Data & Credentials

OpenAlice is file-backed. There is no database to provision or migrate by hand: config, sessions, trading state, news, issues, Inbox entries, and workspace artifacts are ordinary files under a data root.

Data Roots

Source and desktop installs use ~/.openalice by default:

~/.openalice/
├─ data/
│  ├─ config/
│  │  └─ alice-project.json # immutable TraderAlice/NanoAlice birth
│  ├─ inbox/
│  ├─ entities/
│  ├─ trading/
│  ├─ news-collector/
│  ├─ preferences.json    # Quick Start, AutoQuant, and Harness choices
│  └─ ui-layout.json      # Activity Bar groups, order, and visibility
├─ workspaces/          # Workspace launcher root
│  ├─ workspaces.json
│  ├─ workspaces/       # Active Workspace repos only
│  ├─ departed-workspaces/
│  └─ state/            # Catalog, Sessions, runs, provenance, conversation/runtime logs
├─ state/               # Guardian and Runtime ownership locks
├─ runtime/             # Replaceable optional Broker Packs
├─ provider-keys.json
└─ sealing.key

Docker maps the same idea onto /data:

/data/
├─ data/
│  ├─ config/
│  │  └─ alice-project.json # immutable TraderAlice/NanoAlice birth
│  ├─ inbox/
│  ├─ entities/
│  ├─ trading/
│  ├─ news-collector/
│  ├─ preferences.json    # Quick Start, AutoQuant, and Harness choices
│  └─ ui-layout.json      # Activity Bar groups, order, and visibility
├─ workspaces/          # Workspace launcher root
│  ├─ workspaces.json
│  ├─ workspaces/       # Active Workspace repos only
│  ├─ departed-workspaces/
│  └─ state/            # Catalog, Sessions, runs, provenance, conversation/runtime logs
├─ state/               # Guardian and Runtime ownership locks
├─ runtime/             # Replaceable optional Broker Packs
├─ home/
└─ sealing.key

The Compose volume is named openalice_openalice-data. It stores config, workspace files, CLI auth under /data/home, and sealed broker account data.

The active workspaces/ directory is intentionally not an archive. Offboarded checkouts move to departed-workspaces/; state/workspace-catalog.json retains their lifecycle, while resume-identities.json, headless-tasks.json, and artifact-provenance.json preserve Session and report history. See Lifecycle & Offboarding.

Business Workspace Session dossiers travel with their checkout at .alice/sessions/<resumeId>.json. Their ai object records only the Agent, vault reference or runtime-managed source, model, and effort; an optional sibling displayName is the coworker's mutable nametag. Provider keys and resolved endpoints remain in the complete OpenAlice home. Workspace Manager dossiers use workspaces/state/workspace-manager-sessions/ because the manager owns no business checkout.

Upgrading a 0.89.2 home to 0.89.3 moves legacy Session AI bindings out of the global resume-identities.json registry and into these Workspace-owned files. The migration covers active, departed, and Workspace Manager Sessions, writes a backup before changing the registry, and leaves the global file responsible for identity and lifecycle only.

workspaces/state/agent-conversations.jsonl is a private append-only log of Workspace conversation dispatch and completion events. It contains full prompts and final replies, moves with the complete home, and should be treated as sensitive conversation history.

workspaces/state/agent-runtime.jsonl is the separate append-only occupancy journal used by Office. It records Session birth, runtime start/stop/failure/rejection, and bounded headless text/tool/error projections for replay. It excludes user prompts and tool input/output and is never a dispatch authority, but may still contain clipped replies and errors.

data/ui-layout.json is home-scoped user chrome for the Activity Bar. It stores built-in/custom groups, item order, and hidden rail entries and therefore moves with the complete AliceProject home. Use Settings → Activity bar rather than hand-editing it. A missing or malformed file restores the default layout with Dev Panel hidden; Settings remains pinned and cannot be hidden.

data/preferences.json stores non-sensitive home-wide interaction choices, including the recent Quick Start launch, default AutoQuant Workspace, and Settings → Harness roster filter. It can be copied with the complete home, but it must never contain provider keys, endpoints, tokens, or other secrets.

Selectable Complete Homes

A data location is the complete OPENALICE_HOME, not only its data/ child and not Electron's browser-profile directory. Config, Workspaces, lifecycle state, locks, optional Broker Packs, provider credentials, and the sealing key move together.

Packaged desktop users can open Settings → General → Data location to:

• open the current folder;
• choose another empty or existing OpenAlice home and restart;
• reuse a recent location;
• ask which location to use on every startup.

On a fresh desktop install, OpenAlice offers the default ~/.openalice or a different folder before acquiring a Runtime lock. Existing default-home users continue without a migration prompt. If another live AliceProject owns the chosen home, choose a different data location rather than forcing two writers into one directory.

There is one safe continuation shortcut: when a healthy local source-dev or CLI Server owner advertises a verified loopback Web endpoint, Electron offers Open in browser and then exits without taking the lock. It never shows that action for Electron-owned, stale, starting, unhealthy, or incompatible owners; takeover remains an explicit recovery choice.

The desktop remembers only the path and recent-location preference in its machine-local Electron profile. Secrets remain inside the selected home.

Browser/CLI and development projects use the same boundary:

openalice create alice-project --name research --home ~/.openalice-dev/research --yes
openalice up --project research
openalice status --project research
pnpm dev -- --home ~/.openalice-dev/feature-a

