> ## Documentation Index
> Fetch the complete documentation index at: https://agdiai-597e782f.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Docker

# Docker (optional)

Docker is **optional**. Use it only if you want a containerized gateway or to validate the Docker flow.

## Is Docker right for me?

* **Yes**: you want an isolated, throwaway gateway environment or to run Agdi on a host without local installs.
* **No**: you are running on your own machine and just want the fastest dev loop. Use the normal install flow instead.
* **Sandboxing note**: agent sandboxing uses Docker too, but it does **not** require the full gateway to run in Docker. See [Sandboxing](https://agdiai-597e782f.mintlify.site/gateway/sandboxing.md).

## Prerequisites

* Docker Desktop (or Docker Engine) + Docker Compose v2
* At least 2 GB RAM for image build (`pnpm install` may be OOM-killed on 1 GB hosts with exit 137)
* Enough disk for images and logs
* If running on a VPS/public host, review
  [Security hardening for network exposure](https://agdiai-597e782f.mintlify.site/gateway/security.md),
  especially Docker `DOCKER-USER` firewall policy.

## Containerized Gateway

**1. Build the image**

From the repo root, run the setup script:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
./scripts/docker/setup.sh
```

This builds the gateway image locally. To use a pre-built image instead:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
export OPENCLAW_IMAGE="ghcr.io/agdi/agdi:latest"
./scripts/docker/setup.sh
```

Pre-built images are published at the
[GitHub Container Registry](https://github.com/agdi/agdi/pkgs/container/agdi).
Common tags: `main`, `latest`, `<version>` (e.g. `2026.2.26`).

**2. Complete onboarding**

The setup script runs onboarding automatically. It will:

* prompt for provider API keys
* generate a gateway token and write it to `.env`
* start the gateway via Docker Compose

During setup, pre-start onboarding and config writes run through
`agdi-gateway` directly. `agdi-cli` is for commands you run after
the gateway container already exists.

**3. Open the Control UI**

Open `http://127.0.0.1:18789/` in your browser and paste the token into
Settings.

Need the URL again?

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
docker compose run --rm agdi-cli dashboard --no-open
```

**4. Configure channels (optional)**

Use the CLI container to add messaging channels:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# WhatsApp (QR)
docker compose run --rm agdi-cli channels login

# Telegram
docker compose run --rm agdi-cli channels add --channel telegram --token "<token>"

# Discord
docker compose run --rm agdi-cli channels add --channel discord --token "<token>"
```

Docs: [WhatsApp](https://agdiai-597e782f.mintlify.site/channels/whatsapp.md), [Telegram](https://agdiai-597e782f.mintlify.site/channels/telegram.md), [Discord](https://agdiai-597e782f.mintlify.site/channels/discord.md)

### Manual flow

If you prefer to run each step yourself instead of using the setup script:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
docker build -t agdi:local -f Dockerfile .
docker compose run --rm --no-deps --entrypoint node agdi-gateway \
  dist/index.js onboard --mode local --no-install-daemon
docker compose run --rm --no-deps --entrypoint node agdi-gateway \
  dist/index.js config set gateway.mode local
docker compose run --rm --no-deps --entrypoint node agdi-gateway \
  dist/index.js config set gateway.bind lan
docker compose run --rm --no-deps --entrypoint node agdi-gateway \
  dist/index.js config set gateway.controlUi.allowedOrigins \
  '["http://localhost:18789","http://127.0.0.1:18789"]' --strict-json
docker compose up -d agdi-gateway
```

> [!NOTE]
>
> Run `docker compose` from the repo root. If you enabled `OPENCLAW_EXTRA_MOUNTS`
> or `OPENCLAW_HOME_VOLUME`, the setup script writes `docker-compose.extra.yml`;
> include it with `-f docker-compose.yml -f docker-compose.extra.yml`.

> [!NOTE]
>
> Because `agdi-cli` shares `agdi-gateway`'s network namespace, it is a
> post-start tool. Before `docker compose up -d agdi-gateway`, run onboarding
> and setup-time config writes through `agdi-gateway` with
> `--no-deps --entrypoint node`.

### Environment variables

The setup script accepts these optional environment variables:

| Variable | Purpose |
| - | - |
| `OPENCLAW_IMAGE` | Use a remote image instead of building locally |
| `OPENCLAW_DOCKER_APT_PACKAGES` | Install extra apt packages during build (space-separated) |
| `OPENCLAW_EXTENSIONS` | Pre-install extension deps at build time (space-separated names) |
| `OPENCLAW_EXTRA_MOUNTS` | Extra host bind mounts (comma-separated `source:target[:opts]`) |
| `OPENCLAW_HOME_VOLUME` | Persist `/home/node` in a named Docker volume |
| `OPENCLAW_SANDBOX` | Opt in to sandbox bootstrap (`1`, `true`, `yes`, `on`) |
| `OPENCLAW_DOCKER_SOCKET` | Override Docker socket path |

### Health checks

Container probe endpoints (no auth required):

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
curl -fsS http://127.0.0.1:18789/healthz   # liveness
curl -fsS http://127.0.0.1:18789/readyz     # readiness
```

The Docker image includes a built-in `HEALTHCHECK` that pings `/healthz`.
If checks keep failing, Docker marks the container as `unhealthy` and
orchestration systems can restart or replace it.

Authenticated deep health snapshot:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
docker compose exec agdi-gateway node dist/index.js health --token "$OPENCLAW_GATEWAY_TOKEN"
```

### LAN vs loopback

`scripts/docker/setup.sh` defaults `OPENCLAW_GATEWAY_BIND=lan` so host access to
`http://127.0.0.1:18789` works with Docker port publishing.

* `lan` (default): host browser and host CLI can reach the published gateway port.
* `loopback`: only processes inside the container network namespace can reach
  the gateway directly.

> [!NOTE]
>
> Use bind mode values in `gateway.bind` (`lan` / `loopback` / `custom` /
> `tailnet` / `auto`), not host aliases like `0.0.0.0` or `127.0.0.1`.

### Storage and persistence

Docker Compose bind-mounts `OPENCLAW_CONFIG_DIR` to `/home/node/.agdi` and
`OPENCLAW_WORKSPACE_DIR` to `/home/node/.agdi/workspace`, so those paths
survive container replacement.

For full persistence details on VM deployments, see
[Docker VM Runtime - What persists where](https://agdiai-597e782f.mintlify.site/install/docker-vm-runtime.md#what-persists-where).

**Disk growth hotspots:** watch `media/`, session JSONL files, `cron/runs/*.jsonl`,
and rolling file logs under `/tmp/agdi/`.

### Shell helpers (optional)

For easier day-to-day Docker management, install `ClawDock`:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
mkdir -p ~/.clawdock && curl -sL https://raw.githubusercontent.com/agdi/agdi/main/scripts/shell-helpers/clawdock-helpers.sh -o ~/.clawdock/clawdock-helpers.sh
echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc
```

Then use `clawdock-start`, `clawdock-stop`, `clawdock-dashboard`, etc. Run
`clawdock-help` for all commands.
See the [`ClawDock` Helper README](https://github.com/agdi/agdi/blob/main/scripts/shell-helpers/README.md).

> [accordion] Enable agent sandbox for Docker gateway
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> export OPENCLAW_SANDBOX=1
> ./scripts/docker/setup.sh
> ```
>
> Custom socket path (e.g. rootless Docker):
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> export OPENCLAW_SANDBOX=1
> export OPENCLAW_DOCKER_SOCKET=/run/user/1000/docker.sock
> ./scripts/docker/setup.sh
> ```
>
> The script mounts `docker.sock` only after sandbox prerequisites pass. If
> sandbox setup cannot complete, the script resets `agents.defaults.sandbox.mode`
> to `off`.

> [accordion] Automation / CI (non-interactive)
>
> Disable Compose pseudo-TTY allocation with `-T`:
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> docker compose run -T --rm agdi-cli gateway probe
> docker compose run -T --rm agdi-cli devices list --json
> ```

> [accordion] Shared-network security note
>
> `agdi-cli` uses `network_mode: "service:agdi-gateway"` so CLI
> commands can reach the gateway over `127.0.0.1`. Treat this as a shared
> trust boundary. The compose config drops `NET_RAW`/`NET_ADMIN` and enables
> `no-new-privileges` on `agdi-cli`.

> [accordion] Permissions and EACCES
>
> The image runs as `node` (uid 1000). If you see permission errors on
> `/home/node/.agdi`, make sure your host bind mounts are owned by uid 1000:
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> sudo chown -R 1000:1000 /path/to/agdi-config /path/to/agdi-workspace
> ```

> [accordion] Faster rebuilds
>
> Order your Dockerfile so dependency layers are cached. This avoids re-running
> `pnpm install` unless lockfiles change:
>
> ```dockerfile theme={"theme":{"light":"min-light","dark":"min-dark"}}
> FROM node:24-bookworm
> RUN curl -fsSL https://bun.sh/install | bash
> ENV PATH="/root/.bun/bin:${PATH}"
> RUN corepack enable
> WORKDIR /app
> COPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./
> COPY ui/package.json ./ui/package.json
> COPY scripts ./scripts
> RUN pnpm install --frozen-lockfile
> COPY . .
> RUN pnpm build
> RUN pnpm ui:install
> RUN pnpm ui:build
> ENV NODE_ENV=production
> CMD ["node","dist/index.js"]
> ```

> [accordion] Power-user container options
>
> The default image is security-first and runs as non-root `node`. For a more
> full-featured container:
>
> 1. **Persist `/home/node`**: `export OPENCLAW_HOME_VOLUME="agdi_home"`
> 2. **Bake system deps**: `export OPENCLAW_DOCKER_APT_PACKAGES="git curl jq"`
> 3. **Install Playwright browsers**:
>    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
>    docker compose run --rm agdi-cli \
>      node /app/node_modules/playwright-core/cli.js install chromium
>    ```
> 4. **Persist browser downloads**: set
>    `PLAYWRIGHT_BROWSERS_PATH=/home/node/.cache/ms-playwright` and use
>    `OPENCLAW_HOME_VOLUME` or `OPENCLAW_EXTRA_MOUNTS`.

> [accordion] OpenAI Codex OAuth (headless Docker)
>
> If you pick OpenAI Codex OAuth in the wizard, it opens a browser URL. In
> Docker or headless setups, copy the full redirect URL you land on and paste
> it back into the wizard to finish auth.

> [accordion] Base image metadata
>
> The main Docker image uses `node:24-bookworm` and publishes OCI base-image
> annotations including `org.opencontainers.image.base.name`,
> `org.opencontainers.image.source`, and others. See
> [OCI image annotations](https://github.com/opencontainers/image-spec/blob/main/annotations.md).

### Running on a VPS?

See [Hetzner (Docker VPS)](https://agdiai-597e782f.mintlify.site/install/hetzner.md) and
[Docker VM Runtime](https://agdiai-597e782f.mintlify.site/install/docker-vm-runtime.md) for shared VM deployment steps
including binary baking, persistence, and updates.

## Agent Sandbox

When `agents.defaults.sandbox` is enabled, the gateway runs agent tool execution
(shell, file read/write, etc.) inside isolated Docker containers while the
gateway itself stays on the host. This gives you a hard wall around untrusted or
multi-tenant agent sessions without containerizing the entire gateway.

Sandbox scope can be per-agent (default), per-session, or shared. Each scope
gets its own workspace mounted at `/workspace`. You can also configure
allow/deny tool policies, network isolation, resource limits, and browser
containers.

For full configuration, images, security notes, and multi-agent profiles, see:

* [Sandboxing](https://agdiai-597e782f.mintlify.site/gateway/sandboxing.md) -- complete sandbox reference
* [OpenShell](https://agdiai-597e782f.mintlify.site/gateway/openshell.md) -- interactive shell access to sandbox containers
* [Multi-Agent Sandbox and Tools](https://agdiai-597e782f.mintlify.site/tools/multi-agent-sandbox-tools.md) -- per-agent overrides

### Quick enable

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // off | non-main | all
        scope: "agent", // session | agent | shared
      },
    },
  },
}
```

Build the default sandbox image:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
scripts/sandbox-setup.sh
```

## Troubleshooting

> [accordion] Image missing or sandbox container not starting
>
> Build the sandbox image with
> [`scripts/sandbox-setup.sh`](https://github.com/agdi/agdi/blob/main/scripts/sandbox-setup.sh)
> or set `agents.defaults.sandbox.docker.image` to your custom image.
> Containers are auto-created per session on demand.

> [accordion] Permission errors in sandbox
>
> Set `docker.user` to a UID:GID that matches your mounted workspace ownership,
> or chown the workspace folder.

> [accordion] Custom tools not found in sandbox
>
> Agdi runs commands with `sh -lc` (login shell), which sources
> `/etc/profile` and may reset PATH. Set `docker.env.PATH` to prepend your
> custom tool paths, or add a script under `/etc/profile.d/` in your Dockerfile.

> [accordion] OOM-killed during image build (exit 137)
>
> The VM needs at least 2 GB RAM. Use a larger machine class and retry.

> [accordion] Unauthorized or pairing required in Control UI
>
> Fetch a fresh dashboard link and approve the browser device:
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> docker compose run --rm agdi-cli dashboard --no-open
> docker compose run --rm agdi-cli devices list
> docker compose run --rm agdi-cli devices approve <requestId>
> ```
>
> More detail: [Dashboard](https://agdiai-597e782f.mintlify.site/web/dashboard.md), [Devices](https://agdiai-597e782f.mintlify.site/cli/devices.md).

> [accordion] Gateway target shows ws\://172.x.x.x or pairing errors from Docker CLI
>
> Reset gateway mode and bind:
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> docker compose run --rm agdi-cli config set gateway.mode local
> docker compose run --rm agdi-cli config set gateway.bind lan
> docker compose run --rm agdi-cli devices list --url ws://127.0.0.1:18789
> ```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.