Docker

Quick run

Pull the prebuilt image and start Nakama:

docker pull ghcr.io/ahmadrosid/nakama:latest
docker run -d -p 4310:4310 -v nakama-data:/nakama/data --name nakama ghcr.io/ahmadrosid/nakama:latest

Open http://localhost:4310. The container serves the API, web dashboard, and platform workers together.

Data is stored at /nakama/data inside the container. The -v nakama-data:/nakama/data volume persists orgs, profiles, sessions, provider settings, and the local SQLite database across restarts.

Build from source

From the repository root:

./scripts/docker-build-run.sh

The script uses docker buildx (default linux/amd64), then starts the container.

Configuration

The data root follows NAKAMA_CONFIG_DIR when set. By default it is /nakama/data in the container (mapped to your Docker volume).

On first run, complete the setup wizard in the browser and add your LLM provider. See Providers and First-time setup.

To skip the setup wizard on a fresh data volume, set all three admin seed variables before the first boot. Nakama creates the admin account, a Personal org (override with NAKAMA_SEED_ORG_NAME), and an OpenCode Zen provider. Self-hosted installs without these variables behave as today.

Variable	Required	Purpose
`NAKAMA_SEED_ADMIN_EMAIL`	Yes (with the other two)	Platform admin email
`NAKAMA_SEED_ADMIN_NAME`	Yes (with the other two)	Platform admin display name
`NAKAMA_SEED_ADMIN_PASSWORD`	Yes (with the other two)	Platform admin password (min 8 characters)
`NAKAMA_SEED_ORG_NAME`	No	Organization name (default `Personal`)

Partial seed config fails boot with a clear error. Restarting a seeded instance is a no-op (idempotent).

docker run -d -p 4310:4310 -v nakama-data:/nakama/data \
  -e NAKAMA_SEED_ADMIN_EMAIL=admin@example.com \
  -e NAKAMA_SEED_ADMIN_NAME=Admin \
  -e NAKAMA_SEED_ADMIN_PASSWORD=seedpass123 \
  --name nakama ghcr.io/ahmadrosid/nakama:latest

Reset a local Docker install

To remove the container, volume, and image and start fresh:

./scripts/docker-destroy.sh
./scripts/docker-build-run.sh

Optional: CloakBrowser with agent-browser

The image does not include CloakBrowser. Stock Chrome from agent-browser install still works inside the container when you use the dashboard Install path.

To use Cloak as the Chromium behind agent-browser, bind-mount the Cloak binary and pass the same host env Nakama's bash tool already inherits:

docker run -d -p 4310:4310 -v nakama-data:/nakama/data \
  -v /path/to/cloak-chromium:/cloak/chromium:ro \
  -e AGENT_BROWSER_EXECUTABLE_PATH=/cloak/chromium \
  -e AGENT_BROWSER_ARGS="<copy from Cloak's agent-browser example>" \
  --name nakama ghcr.io/ahmadrosid/nakama:latest

See Agent browser.

Next steps

Quickstart — first-run flow from zero
Backup and restore — export and restore your data root
Providers — LLM API keys and models