Source & Dev

Use this path when you want logs, debuggability, local patches, or explicit control over the checkout. It is the recommended path for contributors, Linux users, and anyone debugging beta behavior. For a smaller source-backed launcher or private SSH host, see CLI & Remote Access.

Prerequisites

Node.js 22.19.0+ - Download
pnpm 10+ - install with npm install -g pnpm or Corepack
Git - needed to clone the repo
An agent CLI - at least one of claude, codex, opencode, or pi

The simplest model path is Claude Code: run claude once and log in with your Pro/Max subscription. No API key is needed. If you prefer API-key providers, add a credential in AI Providers.

Install

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

Run

pnpm dev

The dev orchestrator prints the URLs it picked. Open the UI URL, usually:

http://localhost:5173

No database or config file is required before first launch.

For an isolated data home, keep state outside the checkout:

pnpm dev -- --home ~/.openalice-dev/feature-a

Separate complete homes are the normal way to run multiple worktrees at once. --takeover is recovery authority for the same home, not a concurrency tool.

What `pnpm dev` starts

pnpm dev runs the Guardian orchestrator, which brings up the local stack in order:

Process	Default port	Purpose
UTA service	`47333` (127.0.0.1)	Broker carrier and keyless data UTAs
Alice backend	`47331`	API, workspace runtime, auth boundary
MCP server	`47332` (`/mcp`)	External MCP and internal CLI gateway
Vite UI	`5173`	Frontend dev server with hot reload

Ports auto-bump if a number is taken. Always trust the URLs printed by the terminal over the defaults in the table.

Useful commands

pnpm dev       # Start local development stack
pnpm build     # Production build (backend + UI)
pnpm test      # Unit tests (Vitest)
pnpm test:e2e  # End-to-end tests

First-run behavior

On first startup, OpenAlice automatically:

Creates JSON config files under ~/.openalice/data/config/.
Copies the default persona to ~/.openalice/data/brain/persona.md.
Starts in Lite mode when no broker accounts or explicit trading mode exist, keeping UTA disconnected while research and workspaces remain available.

Optional keyless crypto K-line sources are disabled by default. Switch to Readonly or Pro, then enable Binance, OKX, or Bybit under Trading → Public crypto data sources when you want them. 4. Loads the local SEC/TMX symbol index for instant equity search.

All of this lives outside the git checkout under ~/.openalice unless OPENALICE_HOME points somewhere else. Updating the repo does not erase your workspaces, config, Inbox, sessions, or broker-account data.

Troubleshooting

A port is already in use — Guardian probes for free ports and bumps automatically. To pin ports explicitly, edit ~/.openalice/data/config/ports.json or set env vars such as OPENALICE_WEB_PORT.

Claude Code is not authenticated — Run claude directly, finish login, then restart pnpm dev.

Using API keys instead of CLI login — Add a credential in Settings -> AI Provider. The credential is tested before saving and injected into future workspaces.

pnpm install fails — Check node -v and pnpm -v. OpenAlice expects Node 22+ and pnpm 10+.

You want a browser Runtime without memorizing Guardian commands — Install the stable CLI and use openalice start. It can bootstrap dependencies, reuse a compatible active Runtime for the same home, and expose structured server status; see CLI & Remote Access.

Next Steps

Quick Start - Run the product loop after the dev server starts.
File-based State - Understand ~/.openalice.
Configuration Reference - Inspect config files and defaults.
Docker - Move from local dev to a long-lived server.
CLI & Remote Access - Use the source-backed CLI locally or through SSH.

Search Documentation