Docker

Docker Compose is the recommended server path today: use it when you want OpenAlice running as a long-lived service on a trusted machine. For local debugging, use Source & Dev; for a normal Windows source install, use Windows.

The image builds the Web UI, Alice backend, UTA service, workspace templates, and the bundled claude and codex CLIs into one service.

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.

Check that the container is running:

docker ps --filter name=^/openalice$

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:

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

Authenticate Agent CLIs

The Docker image includes the claude and codex binaries, but their account logins still need to be completed once. The 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.

If you prefer API keys, open Settings → AI Provider in the Web UI and add a credential instead:

opencode and Pi are not installed in the stock Docker image; use a source install or extend the image if you need those runtimes on a server. In the Ask Alice agent picker, the stock image should show Claude Code and Codex available:

Verify the Running Service

Useful checks:

docker compose logs --tail=120 openalice
curl -I http://localhost:47331
docker exec openalice sh -lc 'node --version && git --version && claude --version && codex --version'

curl -I http://localhost:47331 may return 401 Unauthorized because the HEAD request passes through the auth gate. A normal browser visit still loads the React app and shows the login screen. The important path is the browser flow with the admin token.

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, and logs across rebuilds.

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 an API-key credential in Settings → AI Provider.

Container starts but the UI is not ready yet — Wait for:

engine: started
web plugin listening on http://0.0.0.0:47331

Then refresh the browser.

Search Documentation