Configuration Reference

All configuration lives in ~/.openalice/data/config/ as JSON files (the user-data home; OPENALICE_HOME overrides the root, Docker mounts a volume there). Missing files are auto-created with defaults on startup. Config files support hot-reload — changes take effect on the next request without restart. The one exception is accounts.json, which is sealed (encrypted at rest) and managed through the Web UI rather than hand-edited.

This page is a reference, not the recommended first-run path. For normal setup:

• Use the browser settings and setup wizards as the main configuration surface.
• Add model credentials through the AI Provider page.
• Add broker accounts through the Trading page wizard.
• Use Settings for hot-reloaded config where the UI exposes an editor.
• Edit JSON directly only when you need a field the UI does not expose yet.

The files fall into three buckets:

ai-provider-manager.json

The credential vault — api-key credentials injected into workspaces. As of 0.40 there's no in-process model loop, so this file holds no backends or active-profile pointer; just a map of slug → credential. Edit it through the Web UI's AI Provider page rather than by hand.

Each Credential:

Credentials are deduplicated by { vendor, authType, apiKey } — re-saving the same key upgrades its wires in place. See AI Providers for the full model.

accounts.json

UTA (Unified Trading Account) definitions. Array of UTA objects, preset-driven — you pick a presetId from the broker preset catalog and fill presetConfig with the values that preset's Zod schema requires.

Sealed at rest. Unlike every other config file, accounts.json is encrypted (AES-256-GCM) under a machine-bound key at ~/.openalice/sealing.key, so broker credentials never sit on disk in plaintext. That means it's UI-managed, not hand-edited — add and edit accounts through the Web UI's account form. The fields below describe the logical shape the UI writes. See Data & Credentials.

Optional keyless data UTAs. trading.json can enable Binance, OKX, and Bybit public-data sources. Enabled entries are materialized at UTA startup as binance-readonly / okx-readonly / bybit-readonly; they are code-defined, not written to sealed accounts.json. The default list is empty. See Keyless Data Accounts.

The presetConfig shape varies by preset:

Manage trading accounts through the Web UI wizard when possible; the file is sealed at rest and not meant to be hand-edited for ordinary setup. See Trading Setup.

engine.json

Core engine settings.

agent.json

AI agent behavior.

Default disallowed tools: Task, TaskOutput, AskUserQuestion, TodoWrite, NotebookEdit, Skill, EnterPlanMode, ExitPlanMode, mcp__claude_ai_Figma__*

ports.json

The four service ports, read by the Guardian supervisor before it spawns the processes. This is the authoritative place to change ports.

Precedence per port: an env override (OPENALICE_WEB_PORT, OPENALICE_MCP_PORT, OPENALICE_UTA_PORT, OPENALICE_UI_PORT) wins over ports.json, which wins over the defaults. Defaults probe upward if taken; an explicitly-set port that's in use fails loudly instead.

connectors.json

Bind config for the running Alice process (hot-reloaded). Ports themselves come from ports.json / env above; connectors.json carries the rest.

mcp.json

MCP server configuration — exposes the ToolCenter to external MCP clients and the workspace CLIs. The listener is always bound to loopback and never honors OPENALICE_BIND_HOST (it carries the full, unauthenticated tool surface). See MCP & CLI Access.

auth.json

The admin-token gate for the web boundary. Generated on first boot; the token is printed once to stdout and stored only as a scrypt hash. Rotate by deleting this file and restarting. See Data & Credentials.

Loopback requests bypass the gate entirely (zero-friction dev); set OPENALICE_TRUSTED_PROXIES for reverse-proxy setups or OPENALICE_DISABLE_AUTH=1 to opt out.

crypto.json

Legacy global crypto provider. New installs typically leave this as { "provider": { "type": "none" } } and use accounts.json per-account presetConfig instead. Kept for backwards compatibility.

securities.json

Legacy global securities provider. Same deprecation story as crypto.json — prefer per-account config.

market-data.json

Market data settings. The data engine runs in-process through the SDK — the external openbb-api backend was removed, so there's no sidecar to configure. See the Data Hub page for the resolution model.

provider-keys.json

User-global data-vendor keys at the ~/.openalice root (above data/), shared across every checkout and the desktop app on this machine. The location is overridable via OPENALICE_GLOBAL_DIR (default ~/.openalice/provider-keys.json) — resolved off the real home directory independently of OPENALICE_HOME, so it stays global even when OPENALICE_HOME=$PWD pins data/ to a checkout. Same key set as market-data.json → providerKeys; the per-install file overrides this one key-by-key. Missing FRED / EIA / BLS keys route through the Hub's keyed proxy automatically. See Data Hub — provider keys.

trading.json

Trading-engine knobs.

Use Settings → Agent Permissions for mode and the Trading page for public data-source toggles. Those UI flows coordinate the UTA stop/start needed for a runtime change; direct JSON edits do not provide that feedback.

news.json

News collector settings.

Default feeds: Federal Reserve Press, ECB Press, MarketWatch Top Stories, WSJ Markets, CNBC Economy, Nikkei Asia, SCMP Business, CoinDesk.

snapshot.json

Account snapshot settings.

compaction.json

Context window management.

tools.json

Tool enable/disable.

web-subchannels.json

Web UI sub-channel definitions. Array of channel objects. This is an advanced config file for specialized chat surfaces; most installs never need to edit it directly.

Persona overlay

Alice's persona is a Markdown file that the engine prepends to the system prompt on every generation. It defines her identity and speaking style.

The persona uses a two-tier default + user override pattern:

On first run, the default is auto-copied to the override path. Edit the user file to customize without touching version control — updates to the default won't overwrite your customizations. The persona is composed into each workspace's instruction file (CLAUDE.md + AGENTS.md) at create time; the Web UI's settings panel exposes an editor that writes to the same file.

Next Steps

• Installation Overview — Choose the right run path for your machine.
• AI Providers — Manage model credentials without hand-editing the vault.
• Trading Setup — Manage sealed broker config through the wizard.
• Remote Access — Understand auth, ports, and network exposure.