## Quick run

Pull the prebuilt image and start Nakama:

```bash
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:

```bash
./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](/providers) and [First-time setup](/first-time-setup).

### First-boot seed (optional)

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).

```bash
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:

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

## Optional: CloakBrowser with agent-browser

The image does not include [CloakBrowser](https://github.com/CloakHQ/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:

```bash
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](/agent-browser#3-optional-cloakbrowser-for-antibot-sites).

## Next steps

- [Quickstart](/quickstart) — first-run flow from zero
- [Backup and restore](/backup-restore) — export and restore your data root
- [Providers](/providers) — LLM API keys and models