Get Digital Brain running on your own hardware.

Run it locally

The native application runs an Electron utility process that owns the authenticated loopback API, the SQLite database and the provider sessions.

# desktop app
pnpm dev

# persistent browser service
pnpm build && pnpm serve

Bind a specific repository with DIGITAL_BRAIN_WORKSPACE=/absolute/path; otherwise the working directory is persisted as the initial project workspace. A fresh database starts with that real workspace registered and no sample conversations.

Create an account

Provisioning the first user enables the browser sign-in screen. Stop the standalone service first, then run the built user command and restart it.

DIGITAL_BRAIN_USER_USERNAME=John \
DIGITAL_BRAIN_USER_DISPLAY_NAME=John \
DIGITAL_BRAIN_USER_PASSWORD='choose-a-long-unique-password' \
pnpm --filter @digital-brain/desktop auth:create-user

The command stores a salted scrypt verifier, never the raw password. A successful sign-in keeps its 15-minute access token in memory and rotates a refresh session — valid up to 30 days — in a Secure; HttpOnly; SameSite=Strict cookie. Electron keeps its per-launch trusted bridge and never shows the sign-in screen.

Pair a phone

The service stays loopback-only by default. To reach it from another device on a trusted private network, bind an explicit address and advertise the URL that device can actually reach.

DIGITAL_BRAIN_HOST=0.0.0.0 \
DIGITAL_BRAIN_PUBLIC_ORIGIN=https://thebeast.example.ts.net \
pnpm serve

Startup prints a ten-minute, one-time pairing link; opening it exchanges the credential for a durable device session. Settings → Connections has the guided setup: verify the advertised HTTPS origin, render a QR code, watch the paired session appear, then offer installation and notifications. Ordinary pairing links get mission:read, mission:operate, terminal:operate and access:read — they cannot create credentials or change host and provider configuration.

Note Put TLS in front of Digital Brain for any network that isn't wholly trusted. Revoking a device also removes its Web Push subscription.

Providers

Settings → Providers manages durable, named provider instances and reports the server-side client versions it discovered.

Secret environment values live only in a mode-0600 host sidecar and are always redacted when read back. Saved changes apply immediately when every native session is idle; while a turn is active the new configuration stays visibly pending, so a session is never silently rebound to different credentials.

Required checks

In Project settings → Task completion, configure a command such as pnpm validate. Checks run after coding turns — including native Android conversations — and retain exit codes, bounded logs, the tested commit and a hash of the actual files and index.

Leave the command blank to disable checks; existing projects start with them disabled, and turns without a configured command omit the empty panel. Code reviews receive a frozen evidence packet containing the recorded tool commands, outputs, available exit codes and check results — a successful tool call alone never proves tests passed.

Optional automatic corrections share a frozen limit of 0–3 attempts and a time budget, use the original task's model and access policy, and are attributed as automatic system messages. Retrying checks never replenishes that allowance.

Durable turns

Install the independently supervised Codex runtime so turns outlive the app that started them.

pnpm runtime:install
export DIGITAL_BRAIN_CODEX_SOCKET="${XDG_RUNTIME_DIR:-/run/user/$(id -u)}/digital-brain/codex-app-server.sock"
pnpm serve

Digital Brain connects through WebSocket framing on that private Unix socket. Restarting the desktop or browser service detaches its client but leaves Codex and active turns running; startup rejoins the exact persisted turn, restores pending approvals and hydrates missed messages and tool results before accepting more input.

Validation commands

# the complete gate: suite, builds, Electron smoke
pnpm validate

# repository-wide format/lint/type/unit, no builds
pnpm validate --quick

# small fixes: only what changed against HEAD
pnpm check:changed
pnpm check:changed --base origin/main --plan

Documentation-only changes need formatting alone. Shared configuration, contracts, migrations and unclassified changes select the full gate automatically. Browser tests use up to eight local workers, or two in CI; override with pnpm test:e2e --workers=4.

Android release

Building a signed, installable APK needs JDK 21 and the Android SDK. Signing secrets are created once, outside the repository.

node apps/mobile/scripts/init-signing.mjs
pnpm --filter @digital-brain/mobile android:release

The APK and its checksum/version manifest are written to release/mobile, and the standalone service serves the signed artifact at /downloads/digital-brain.apk. Keep the package ID and signing key stable and increase the version code for every distributed update — installing over the existing app then preserves pairing, drafts and notification setup.