Configuration Reference

Installation configuration lives in ~/.openalice/data/config/ as JSON files (the user-data home; OPENALICE_HOME overrides the root, Docker mounts a volume there). A Workspace can additionally keep its own public metadata in .alice/workspace.json. Missing installation files are auto-created with defaults on startup. Most ordinary config supports hot reload; process ownership, ports, and optional-service lifecycle require Guardian reconciliation or restart. accounts.json and external connectors.json are sealed 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:

Appearance preferences

Open Settings → General → Appearance to choose color and layout preferences. Changes apply immediately and persist locally on that browser/device; they are not files under ~/.openalice/data/config/ and do not sync to another browser.

Interface style changes component shape, density, typography, and motion without changing the saved colors:

Color mode is independent: Auto follows the operating system's Day/Night preference, while Day and Night pin one saved palette slot. Windows 98 also offers Use recommended colors, which applies the Windows Classic palette to both slots only while that style is active. Use saved colors or switch styles to return to the saved Day & Night pair; the recommendation never overwrites those global selections.

Activity Bar layout

Open Settings → Activity bar to reorder the rail's items and groups, move items between groups, create or rename custom groups, and hide surfaces you do not use. Changes autosave to <OPENALICE_HOME>/data/ui-layout.json and travel with that complete AliceProject home; unlike Appearance, they are not merely a browser-local preference.

The version 1 document contains ordered groups plus a hidden page-id list. Built-in groups are primary, beta, and system; custom group ids begin with custom: and labels are limited to 40 characters. Settings is pinned and cannot be hidden. Dev Panel is hidden in the default layout. A hidden surface stays available through direct/deep links, and a missing or malformed file falls back to the complete default layout.

The default Beta group exposes one portfolio rail item labelled Trading. Its page navigator contains Trading as Git, All Accounts, and each connected account. trading-as-git is no longer a separate Activity Bar page id; layout normalization drops that retired id from older saved group and hidden lists while the /trading-as-git deep link continues to work.

User preferences

Open Settings → Harness for options shared by the Ask Alice, AutoQuant, and Prediction desks. Show headless-born Sessions defaults off: an Issue/API-born Session that has never opened a TUI or WebPi remains accessible from its Issue instead of appearing in the shared desk rosters. Turning the option on restores those existing Session rows; it does not create, archive, retire, or move them.

Show Issue-attached Sessions is a separate option and also defaults off. An exact Session currently assigned to an ordinary Issue, or a Session actively executing one, stays on Issue and Automation surfaces instead of the Ask Alice, AutoQuant, or Prediction roster. Turning it on changes presentation only; it does not change the Issue owner, execution, Session identity, or lifecycle. Connector chat Sessions always stay hidden from these rosters, regardless of this preference.

The version 1 document at data/preferences.json stores only non-sensitive, home-scoped convenience state:

Recent runtime use wins over the manual fallback order in compact launch menus; selection and failed launch attempts do not update it. Installation paths and readiness are probed live and are not stored in this file. Missing or malformed preferences fall back to defaults rather than blocking startup.

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 WorkspaceCredentialDefault:

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.

Live engines are optional runtime payloads rather than fields in this file. The Trading wizard installs, updates, or repairs the matching Broker Pack before testing credentials. Production startup also reconciles already active downloaded Packs with the current release. OPENALICE_BROKER_PACK_AUTO_UPDATE=0 disables that reconciliation as an emergency override; it does not install a missing Pack.

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

ports.json stores an explicitly pinned Alice Web listener:

The other listeners are child-process/runtime configuration rather than fields in this file:

Missing ports.json means unconfigured: Alice uses 47331 in memory and Guardian probes upward from that default when another AliceProject already owns it. First boot does not create this file merely to record the default.

Any written web number is a pin and fails loudly when occupied. This includes older shipped { "web": 3002 } files, which OpenAlice preserves rather than silently changing their meaning. Delete the web field or the file to restore automatic probing. OPENALICE_WEB_PORT wins for one launch and is not written back to ports.json.

connectors.json and connector-service.json

connectors.json is the sealed external-notification configuration for Discord, Telegram, Slack, Feishu/Lark, and future adapters. Its logical shape contains adapter enablement and settings, but secret token and App-secret fields never return through the public Settings API. Telegram uses a bot token; Slack uses bot plus app-level tokens; Discord uses application id plus bot token; Feishu/Lark uses App ID, App secret, and a feishu or lark domain. Owner and private-chat ids are learned through /link. Configure it through Settings → Connectors.

connector-service.json contains only:

{ "enabled": false }

Guardian reads that non-secret switch to decide whether to run the optional service. Settings changes also write a restart flag so Connector Service can reconcile without restarting Alice or UTA. See External Connectors.

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.

Native context and compaction

OpenAlice no longer owns a global compaction.json policy or a workspaceDefaultContextWindow field; both predate the supported 0.89.2-beta baseline. Context and compaction belong to the selected model and Agent runtime; OpenAlice stores an explicit context override only inside a specific Oh My Pi, Pi, or opencode Workspace binding.

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.

Workspace instruction ownership

There is no installation-wide Persona configuration or global persona editor. Each instruction-bearing template owns one instruction.md; Workspace creation copies it to CLAUDE.md and AGENTS.md. Those committed Workspace files are the editable source of truth for that desk. Later template changes arrive only through the reviewed Template Upgrade flow.

.alice/workspace.json

This file belongs to one Workspace rather than the installation config root. OpenAlice updates it through Workspace Settings and keeps it in the Workspace's Git-visible .alice/ directory.

An explicit Quick Chat, sidebar, CLI, or API runtime wins for one launch without rewriting defaultAgent. If the field is absent or names an unavailable runtime, OpenAlice falls back to workspaceDefaultAgent, then the first live registered runtime.

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.