gopherstack

150+ AWS services. One Go binary. Milliseconds, not minutes.

Gopherstack is a lightweight, in-memory AWS cloud stack you can run locally. It emulates 150+ AWS service APIs in a single Go binary — no AWS account, no credentials, no network calls — so you can develop and test against realistic AWS behaviour in milliseconds.

Point any AWS SDK, the AWS CLI, Terraform, or the CDK at http://localhost:8000 and it just works. Beyond simple CRUD mocks, Gopherstack implements real cross-service integration: Event Source Mappings, EventBridge Scheduler, EventBridge Pipes, DynamoDB Streams → Lambda, SNS → SQS fan-out, and container-backed Lambda execution.

[!TIP] Gopherstack is significantly faster and lighter than LocalStack, making it ideal for unit and integration tests where speed is critical.

[!IMPORTANT] This project is vibe coded. 🚀 It's built for speed, performance, and developer experience.

Quick Start

Pull and run the image:

docker run -p 8000:8000 ghcr.io/blackbirdworks/gopherstack:latest

Open the built-in web dashboard:

http://localhost:8000/dashboard

Then point any AWS tooling at the endpoint — no credentials required:

aws dynamodb list-tables --endpoint-url http://localhost:8000
aws s3 mb s3://my-bucket --endpoint-url http://localhost:8000

Installation

Docker

docker pull ghcr.io/blackbirdworks/gopherstack:latest
docker run -p 8000:8000 ghcr.io/blackbirdworks/gopherstack:latest

The API and the dashboard are both served on port 8000.

Docker Compose

services:
  gopherstack:
    image: ghcr.io/blackbirdworks/gopherstack:latest
    ports:
      - "8000:8000"
    environment:
      - LOG_LEVEL=info

docker compose up -d

For Lambda support the container needs access to a container runtime — see docs/docker.md.

Testcontainers (Go)

Gopherstack ships a reusable Testcontainers for Go module so you can spin up the whole stack from any Go test suite:

go get github.com/blackbirdworks/gopherstack/modules/gopherstack

import (
    "context"
    "testing"

    "github.com/aws/aws-sdk-go-v2/aws"
    "github.com/aws/aws-sdk-go-v2/config"
    "github.com/aws/aws-sdk-go-v2/credentials"
    "github.com/aws/aws-sdk-go-v2/service/dynamodb"
    "github.com/testcontainers/testcontainers-go"

    gopherstack "github.com/blackbirdworks/gopherstack/modules/gopherstack"
)

func TestMyService(t *testing.T) {
    ctx := context.Background()

    container, err := gopherstack.Run(ctx, gopherstack.DefaultImage)
    if err != nil {
        t.Fatal(err)
    }
    defer testcontainers.TerminateContainer(container)

    endpoint, err := container.BaseURL(ctx)
    if err != nil {
        t.Fatal(err)
    }

    cfg, _ := config.LoadDefaultConfig(ctx,
        config.WithRegion("us-east-1"),
        config.WithCredentialsProvider(
            credentials.NewStaticCredentialsProvider("test", "test", ""),
        ),
    )

    ddb := dynamodb.NewFromConfig(cfg, func(o *dynamodb.Options) {
        o.BaseEndpoint = aws.String(endpoint)
    })

    // … use ddb in your tests
}

Pass environment variables with gopherstack.WithEnv:

container, err := gopherstack.Run(ctx, gopherstack.DefaultImage,
    gopherstack.WithEnv(map[string]string{
        "LOG_LEVEL": "debug",
        "DEMO":      "true",
    }),
)

As a Go library

Use the in-memory backends directly, without any HTTP server:

import "github.com/blackbirdworks/gopherstack/services/dynamodb"

db := dynamodb.NewInMemoryDB()
// Use db for your application logic…

From source

git clone https://github.com/blackbirdworks/gopherstack.git
cd gopherstack
go run .            # serves on :8000

Features

Web Dashboard

A built-in UI at http://localhost:8000/dashboard for inspecting and managing local state:

• DynamoDB — list tables, view details (keys, indexes, item count), run Query and Scan, create tables
• S3 — list buckets, browse files with folder support, upload/download, manage versioning, view object metadata

Configuration

Every setting has a CLI flag and (usually) an equivalent env var; a flag always wins. When --persist is enabled, values loaded from the persisted config file sit between the two: precedence is defaults < persisted config < env vars / CLI flags.

Server

AWS credentials & region overrides

Gopherstack's own AWS SDK clients read a few standard AWS environment variables, so tooling that already exports them (e.g. awslocal) works without remapping. These are not flags.

Per-service engine & provider selection

Lambda & containers

The core Lambda/container-runtime flags — LAMBDA_DOCKER_HOST, LAMBDA_POOL_SIZE, LAMBDA_IDLE_TIMEOUT, CONTAINER_RUNTIME — are documented in Lambda configuration below. A few more exist:

Per-service tuning (janitor intervals & TTLs)

Most services expose a background "janitor" tick interval and TTLs for evicting stale data. These have CLI flags too (run gopherstack serve --help for exact names) but are most commonly set via env var:

DynamoDB

