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 repos + headless run state
├─ 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 repos + headless run state
├─ 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.

Environment Roots

Three variables control where OpenAlice stores user data:

For a fully isolated source checkout, set all three. Setting only OPENALICE_HOME moves config but may still leave workspaces and provider keys shared.

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.

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 ~/.openalice. If you intentionally want to move research/workspace history without broker secrets, omit sealing.key and recreate broker accounts on the new machine.