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/
│  ├─ inbox/
│  ├─ entities/
│  ├─ trading/
│  ├─ news-collector/
│  └─ brain/persona.md
├─ workspaces/          # Workspace launcher root
│  ├─ workspaces.json
│  ├─ workspaces/       # Active Workspace repos only
│  ├─ departed-workspaces/
│  └─ state/            # Catalog, Sessions, runs, scrollback, provenance
├─ 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/
│  ├─ inbox/
│  ├─ entities/
│  ├─ trading/
│  ├─ news-collector/
│  └─ brain/persona.md
├─ workspaces/          # Workspace launcher root
│  ├─ workspaces.json
│  ├─ workspaces/       # Active Workspace repos only
│  ├─ departed-workspaces/
│  └─ state/            # Catalog, Sessions, runs, scrollback, provenance
├─ 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.

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 instance owns the chosen home, choose a different data location rather than forcing two writers into one directory.

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 instances use the same boundary:

openalice start --home ~/.openalice-dev/research
pnpm dev -- --home ~/.openalice-dev/feature-a

Two instances 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.

Environment Roots

Three variables control where OpenAlice stores user data:

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.

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.

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 in dev where appropriate.

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.

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.