Two AliceProjects may run concurrently when they use different complete homes and unpinned ports. Two writers must never share one home. Paths are canonicalized, so symlink aliases do not bypass ownership detection.

Bare openalice manages this through AliceProjects. The implicit default may inherit the ordinary home, while every named project must register a separate complete home. Selecting or creating a project never moves, copies, stops, or deletes another home. Equal and nested registered homes are rejected.

The explicit exception is openalice project copy-ai-creds, which merges only AI credential rows from one registered complete home into another after confirmation. It skips matching credential identities, renames colliding slugs, never prints secrets, and does not copy Workspace preferences, broker accounts, provider-keys.json, or sealing.key.

The Supervisor project registry and machine defaults live in the platform's user configuration directory, outside every complete home. It contains paths, ports, update policy, and source selection rather than product data or credentials:

OPENALICE_SUPERVISOR_HOME relocates this machine-local registry; OPENALICE_PROJECT selects a registered AliceProject for one launch. OPENALICE_INSTANCE remains a deprecated compatibility alias.

Environment Roots

These variables control product data and Supervisor selection:

For ordinary isolation, set only the complete OPENALICE_HOME through --home. A fixed AQ_LAUNCHER_ROOT intentionally disables desktop home switching because selecting a new home while sharing Workspace files would violate the one-writer boundary. OPENALICE_GLOBAL_DIR is an advanced explicit sharing override.

See AliceProjects for stable project identity, concurrent runtime ownership, and the immutable TraderAlice/NanoAlice product choice stored inside each complete home.

Workspace creation keeps a free-space safety margin. If bootstrap, injection, git initialization, or registry persistence hits ENOSPC, OpenAlice reports insufficient_storage and does not register a half-created Workspace. Partial directories are removed or quarantined for inspection when the operating system still holds a handle.

Admin Token

When OpenAlice runs outside local-dev bypass, it creates a 256-bit admin token on first boot and prints it once. Only a scrypt hash is stored on disk.

Docker:

docker compose logs openalice | grep -A6 'First-run admin token'

Source/server process:

node dist/main.js

Then paste the token into the login screen. Browser sessions are stored separately in data/config/sessions.json.

Rotate or Recover Auth

If you lose the token, delete auth.json and restart:

rm ~/.openalice/data/config/auth.json

Docker:

docker exec openalice rm -f /data/data/config/auth.json
docker compose restart openalice

To force existing browser sessions to log in again, delete sessions.json too:

rm ~/.openalice/data/config/sessions.json

Docker:

docker exec openalice rm -f /data/data/config/sessions.json
docker compose restart openalice

Auth Boundary

The admin-token gate covers:

• /api/* routes except public auth/version endpoints
• the workspace PTY WebSocket
• cross-origin mutation protection through CSRF origin checks

The static React bundle is public so the login page can load before a session exists.

OPENALICE_DISABLE_AUTH=1 turns the gate off. Use it only behind another trusted boundary such as Tailscale ACLs, VPN-only access, or reverse-proxy auth.

Sealed Broker Credentials

Broker credentials never sit on disk in plaintext. accounts.json is sealed with AES-256-GCM under a machine-local key:

~/.openalice/sealing.key

or, in Docker:

/data/sealing.key

The sealed file is an envelope with ciphertext, IV, and auth tag. Without the matching sealing.key, OpenAlice cannot decrypt it. If you copy data/ to a new machine without the key, the unreadable account store is quarantined and Alice starts with an empty account store instead of silently using bad data.

Because account config is encrypted, manage broker accounts through the Web UI rather than hand-editing accounts.json.

Connector bot credentials use the same machine-key boundary in a separate sealed configuration. The Connector Settings API exposes only field presence, never the stored token. See External Connectors.

Replaceable Runtime State

Optional Broker Packs live under:

<OPENALICE_HOME>/runtime/broker-packs/

They are versioned, checksummed, and replaceable. Back up the complete user home, but expect to reinstall Packs after moving to another operating system or architecture rather than treating native dependencies as portable user data. After an OpenAlice production upgrade, already active downloaded Packs are reconciled automatically with the current platform release; missing Packs remain an explicit installation choice.

Ports

Default service ports:

Port environment variables override config:

OPENALICE_WEB_PORT=47331
OPENALICE_MCP_PORT=47332
OPENALICE_UTA_PORT=47333
OPENALICE_UI_PORT=5173

An explicitly configured port fails loudly if it is already in use. Defaults probe upward where Guardian owns allocation. A missing data/config/ports.json is the unpinned state: Alice keeps 47331 only as an in-memory fallback, and Guardian may choose the next free port. Any written web value is an intentional pin, including older shipped { "web": 3002 } files. Delete the web field or the file to restore probing. A one-run OPENALICE_WEB_PORT override does not write ports.json.

Backup and Restore

For Docker, back up the named volume or copy /data from a stopped container. Keep sealing.key with the backup if you need broker accounts to remain decryptable. Treat the backup as sensitive conversation history because the Workspace launcher state can contain full conversation prompts and replies.

For source/desktop, back up the selected complete home while OpenAlice is stopped. If you intentionally want to move research/Workspace history without broker or Connector secrets, omit sealing.key and recreate those integrations on the new machine. Never copy only data/ and assume Session identity, departed Workspaces, or Runtime ownership moved with it.