Source & Dev

Use this path when you want logs, debuggability, local patches, or the newest code. It is the recommended path for contributors, Linux users, Intel Mac users, Windows users who want the reliable path, and anyone debugging beta behavior.

Prerequisites

Node.js 22+ - 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.

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.
Injects keyless read-only crypto data UTAs: binance-readonly, okx-readonly, bybit-readonly.
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+.

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.

Search Documentation