Nov 18, 20266 min read

How to Run S3 Locally: MinIO, LocalStack and Local Buckets

The options for an S3-compatible endpoint on a laptop in 2026, what changed with MinIO and LocalStack, and how to keep local uploads and production S3 on the same code path.

Illustration for How to Run S3 Locally: MinIO, LocalStack and Local Buckets

For years the answer to "how do I run S3 locally" was docker run minio/minio, and every tutorial pointed the AWS SDK at localhost:9000 with path-style addressing.

That stopped being a safe default in 2026: the MinIO repository is marked as no longer maintained and the Docker Hub images disappeared in September, and LocalStack now needs an account token even for the free tier.

This guide compares what is left for a local S3 endpoint, shows the SDK configuration that makes the same upload code work locally and against real S3, and covers the case where the bucket is declared in application code so there is no endpoint to configure at all.

Local S3 options at a glance

Encore bucketFlociLocalStackGarage / SeaweedFSMinIO (archived)
What runs locallyObjects on local disk via encore runAWS emulator containerAWS emulator containerS3-compatible storage serverS3-compatible storage server
Account or tokenNone for localNoneLocalStack account and auth tokenNoneNone
SDK endpoint configNot neededhttp://localhost:4566http://localhost:4566Server addressServer address
Production targetS3 or GCS in your accountReal S3, configured separatelyReal S3, configured separatelyReal S3, configured separatelyReal S3, configured separately
Maintenance statusMaintainedMaintainedMaintainedMaintainedSource only, no new images

What changed with MinIO and LocalStack

MinIO Community Edition moved to source-only releases in October 2025, with the maintainers saying the project would only receive bug fixes and CVE patches. The README now opens with "this repository is no longer maintained" and points to the commercial AIStor editions. In September 2026 the minio/minio and minio/mc images stopped pulling from Docker Hub, which broke CI jobs that had pinned exact release tags. Building from source still works, but a local dependency that you have to patch yourself is a poor trade for a dev loop.

LocalStack for AWS has shipped as a single image since its March 2026 release, and that image requires a LocalStack account and an auth token, including in CI, as covered in LocalStack alternatives. The S3 emulation is still good; the cost is a token in every pipeline and every new laptop.

Point the AWS SDK at a local endpoint

Every S3-compatible server works the same way from the application side: a custom endpoint, path-style addressing and dummy credentials. Keep those three settings in one place and switch them off in production, so the upload code does not branch.

// storage.ts import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3"; const local = process.env.S3_ENDPOINT; // e.g. http://localhost:4566 export const s3 = new S3Client({ region: process.env.AWS_REGION ?? "eu-central-1", ...(local && { endpoint: local, forcePathStyle: true, credentials: { accessKeyId: "test", secretAccessKey: "test" }, }), }); export async function saveAvatar(userId: string, body: Buffer) { await s3.send(new PutObjectCommand({ Bucket: process.env.AVATAR_BUCKET!, Key: `avatars/${userId}.png`, Body: body, ContentType: "image/png", })); }

The local server also needs the bucket to exist before the first upload, so a docker compose file usually grows an init container that runs aws s3 mb against the local endpoint. That init step and the environment variables above are the parts that drift from production: the production bucket name comes from Terraform outputs, the local one from a compose file, and nobody notices until a new prefix or a CORS rule exists in one place only.

Floci

Floci is an MIT-licensed AWS emulator that serves its services on http://localhost:4566, the same port LocalStack uses, and runs without an account or token. For S3 it is a drop-in swap in a compose file that already targets LocalStack.

~
$ docker run -d --name floci -p 4566:4566 floci/floci$ aws --endpoint-url http://localhost:4566 s3 mb s3://avatars$ S3_ENDPOINT=http://localhost:4566 AVATAR_BUCKET=avatars npm run dev

Best fit: teams that already have a LocalStack-shaped setup and want to drop the auth token.

LocalStack

LocalStack's S3 emulation remains the most complete and the most documented, and if you already pay for LocalStack for other services, keeping S3 there is the least work. The token requirement applies to every environment that pulls the image, so store it as a CI secret and document it in onboarding.

