1. Clone and install dependencies

git clone https://github.com/TraderAlice/OpenAlice.git
cd OpenAlice
pnpm install

First-time pnpm install pulls the full monorepo + native deps (notably node-pty for terminal sessions). On a normal connection allow ~1 minute.

pnpm may print "Ignored build scripts: ccxt, esbuild, protobufjs" — this is fine, those are optional native optimizations and OpenAlice doesn't need them. You can run pnpm approve-builds later if you want to opt in.

Run on a server (Docker)

For self-hosting on a VPS or always-on box. The image bundles claude and codex CLIs — no host install needed.

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

First-time auth (one-shot — credentials persist in the data volume so the container can be rebuilt without losing them):

docker exec -it openalice claude        # OAuth: paste URL into any browser
docker exec -it openalice codex login   # same dance for codex

Then open http://<your-server>:47331 in a browser. You'll hit the admin-token login screen — see Authentication above for how to retrieve the first-run token from docker logs.

Notes

- All state — config, workspaces, claude/codex credentials, logs — lives in the openalice-data named volume. docker compose down -v is the factory reset. - Already have claude/codex auth on the host? Skip the docker exec step by uncommenting the bind-mount lines in docker-compose.yml to reuse your local ~/.claude and ~/.codex. - The MCP server (port 47332) is intentionally not exposed externally; it's consumed by the CLIs running inside the container only. - The base image is node:22-trixie-slim (Debian 13) because several native deps (notably longbridge) ship glibc 2.39 binaries that older Debians don't have, and workspace bootstrap scripts need bash + POSIX utils. Alpine doesn't qualify on either count (musl libc, no bash).

Quick Start

Heads up: there's no native installer yet. To try OpenAlice today you clone the repo and run it from source — this section is the contributor / early-adopter path. A DMG (macOS) + Windows installer are in flight; once they ship, the steps below collapse to "download, open, done."

Configuration

All config lives in data/config/ as JSON files with Zod validation. Missing files fall back to sensible defaults. You can edit these files directly or use the Web UI.

AI Provider — The default provider is Claude (Agent SDK), which uses your local Claude Code login — no API key needed. To use the Vercel AI SDK instead (Anthropic, OpenAI, Google, etc.), switch ai-provider.json to vercel-ai-sdk and add your API key. Both can be switched at runtime via the Web UI.

Trading — Unified Trading Account (UTA) architecture. Each account in accounts.json becomes a UTA with its own broker connection, git history, and guard config. Broker-specific settings live in the brokerConfig field — each broker type declares its own schema and validates it internally.

Persona and heartbeat prompts use a default + user override pattern:

On first run, defaults are auto-copied to the user override path. Edit the user files to customize without touching version control.

Interface

• Web UI — workspace chat, the Inbox, a portfolio dashboard with equity curve, and full config management
• Workspace — a per-task directory + git repo + persistent terminal session running your chosen agent CLI (claude / codex / shell) with OpenAlice's MCP tools plumbed in. The recommended path for any non-trivial AI work — native prompt cache, native rendering, no protocol shim
• Inbox — workspace-to-user push channel. Agents call inbox_push from inside a workspace to surface a document (rendered live) plus a markdown comment in a dedicated tab; click the reply bar to jump back into the workspace and continue
• MCP server — tool exposure for external agents