• In-memory storage — blazing fast tables and items
• Secondary indexes — full Global (GSI) and Local (LSI) secondary index support
• Rich querying — sort-key conditions, pagination (Limit, ExclusiveStartKey), ordering
• Efficient scanning — filtering and projection with DynamoDB expressions
• Expression support — expression attribute values and names
• Streams — change capture that can drive Lambda via Event Source Mappings

S3

• Bucket management — full lifecycle for versioned and unversioned buckets
• Object operations — Get, Put, Head, List, multipart uploads
• Versioning & tagging — first-class object versioning and metadata tagging
• Data integrity — automatic checksums (CRC32, CRC32C, SHA1, SHA256)
• Compression — integrated gzip compression for efficient memory usage

Lambda (Zip and Image packaging)

Gopherstack runs real Lambda functions in containers, supporting both Zip (PackageType: Zip) and container image (PackageType: Image) packaging.

• Zip functions — the archive is extracted and run on the matching AWS runtime base image, so standard managed runtimes work unmodified: python3.9–python3.13, nodejs18.x/20.x/22.x, java11/17/21, dotnet8/dotnet9, ruby3.2/3.3, and provided.al2/provided.al2023
• Image functions — provide an ImageUri (an AWS base image or your own)
• Lambda Runtime API — full implementation, so standard AWS base images work as-is
• Invocation modes — RequestResponse (sync) and Event (async / fire-and-forget)
• Warm container pool — configurable per-function pool to cut cold starts
• Reserved concurrency — enforced for both sync and async calls
• Async realism — AWS-realistic retry semantics and dead-letter queues (via SNS/SQS)
• Environment variables — passed straight through to the container

[!IMPORTANT] Both packaging modes require a running Docker (or Podman) daemon to execute invocations. S3-based code delivery and direct Go binary execution on the host are not supported. All other Gopherstack services work without Docker.

# Create an image-based Lambda function
aws lambda create-function \
    --endpoint-url http://localhost:8000 \
    --function-name my-function \
    --package-type Image \
    --code ImageUri=public.ecr.aws/lambda/python:3.12 \
    --role arn:aws:iam::000000000000:role/my-role

# Invoke synchronously
aws lambda invoke \
    --endpoint-url http://localhost:8000 \
    --function-name my-function \
    --payload '{"key":"value"}' \
    response.json

# List functions
aws lambda list-functions --endpoint-url http://localhost:8000

Lambda configuration

Using Podman

Podman works as a drop-in replacement for Docker via its Docker-compatible API socket.

# Enable the Podman socket for your user (rootless, Linux)
systemctl --user enable --now podman.socket

# Point Gopherstack at Podman
export CONTAINER_RUNTIME=podman

# Optional: override the socket path
export CONTAINER_HOST=unix://${XDG_RUNTIME_DIR}/podman/podman.sock

Rootless networking note: in rootless Podman the Docker bridge (172.17.0.1) is not available — use the host's routable IP or host.containers.internal:

export LAMBDA_DOCKER_HOST=host.containers.internal

Set CONTAINER_RUNTIME=auto to probe Docker first, then Podman, and use whichever socket is reachable.

Event Source Mappings (ESM)

Automatically trigger Lambda functions from DynamoDB Streams — Gopherstack manages the polling and invocation for you once an ESM exists. Respects batch size, starting position (TRIM_HORIZON, LATEST), and enable/disable state.

EventBridge Scheduler & Pipes

• Scheduler — recurring or one-time scheduled tasks that trigger AWS targets (Lambda, SQS, SNS, and more)
• Pipes — point-to-point integrations from sources (SQS) to targets (Lambda, Step Functions) with optional filtering and enrichment

Performance & Scalability

• O(1) ARN indexing — tagging and resource lookup use a centralized ARN index, so operations stay fast with thousands of resources
• Memory optimization — struct field alignment and efficient data structures keep the footprint small
• Profile-guided optimization — the binary ships with a PGO profile captured from real workloads (see PGO)

Examples

Complete, runnable examples live in examples/ — each ships a docker-compose.yml and a demo.sh so you can run it end to end.

Running one:

cd examples/kinesis-lambda-aggregator
docker compose up -d
./demo.sh

See examples/README.md for prerequisites and teardown.

Services

Every service links to its own page with a coverage breakdown — audited operations, known gaps, deferred items and resource-leak status — generated from that service's PARITY.md audit.

Parity is the overall grade recorded by that service's most recent audit. PARITY Entries is the number of ops: entries audited in that service's PARITY.md -- a hand-grouped audit unit, not a raw operation count (one entry can name more than one real operation); a dash means the service is tracked by feature family instead. Run make docs to refresh this table.

Compute

Containers

Storage

Database

Networking & Content Delivery

Messaging & Integration

Analytics

Security

Identity & Access

Management & Governance

Developer Tools

Machine Learning

Media

IoT

Migration & Transfer

Azure

Other

Using Gopherstack

AWS CLI

Everything works with the standard AWS CLI — just pass --endpoint-url:

