Skip to content
Subspace

Installation & running

Subspace is a single Node process that supervises its own embedded PostgreSQL. This page covers where it stores data, how to configure it, and how backups work. For the exhaustive variable list see the environment reference.

The home directory

Section titled “The home directory”

On first boot Subspace runs initdb for an embedded Postgres under $SUBSPACE_HOME (default ~/Subspace) and applies migrations transactionally on every boot.

pg/

The PostgreSQL data directory. Unix socket only, no TCP listener. All durable state lives here: pages, comms, ops, search, agent runs.

blobs/

Content-addressed file store, sharded ab/cd/<sha256>. Uploads, attachments, and code-cell image outputs.

okf/

The optional filesystem mirror of the graph (one Markdown file per page). See the OKF bridge.

secret.key

The 0600 master key that the capability broker uses to decrypt ops.secrets at rest.

The database binaries

Section titled “The database binaries”

Subspace ships PostgreSQL 17.5 + pgvector as host-filtered optional npm packages for macOS arm64 / x64 and Linux arm64 / x64 (@subspace/pg-darwin-arm64, etc.), roughly 35 MB compressed each. A ~250 line pg-embed supervisor performs the first-run initdb --data-checksums, templates the config (unix socket, shared_buffers=128MB, archive_command wired when backup is configured), and supervises Postgres as a child process. Major-version bumps ship both majors’ binaries and run pg_upgrade --link automatically on boot.

Common configuration

Section titled “Common configuration”
Variable Default Purpose
SUBSPACE_HOME ~/Subspace Data directory (pg, blobs, okf, secrets).
SUBSPACE_PORT 4780 HTTP + WebSocket port.
SUBSPACE_HOST 127.0.0.1 Bind address. Localhost or tailnet only.
SUBSPACE_SEED unset mock-world seeds the demo fixture graph.
PROVIDERS unset fake uses deterministic stand-ins for external seams.
SUBSPACE_SHELL login shell Shell used for terminal nodes.
SUBSPACE_GITOPS_REPO unset Git-backed config pages. See GitOps.
Full environment referenceEvery variable, including backup, gitops, secrets, roles, and provider toggles.

HTTP surface

Section titled “HTTP surface”

/  SPA

The React single-page app, served statically by the server.

/health  GET

Health check.

/trpc/*  tRPC 11

The typed RPC surface every client speaks.

/ws  WebSocket

The topic-bus WebSocket: subscribe to topics, receive command echoes and invalidations.

/pty  WebSocket

Terminal streams for server-hosted and device-hosted PTYs.

POST /files  multipart

File upload into the content-addressed blob store.

/blobs/:sha256  GET

Immutable content-addressed blob fetch.

See the HTTP endpoint reference for the complete surface.

Backup, retention, and restore

Section titled “Backup, retention, and restore”

Subspace bundles WAL-G for continuous archiving and drills its own restores.

  1. Turn on WAL archiving

    Set a WAL-G repository variable (WALG_S3_PREFIX, WALG_FILE_PREFIX, and so on). This enables archive_command with archive_timeout=60s; a nightly backup-push retains 14 full backups.

  2. Replicate blobs

    Set SUBSPACE_BLOB_REPLICA_URL to enable the durable blob-replicator consumer. Referenced blobs upload within seconds; deletes become seven-day delayed tombstones.

  3. Snapshot the OKF dump

    With RESTIC_REPOSITORY configured, the nightly job also snapshots okf/ and retains 14 daily snapshots.

  4. Drill the restore

    A monthly PITR drill (and pnpm doctor -- --restore-drill) fetches the latest backup into a temporary read-only cluster, replays WAL, downloads every referenced blob, and OKF-parses every live page. Attempts and failures are audited in ops.backup_runs.