Installation

Prerequisites

Node.js 22+ — Download
pnpm 10+ — Install with npm install -g pnpm or via Corepack
Claude Code CLI — Install and authenticate following the Anthropic docs. This is needed for the default AI provider (Claude via Agent SDK with your Pro/Max subscription). If you plan to use the Vercel AI SDK with your own API keys instead, Claude Code is optional.

Install

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

Run

pnpm dev

Open localhost:3002 and start chatting. No API keys or config files needed — the default setup uses your local Claude Code login.

Development Mode

OpenAlice has two dev commands:

Command	Port	Purpose
`pnpm dev`	3002	Backend with watch mode (tsx). Serves the pre-built UI.
`pnpm dev:ui`	5173	Frontend dev server (Vite) with hot reload. Proxies API calls to port 3002.

For UI development, run both commands in separate terminals. For everything else, pnpm dev alone is sufficient.

pnpm build     # Production build (backend + UI)
pnpm test      # Run unit tests (Vitest)
pnpm test:e2e  # Run end-to-end tests

First-Run Behavior

On first startup, OpenAlice automatically:

Creates config files — All JSON config files are created in data/config/ with sensible defaults. Missing files are re-created on each startup.
Copies persona — The default persona prompt (default/persona.default.md) is copied to data/brain/persona.md. Edit this file to customize Alice's personality.
Copies heartbeat prompt — The default heartbeat prompt (default/heartbeat.default.md) is copied to data/brain/heartbeat.md.
Loads symbol index — SEC and TMX stock symbols (~13k) are cached locally for instant search.

Your customizations in data/ are gitignored and will not be overwritten by updates.

Verifying the Installation

When OpenAlice starts successfully, you should see output like:

tool-center: 25 tools registered
cron: engine + listener started
heartbeat: enabled (every 30m)
plugin started: mcp
plugin started: web
engine: started

The Web UI should be accessible at localhost:3002 with a chat interface ready to go.

Troubleshooting

Port 3002 is already in use — Another process is using the port. Either stop it or change the port in data/config/connectors.json:

{ "web": { "port": 3003 } }

Claude Code not authenticated — If you see authentication errors, run claude in your terminal to complete the Claude Code login flow.

Using API keys instead of Claude Code — Switch to the Vercel AI SDK provider in data/config/ai-provider.json:

{
  "backend": "vercel-ai-sdk",
  "vercelAiSdk": {
    "provider": "anthropic",
    "model": "claude-sonnet-4-20250514",
    "apiKeys": {
      "anthropic": "sk-ant-..."
    }
  }
}

pnpm install fails — Make sure you're using pnpm 10+ and Node.js 22+. Run node -v and pnpm -v to check.

Search Documentation