Docs
GitHubBlog

Search Documentation

Search for a page in the docs

Docker

Docker Compose is OpenAlice's first-class container path: use it when you want an image, volume, healthcheck, bundled Agent runtimes, and a container-owned lifecycle on a trusted machine. If you already have a private Linux or macOS host and want the browser on your laptop, managed CLI & Remote Access is the parallel first-class path. Neither surface is a fallback for the other.

For local debugging, use Source & Dev; for a local Windows install, choose the desktop beta or source path in Windows.

The image builds the Web UI, Alice backend, UTA Core, optional Connector Service, Workspace templates, and pinned Claude Code, Codex, opencode, and Pi runtimes into one service. Live broker SDKs are not baked into core; selected Broker Packs install under the persistent volume.

Prerequisites

  • Docker Engine or Docker Desktop / OrbStack
  • Git
  • Enough time for a first build: the image installs dependencies, compiles native modules such as node-pty, builds the UI/backend, and installs the bundled agent CLIs. Later builds reuse Docker cache and are faster.

The Dockerfile uses a Debian-based Node 22 image rather than Alpine because OpenAlice depends on native modules and workspace tooling that expect glibc, bash, and standard POSIX utilities.

Start OpenAlice

git clone https://github.com/TraderAlice/OpenAlice.git
cd OpenAlice
docker compose up -d --build

Compose creates:

  • container: openalice
  • image: openalice:local
  • network: openalice_default
  • volume: openalice_openalice-data
  • published port: host 47331 → container 47331

Only the Web UI port is published. The MCP/CLI port is deliberately not exposed to the host. UTA and Connector Service also stay on container loopback.

Check that the container is healthy:

docker compose ps

Get the Admin Token

On first boot, Alice prints one admin token and stores only its hash. Read it from the logs:

docker compose logs openalice | grep -A6 'First-run admin token'

You should also see startup lines like:

[guardian/prod] Alice → http://0.0.0.0:47331
mcp plugin listening on http://127.0.0.1:47332/mcp (+ /mcp/:wsId, /cli)
web plugin listening on http://0.0.0.0:47331

Open http://<server-host>:47331, paste the token, and sign in. On a local machine, use http://localhost:47331. The first screen is the admin-token gate:

OpenAlice admin-token sign-in screen

After sign-in, the Docker instance should land in Ask Alice:

OpenAlice Ask Alice page after signing in to a Docker deployment

Authenticate Agent CLIs

The image owns all four agent runtimes because a Linux container cannot borrow macOS host binaries and a remote host may have none. Their versions are pinned and verified during the image build.

Claude Code and Codex can use their normal subscription login. Login state persists in the Docker volume because the container's HOME is /data/home.

docker exec -it openalice claude
docker exec -it openalice codex login

Use the browser flow each CLI prints. After that, OpenAlice workspaces can use those CLI subscription logins.

For Pi or opencode, or when you prefer API keys, open Settings → AI Provider and add a compatible credential:

AI Provider settings in a Docker deployment

The Ask Alice picker should show Claude Code, Codex, opencode, and Pi as installed. Installed does not mean authenticated: each selected runtime still needs either its own login or a compatible vault credential.

Optional services and Broker Packs

Enable Discord or Telegram delivery through Settings → Connectors. Guardian starts Connector Service only when configured, and connector failure never changes local Inbox availability. See External Connectors.

UTA Core starts without live broker SDKs. Choosing a live broker or public CCXT data source in Trading downloads its version/platform Pack into:

/data/runtime/broker-packs/

The named volume therefore preserves installed Packs across container rebuilds. A missing or incompatible Pack disables only its accounts/data sources; Chat, Mock, and other engines remain available.

Verify the Running Service

Useful checks:

docker compose logs --tail=120 openalice
docker compose ps
docker exec openalice sh -lc 'node --version && git --version && claude --version && codex --version && opencode --version && pi --version'

The container healthcheck calls the public /api/version route from loopback. docker compose ps should report healthy after Alice is ready. A normal browser visit still goes through the admin-token login flow.

The MCP/CLI port should not be reachable from the host:

curl http://localhost:47332/mcp

That should fail unless you intentionally changed the Compose file.

Reuse Host CLI Logins

If you already have working claude or codex auth on the host, you can bind-mount those credential directories read-only instead of authenticating inside the container. Uncomment the matching lines in docker-compose.yml:

volumes:
  - openalice-data:/data
  - ${HOME}/.claude:/data/home/.claude:ro
  - ${HOME}/.codex:/data/home/.codex:ro

Then restart:

docker compose up -d

Do this only on machines where you are comfortable sharing those local CLI credentials with the container.

Update

From the repo checkout:

git pull
docker compose up -d --build

The named volume keeps config, Workspaces, CLI auth, logs, Connector settings, and installed Broker Packs across rebuilds.

Backup and Restore

Stop OpenAlice before taking a filesystem-consistent volume snapshot:

docker compose stop openalice
docker run --rm \
  -v openalice_openalice-data:/data:ro \
  -v "$PWD":/backup \
  alpine tar -czf /backup/openalice-data.tgz -C /data .
docker compose start openalice

Compose derives the volume prefix from the project directory, so confirm the real name with docker volume ls. Restore into an empty volume while OpenAlice is stopped. Treat the archive as sensitive: it can contain model logins, sealed broker credentials, the sealing key, private Workspace history, and reports.

Stop or Reset

Stop without deleting data:

docker compose down

Factory reset, including all config, workspaces, CLI auth, and broker settings inside the volume:

docker compose down -v

Use the reset command carefully. It removes the openalice_openalice-data volume.

Troubleshooting

Port 47331 is already in use — Change the host-side mapping in docker-compose.yml, for example "8080:47331", then open http://<server-host>:8080.

Lost the admin token — Rotate it by deleting /data/data/config/auth.json inside the container or volume, then restart:

docker exec openalice rm -f /data/data/config/auth.json
docker compose restart openalice
docker compose logs openalice | grep -A6 'First-run admin token'

Delete /data/data/config/sessions.json too if you need to force existing browsers to sign in again.

Agent starts but cannot call the model — Run the CLI login inside the container (docker exec -it openalice claude or docker exec -it openalice codex login) or configure a compatible API-key credential in Settings → AI Provider for Pi/opencode.

Container starts but the UI is not ready yet — Wait until docker compose ps reports healthy, then inspect docker compose logs --tail=200 openalice before refreshing.

Acceptance Contract

pnpm docker:smoke builds an isolated image, starts a temporary lite-mode instance, requires all four runtimes, creates a real Chat Workspace, opens the real PTY WebSocket, and calls the injected alice CLI. Release operators can opt into a paid credentialed smoke that proves multi-turn Session resume, Workspace Issue tool use, and keyless market-data access. The credential never enters the image or build context.