# DynamoDB
aws dynamodb create-table \
    --endpoint-url http://localhost:8000 \
    --table-name Users \
    --attribute-definitions AttributeName=ID,AttributeType=S \
    --key-schema AttributeName=ID,KeyType=HASH \
    --provisioned-throughput ReadCapacityUnits=5,WriteCapacityUnits=5

aws dynamodb list-tables --endpoint-url http://localhost:8000

# S3
aws s3 mb s3://my-bucket --endpoint-url http://localhost:8000
aws s3 cp myfile.txt s3://my-bucket/ --endpoint-url http://localhost:8000
aws s3 ls s3://my-bucket/ --endpoint-url http://localhost:8000

Alternatively set AWS_ENDPOINT_URL=http://localhost:8000 once and drop the flag.

Terraform / OpenTofu

Point the AWS provider at Gopherstack by overriding the service endpoints. No real credentials are needed — any non-empty string works.

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
  }
}

provider "aws" {
  region                      = "us-east-1"
  access_key                  = "test"
  secret_key                  = "test"
  skip_credentials_validation = true
  skip_metadata_api_check     = true
  skip_requesting_account_id  = true

  endpoints {
    dynamodb       = "http://localhost:8000"
    s3             = "http://localhost:8000"
    sqs            = "http://localhost:8000"
    sns            = "http://localhost:8000"
    ssm            = "http://localhost:8000"
    kms            = "http://localhost:8000"
    secretsmanager = "http://localhost:8000"
    iam            = "http://localhost:8000"
    sts            = "http://localhost:8000"
    lambda         = "http://localhost:8000"
    cloudformation = "http://localhost:8000"
    cloudwatch     = "http://localhost:8000"
    cloudwatchlogs = "http://localhost:8000"
    stepfunctions  = "http://localhost:8000"
    eventbridge    = "http://localhost:8000"
    apigateway     = "http://localhost:8000"
  }
}

Terraform uses path-style S3 URLs, so set use_path_style = true on the S3 provider/resource when creating aws_s3_bucket resources.

docker compose up -d   # or: go run .
terraform init
terraform apply

AWS CDK

CDK synthesises CloudFormation locally and deploys it via the AWS SDK, so pointing the SDK at Gopherstack is enough:

export AWS_ENDPOINT_URL=http://localhost:8000
export AWS_ACCESS_KEY_ID=test
export AWS_SECRET_ACCESS_KEY=test
export AWS_DEFAULT_REGION=us-east-1
export CDK_DEFAULT_ACCOUNT=000000000000
export CDK_DEFAULT_REGION=us-east-1

docker compose up -d   # start Gopherstack
cdk bootstrap          # creates the CDKToolkit stack via CloudFormation
cdk deploy

AWS_ENDPOINT_URL is picked up automatically by the AWS SDK v2 used by the CDK CLI.

Documentation

• Quickstart
• Running with Docker
• Migrating from LocalStack
• Architecture
• Examples
• Chaos Testing

Development

Prerequisites: Go 1.26+, Docker or Podman (only for Lambda invocations), AWS CLI (optional).

make all             # lint + all tests with coverage
make test            # unit tests (short mode)
make total-coverage  # unit + integration + E2E with combined coverage
make lint            # linters
make docs            # regenerate the service docs from each PARITY.md
make pgo             # regenerate the PGO profile

Versioning

Releases are tagged v1.<major>.<minor> — a major bump moves the middle number, a minor bump moves the last one. Releases are cut from the Release workflow, which only offers those two increments.

The leading 1 is deliberate and stays put. The Go module path is github.com/blackbirdworks/gopherstack with no /vN suffix, and Go requires any module at major version 2 or higher to carry that suffix in its path. A tag like v18.0.0 is therefore invisible to the Go module proxy and pkg.go.dev — staying on the v1.x.y line keeps go get working without rewriting every import across the tree on each release.

v1.0.x is reserved and must never be reused. An earlier release line published v1.0.0–v1.0.18, and proxy.golang.org caches module versions permanently while sum.golang.org records their checksums — re-tagging one of those numbers would serve the old cached code and break checksum verification for anyone fetching it. Releases therefore start at v1.1.0, which also sorts above the highest cached version. The release workflow enforces both rules and refuses to create a tag that violates them.

Profile-Guided Optimization (PGO)

The repo root ships default.pgo, a CPU profile that Go's Profile-Guided Optimization automatically consumes from the main package directory on every go build — no extra flags. It's captured from a representative workload (heavy DynamoDB GSI/LSI and S3 traffic, plus broad multi-service coverage) so the compiler can optimize the real hot paths.

Regenerate it with:

make pgo

This runs scripts/pgo.sh, which builds the server and the cmd/pgoload load generator, runs the server with pprof enabled, captures CPU profiles while driving load against it, and writes the merged result to default.pgo. It validates the profile with go tool pprof and go build -pgo=auto before finishing. Knobs (capture/load duration, concurrency, …) are environment variables — see the header of scripts/pgo.sh.

Per-PR: if your change measurably shifts the server's hot paths, run make pgo and commit the updated default.pgo alongside it.

CI: a weekly workflow (.github/workflows/pgo.yml) also runs make pgo and opens a pull request with a refreshed profile.

License

Gopherstack is released under the MIT License.