Install Goku

The goku CLI — macOS, Linux and Windows

The CLI installs natively on each platform and runs Goku in Docker for you — no docker commands to write. It installs the goku command, plus mimir, its former name, as a deprecated alias (details).

macOS and Linux

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

Windows (PowerShell)

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

Start your local cloud

$ goku start

goku start downloads the image on first run, starts Goku and opens the web console at http://localhost:8080. Your AWS CLI, SDKs and apps talk to http://localhost:4566 — point them at it with one command.

The CLI also drives a running Goku: goku services, goku ready, goku snapshot, goku chaos, goku iam and goku lambda debug. Run goku help <command> for the details.

Point your AWS CLI and SDKs at Goku

goku env sets AWS_ENDPOINT_URL, AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY (test / test) and AWS_REGION, so the AWS CLI v2 and every AWS SDK talk to Goku with no code changes.

macOS and Linux

$ eval "$(goku env)"

Windows (PowerShell)

PS> goku env --shell powershell | Invoke-Expression

Then aws s3 ls lists your local buckets. On macOS and Linux, eval "$(goku env --unset)" switches back to real AWS. To configure a tool by hand, use the endpoint http://localhost:4566, region us-east-1 and any local credentials such as test / test.

Next, create your first bucket, table, queue and function with the run AWS locally guide.

Connect an AI assistant

Goku serves an MCP server at http://localhost:8080/mcp, so AI assistants can work with your local AWS too, and nothing they change reaches real AWS. For Claude Code:

$ claude mcp add goku -- goku mcp

goku mcp starts Goku if it isn't running, and goku mcp config prints the setup for Claude Desktop, Cursor, VS Code and Windsurf. The MCP guide covers every client and the 25 tools.

Docker without the CLI

Already have Docker? Run the image directly — it's the same image the CLI runs.

macOS and Linux (bash)

$ 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

Windows (PowerShell)

PS> New-Item -ItemType Directory -Force "$env:LOCALAPPDATA\Goku\data" | Out-Null
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 "$env:LOCALAPPDATA\Goku\data:/app/data" `
  -v /tmp/goku-glue:/tmp/goku-glue `
  tanujsoni027/goku:latest

The web console is at http://localhost:8080 and the AWS-compatible endpoint at http://localhost:4566. Add -e GOKU_SERVICES=all to start with every service subscribed, and -p 2000:2000/udp to send X-Ray segments from apps on your host.

Requirements

Upgrading an existing install

Everything you created carries over. The easiest way is the CLI: install it (the commands above), then run

$ goku update

goku update stops your mimir container gracefully so it saves its state, moves that state into your data folder (~/.goku/data, or %LOCALAPPDATA%\Goku\data on Windows) and starts the newest Goku, now named goku and running tanujsoni027/goku, on the same ports. Your old mimir-data volume is kept as a backup. Engine data (databases, search domains, brokers, the ECR registry) moves into the folder by itself when each engine next starts.

With plain Docker

Stop the old mimir container gracefully, copy its data into a folder, then start the new image on that folder as goku. docker cp works with every Mimir version, including early v3 builds that kept state only inside the container:

$ docker stop -t 60 mimir
mkdir -p ~/.goku/data
docker cp mimir:/app/data/. ~/.goku/data/
docker rm mimir
docker pull tanujsoni027/goku:latest
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

On Windows, use "$env:LOCALAPPDATA\Goku\data" as the folder, as in the Docker commands above. Check that the folder holds your data (for example an s3 folder) before the docker rm; your mimir-data volume, if you have one, is left untouched as a backup. Starting the new image on an empty folder also works: it copies the state kept in the mimir-data volume into the folder by itself.

From Goku 4.0 on, the console tells you when a new version is out and updates itself with Update now.

Old and new names

Goku (formerly Mimir) is the same product with a new name, and every name is Goku now. Start using the goku names. The old names keep working for now, existing installs move over automatically, and the old names will be removed in a future release.

• The installer upgrades an existing install in place and installs both commands, goku and mimir. Every example on this site uses goku.
• The mimir command is deprecated and will be removed in a future release. Until then it keeps working: it runs goku and prints a short note on stderr asking you to switch. Set GOKU_NO_DEPRECATION_NOTICE=1 to silence the note.
• Your install moves over by itself: goku update (or Update now in the console) renames the mimir container to goku, moves it to the tanujsoni027/goku image and your state into the data folder, and keeps the mimir-data volume as a backup.
• Your settings still work: every MIMIR_* variable is still read, and Goku prints a note for each one, asking you to rename it to GOKU_*. When both are set, the GOKU_* one wins.

Updating & uninstalling

Updating

From the console: when a new version is out, the console shows a banner; Update now downloads it and replaces the running Goku with the same ports, settings and data. If the new version doesn't come up healthy within 3 minutes, Goku rolls back to the version you had. The version menu in the top bar has Check for updates.

From a terminal: goku update updates Goku, and goku update --cli updates the CLI. The CLI mentions new versions at most once a day.

With plain Docker: stop the container gracefully, pull the new image and run the docker run command again with the same data folder:

$ docker stop -t 60 goku && docker rm goku
docker pull tanujsoni027/goku:latest

How update checks work: Goku downloads one small static file, releases.json, from this site. Nothing about you or your setup is sent. Set GOKU_UPDATE_CHECK=off to turn the checks off.

Backing up and moving

Stop Goku and copy the data folder; that is the whole backup. Copy it to another machine and start Goku there with the same folder to carry on. On Linux, engine folders belong to the users their engines run as, so copy them as root to keep their owners.

Uninstalling

goku uninstall removes Goku — its container and only the engine containers of this installation — and keeps your data folder, so a later reinstall finds your resources intact. Add --purge to also delete the data folder.

Troubleshooting

Start with the built-in checkup — it checks Docker, ports, saved state, curl and the backend's features, and tells you what's missing:

$ goku doctor

Port conflicts

If something already uses port 8080 or 4566, pick other ports with GOKU_CONSOLE_PORT and GOKU_EDGE_PORT:

$ GOKU_CONSOLE_PORT=9090 GOKU_EDGE_PORT=4567 goku start

PS> $env:GOKU_CONSOLE_PORT = "9090"; $env:GOKU_EDGE_PORT = "4567"; goku start

Data endpoints live in a dedicated 5500–5659 range (RDS, ElastiCache and Neptune through the published 5500–5524 ports; the rest bind automatically), so they won't clash with a local Redis, Postgres or Elasticsearch.

Still stuck?

Open an issue at github.com/tanuj24/goku/issues — include the output of goku doctor and goku logs.