tanujsoni027/goku repository overview

⁠Goku: a local AWS cloud in one Docker image

See your cloud, before you ship your cloud.

Goku is a local AWS cloud for building, testing and learning cloud infrastructure on your machine. You don't need an AWS account, you don't pay an AWS bill, and you don't need cloud credentials.

⁠Install with the CLI (recommended)

macOS / Linux:

curl -fsSL https://tanuj24.github.io/goku/install.sh | sh
goku start

Windows (PowerShell):

irm https://tanuj24.github.io/goku/install.ps1 | iex
goku start

goku start pulls this image, starts it with your data folder (~/.goku/data, or %LOCALAPPDATA%\Goku\data on Windows) and opens the console. Point your AWS CLI and SDKs at it with eval "$(goku env)" (or goku env --shell powershell | Invoke-Expression on Windows).

⁠Or run the image directly

mkdir -p ~/.goku/data
docker run -d --name goku \
  -p 8080:80 -p 4566:4566 -p 5500-5524:5500-5524 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v ~/.goku/data:/app/data \
  -v /tmp/goku-glue:/tmp/goku-glue \
  tanujsoni027/goku:latest

• Console: http://localhost:8080⁠

• AWS endpoint: http://localhost:4566⁠, region us-east-1, any local credentials such as test / test.

• Everything lives in your data folder: every bucket, table, function and job, and the data of its engines too:

  • RDS PostgreSQL databases
  • OpenSearch
  • MSK
  • ECR
  • DocumentDB
  • MemoryDB
  • Amazon MQ
  • Redshift

  Stop Goku, update it or reset Docker, and you resume where you left off. Without the -v …:/app/data, state is kept in the goku-data volume instead.

• Updates: the console shows when a new version is out. Update now replaces the running container with the same settings and data, and rolls back if the new version isn't healthy. GOKU_UPDATE_CHECK=off turns checks off.

• Settings: -e GOKU_SERVICES=all subscribes every service on first start. Every setting is a GOKU_* environment variable.

⁠Upgrading from Mimir

With the CLI, install it (above) and run goku update. It saves your state, moves it into the data folder, renames the mimir container to goku and starts the newest Goku on this image. Your mimir-data volume stays as a backup.

With plain Docker:

docker stop -t 60 mimir
mkdir -p ~/.goku/data
docker cp mimir:/app/data/. ~/.goku/data/    # works with every Mimir version
docker rm mimir
docker pull tanujsoni027/goku:latest
# then the docker run command above

The old names keep working for now and will be removed in a future release. Goku prints a note whenever it meets one.

⁠What's new in Goku 4.1

• Connect AI assistants to your local AWS. Goku serves an MCP server at http://localhost:8080/mcp. Claude Code, Claude Desktop, Cursor, VS Code, Windsurf and other MCP clients can create and inspect resources, call any AWS API, read logs, take snapshots and inject faults, all on your machine.
  • Claude Code: claude mcp add goku -- goku mcp (the goku CLI starts Goku if needed), or claude mcp add --transport http goku http://localhost:8080/mcp.
  • Other clients: goku mcp config <client> prints the setup.
• 25 tools, including aws_call for any operation of the emulated AWS services. There is also an AI assistants page in the console.
• goku CLI 0.5.0: goku mcp and goku mcp config.

⁠What's new in Goku 4.0

• Mimir is now Goku, everywhere, with existing installs moving over by themselves.
• Update from the console: a banner when a new version is out, and Update now with automatic rollback.
• Everything in a folder on disk, databases included. Existing volumes move into it by themselves.
• Delete a service removes every container it started, and the Resource Center lists leftover containers from older versions.
• goku CLI 0.4: goku update --cli, goku data, and a daily notice when a new version is out.
• Fixed: DynamoDB items could go missing after a restart or snapshot restore when another account used DynamoDB first.
• 73 AWS-compatible services and 60 console services, with one-click sample data on every service page.
• Start light, subscribe to what you use: core services on first start; add others (or presets) on the Services page.
• Resource Center: every running engine container with live memory and CPU, plus pause, stop and cleanup.
• IAM Policy Lab: effective access with evidence, policy drafts with semantic diffs and blast radius, and IAM tests.
• AWS Glue 6.0 and 5.1, DynamoDB vector search, every current Lambda runtime on arm64 and x86_64, and a rebuilt ECS.
• Developer tools:
  • Lambda step-through debugging from VS Code, IntelliJ, PyCharm and GoLand
  • environment snapshots
  • fault injection
  • least-privilege IAM from real activity
  • AWS Organizations with SCPs
  • request journeys with DLQ redrive
  • cloning staging from a real account (read-only)
  • Step Functions testing
  • Terraform, CDK and Pulumi support with a pre-deploy cost and IAM review
  • an operation coverage map

⁠Real engines, not mocks

RDS runs real PostgreSQL, MySQL and MariaDB. ElastiCache and MemoryDB run Valkey and Redis, DocumentDB runs MongoDB, and Amazon MQ runs RabbitMQ and ActiveMQ. EKS runs k3s, EMR Serverless and Glue run Spark, MWAA runs Airflow, and Lambda and ECS run real containers. That's why the Docker socket mount is needed.

The data endpoints use a dedicated port range that won't clash with a local Redis or Postgres:

• 5500–5524: RDS, ElastiCache and Neptune. These are proxied, so the run command includes -p 5500-5524:5500-5524.
• Other engines (up to 5659): bound on the host automatically.
• 5380: Route 53 DNS.

⁠Tags

• latest, v4, 4.1.0: Goku 4.1, multi-arch (linux/amd64, linux/arm64)
• 4.0.0: Goku 4.0

Earlier releases were published as tanujsoni027/mimir-aws, which also receives the same Goku releases for now.

⁠Requirements

• Docker Desktop (macOS, Windows) or Docker Engine / Docker Desktop (Linux)
• Docker socket access at /var/run/docker.sock (needed for Lambda, RDS, ECS, Glue and the other engine-backed services)
• Ports 8080 (console) and 4566 (AWS endpoint) free

⁠Links

• Website: https://tanuj24.github.io/goku/⁠
• Install guide: https://tanuj24.github.io/goku/install.html⁠
• Issues & support: https://github.com/tanuj24/goku/issues⁠

Goku is free to use.