Best fit: teams already licensed for LocalStack that emulate many AWS services, not only S3.

Garage and SeaweedFS

Garage and SeaweedFS are storage servers rather than AWS emulators, so they are closer to what MinIO used to be. Both expose an S3 API and run as a single container for development. They take more setup than an emulator (Garage needs a layout and access keys created through its CLI) and only cover S3, which is fine if S3 is the only AWS API the app calls.

Best fit: teams that want a long-lived S3-compatible store on a dev server or in CI, not a full AWS emulator.

Encore buckets on local disk

Encore

Encore brings infrastructure from code to the service that writes the files, and with an Encore bucket there is no local endpoint to configure. You declare the bucket in TypeScript or Go, encore run stores its objects on the local filesystem, and integration tests use an in-memory storage backend. On deploy to your own AWS account Encore provisions an S3 bucket with a unique name and provisions an IAM role for the service, or a service account on GCP where it uses Cloud Storage.

Set up the app

Get started
brew install encoredev/tap/encore &&
encore app create
Copy

Run in your terminal to get started locally.

// avatars/avatars.ts import { api } from "encore.dev/api"; import { getAuthData } from "~encore/auth"; import { Bucket } from "encore.dev/storage/objects"; export const avatars = new Bucket("avatars", { versioned: false }); export const upload = api( { expose: true, auth: true, method: "POST", path: "/avatars" }, async (p: { pngBase64: string }): Promise<{ key: string; size: number }> => { const { userID } = getAuthData()!; const key = `${userID}.png`; const attrs = await avatars.upload(key, Buffer.from(p.pngBase64, "base64"), { contentType: "image/png", }); return { key, size: attrs.size }; }, ); export const signedUpload = api( { expose: true, auth: true, method: "POST", path: "/avatars/upload-url" }, async (): Promise<{ url: string }> => { const { userID } = getAuthData()!; const { url } = await avatars.signedUploadUrl(`${userID}.png`, { ttl: 900 }); return { url }; }, );

Both endpoints require an auth handler and derive the object key from getAuthData(), so a caller cannot write or sign an upload for another user. The same upload, download, list and signedUploadUrl calls run against local disk under encore run and against S3 after deploy, so there is no endpoint switch to forget. Public buckets are a flag on the declaration (public: true), and on AWS Encore puts CloudFront in front of them.

A coding agent can add a new bucket and the endpoint that writes to it in one change and exercise it with encore run, without a compose file or an S3 endpoint variable to keep in sync.

Best fit: TypeScript or Go backends that want local uploads and production S3 or Cloud Storage on one code path, in their own AWS or GCP account.

Which one to pick

If the app talks to S3 through the raw AWS SDK and you want the smallest change from an old MinIO or LocalStack setup, Floci is the quickest swap and LocalStack is the safe choice if you already pay for it. If you want a real storage server that will stay up between test runs, Garage or SeaweedFS fill the gap MinIO left. If the backend is TypeScript or Go and the bucket can be declared in code, an Encore bucket removes the local endpoint entirely.

Frequently asked questions

How do I run S3 locally for development?

Run an S3-compatible server on your machine and point the AWS SDK at it with a custom endpoint and path-style addressing. Floci, LocalStack (with an auth token since March 2026), Garage and SeaweedFS all expose the S3 API. If the app uses an Encore bucket, encore run stores objects on local disk and no endpoint configuration is needed.

Can I still use the MinIO Docker image for local S3?

No. MinIO Community Edition became a source-only distribution in late 2025, the repository is marked as no longer maintained, and the minio/minio images stopped pulling from Docker Hub in September 2026. You can build an image from the archived source, but you then own every patch.

Deploy to your cloud on AWS and Google Cloud
without managing infrastructure

Encore lets developers and agents define application infrastructure directly in code, then automatically provisions it from local development to production in your AWS or GCP account.

~/orders — claude
Claude Code
Claude Code v2.1.180Opus 5.5~/orders