S3

Lightweight, dependency-free fake of AWS S3 that speaks the real S3 REST API (XML wire protocol), so application code using @aws-sdk/client-s3 can run against it with zero cost and zero side effects.

Quick Start

Start the server:

import { S3Server } from "./services/s3/src/server.js";

const server = new S3Server(4566);
await server.start();
// ... use it ...
await server.stop();

Connect with the real AWS SDK client:

import {
  S3Client,
  CreateBucketCommand,
  PutObjectCommand,
  GetObjectCommand,
} from "@aws-sdk/client-s3";

const s3 = new S3Client({
  region: "us-east-1",
  endpoint: "http://127.0.0.1:4566",
  forcePathStyle: true, // recommended for the fake
  credentials: { accessKeyId: "parlel", secretAccessKey: "parlel" },
});

await s3.send(new CreateBucketCommand({ Bucket: "my-bucket" }));
await s3.send(new PutObjectCommand({ Bucket: "my-bucket", Key: "hello.txt", Body: "hello world" }));

const obj = await s3.send(new GetObjectCommand({ Bucket: "my-bucket", Key: "hello.txt" }));
console.log(await obj.Body.transformToString()); // "hello world"

Addressing

Both addressing styles are supported:

• Path-style (recommended): http://127.0.0.1:4566/{bucket}/{key} — set forcePathStyle: true.
• Virtual-hosted-style: http://{bucket}.s3.amazonaws.com/{key} — resolved from the Host header.

Authentication

SigV4 signatures are accepted but not verified (any credentials work). This matches LocalStack-style local development.

Access via Parlel Sandbox

S3 is an HTTP service, so inside a Parlel sandbox it is exposed directly at its own Daytona preview URL (not through the MCP parlel_execute tool, which is for TCP database services). Point any @aws-sdk/client-s3 client — or plain HTTP — at the preview URL from the sandbox's Connect panel:

# the preview token comes from the Connect panel / GET /connection
curl -X PUT "$S3_URL/my-bucket" -H "x-daytona-preview-token: $TOKEN"
curl -X PUT "$S3_URL/my-bucket/hello.txt" -H "x-daytona-preview-token: $TOKEN" --data "hello world"
curl "$S3_URL/my-bucket/hello.txt" -H "x-daytona-preview-token: $TOKEN"   # -> hello world

Internal / Health Endpoints

These are not part of the S3 API; they support local tooling.

You can also reset programmatically via server.reset().

Implemented Operations

Service

Bucket — core

Bucket — configuration

Configuration documents (CORS, lifecycle, encryption, website) are stored and returned verbatim so the SDK round-trips them faithfully.

Object — core

Object — listing

Object — tagging / ACL / attributes

Multipart uploads

Surface coverage

This emulator faithfully replicates the API surface most application code and agents exercise. Anything below the supported lines is either an intentional design choice for a fast, zero-cost local emulator (✓ By design) or a candidate for a future release (⟳ Roadmap) — never a silent inaccuracy.

Legend: ✅ fully supported · ◐ accepted (stored, not strictly enforced) · ✓ by design · ⟳ on the roadmap.

Error Codes & Shapes

Errors use the standard S3 XML envelope:

<?xml version="1.0" encoding="UTF-8"?>
<Error>
  <Code>NoSuchKey</Code>
  <Message>The specified key does not exist.</Message>
  <Key>missing.txt</Key>
  <Resource>/my-bucket/missing.txt</Resource>
  <RequestId>…</RequestId>
  <HostId>…</HostId>
</Error>

RequestId and HostId in the body match the x-amz-request-id and x-amz-id-2 response headers, just like the real S3 API.

Environment Variables

The manifest advertises these defaults for clients/tooling:

Configuration — test.env

Copy these into your test.env (used by the bridge sidecar flow). Tokens are Parlel's seeded test credentials — any non-empty value is accepted by the emulator, so you rarely need to change them. Swap in real credentials only when pointing at the live service in prod.env.

AWS_ACCESS_KEY_ID=parlel
AWS_SECRET_ACCESS_KEY=parlel
AWS_REGION=us-east-1
AWS_ENDPOINT_URL_S3=http://parlel-bridge:4566
AWS_S3_FORCE_PATH_STYLE=true