Self-hosting

Run the scheduler and SSP yourself, single node or distributed, with the environment variables each needs.

Deploying Sp00ky requires running the Sp00ky Sidecar (SSP) alongside your SurrealDB instance. For production deployments, the Scheduler coordinates multiple SSP instances.

Architecture

1. SurrealDB: Your persistent data store.
2. Sp00ky SSP (Sidecar): A backend service that monitors SurrealDB for changes and maintains materialized views.
3. Scheduler (optional): Central coordinator for distributed deployments with multiple SSPs. Maintains a RocksDB snapshot replica and WAL.
4. Client: Connects directly to SurrealDB.

Single Node (Development)

The simplest setup for development and testing. No scheduler needed.

services:
  surrealdb:
    image: surrealdb/surrealdb:v3.1.0-beta.3
    command: start --user root --pass root rocksdb:/data/db
    ports:
      - "8666:8000"
    volumes:
      - ./data:/data

  ssp:
    image: ghcr.io/sp00ky-org/ssp-server:canary
    environment:
      - SPKY_DB_WS=ws://surrealdb:8000
      - SPKY_DB_USER=root
      - SPKY_DB_PASS=root
      - SPKY_DB_NS=main
      - SPKY_DB_NAME=app
      - SPKY_SSP_LISTEN_ADDR=0.0.0.0:8667
      - SPKY_AUTH_SECRET=your-secret-token
      - SPKY_SSP_REF_MODE=dedicated
    ports:
      - "8667:8667"
    depends_on:
      - surrealdb

Distributed (Production)

For production with high availability and horizontal scaling, use a Scheduler with multiple SSP instances.

services:
  surrealdb:
    image: surrealdb/surrealdb:v3.1.0-beta.3
    command: start --user root --pass root rocksdb:/data/db
    ports:
      - "8666:8000"
    volumes:
      - surreal-data:/data

  scheduler:
    image: ghcr.io/sp00ky-org/scheduler:canary
    environment:
      - SPKY_DB_WS=ws://surrealdb:8000
      - SPKY_DB_NS=main
      - SPKY_DB_NAME=app
      - SPKY_DB_USER=root
      - SPKY_DB_PASS=root
      - SPKY_SCHEDULER_ID=scheduler-01
      - SPKY_AUTH_SECRET=your-secret-token
    # Bind host/port and storage paths come from the scheduler's
    # sp00ky.yml (ingest_host, ingest_port, replica_db_path, wal_path).
    ports:
      # 9668 is the admin plane: the operator dashboard and its MCP server.
      # This is the only scheduler port you publish. 9667 stays internal.
      - "127.0.0.1:9668:9668"
    volumes:
      - scheduler-data:/app/data
    depends_on:
      - surrealdb

  ssp-1:
    image: ghcr.io/sp00ky-org/ssp-server:canary
    environment:
      - SPKY_SSP_ID=ssp-01
      - SPKY_DB_WS=ws://surrealdb:8000
      - SPKY_DB_USER=root
      - SPKY_DB_PASS=root
      - SPKY_DB_NS=main
      - SPKY_DB_NAME=app
      - SPKY_SSP_LISTEN_ADDR=0.0.0.0:8667
      - SPKY_AUTH_SECRET=your-secret-token
      - SPKY_SCHEDULER_URL=http://scheduler:9667
      - SPKY_SSP_ADVERTISE_ADDR=ssp-1:8667
      - SPKY_SSP_REF_MODE=dedicated
      - HEARTBEAT_INTERVAL_MS=5000
    ports:
      - "8667:8667"
    depends_on:
      - surrealdb
      - scheduler

  ssp-2:
    image: ghcr.io/sp00ky-org/ssp-server:canary
    environment:
      - SPKY_SSP_ID=ssp-02
      - SPKY_DB_WS=ws://surrealdb:8000
      - SPKY_DB_USER=root
      - SPKY_DB_PASS=root
      - SPKY_DB_NS=main
      - SPKY_DB_NAME=app
      - SPKY_SSP_LISTEN_ADDR=0.0.0.0:8667
      - SPKY_AUTH_SECRET=your-secret-token
      - SPKY_SCHEDULER_URL=http://scheduler:9667
      - SPKY_SSP_ADVERTISE_ADDR=ssp-2:8667
      - SPKY_SSP_REF_MODE=dedicated
      - HEARTBEAT_INTERVAL_MS=5000
    ports:
      - "8668:8667"
    depends_on:
      - surrealdb
      - scheduler

volumes:
  surreal-data:
  scheduler-data:

Operator dashboard

The scheduler image bundles a dashboard and serves it on the admin port at /admin. It shows the health of the scheduler and every SSP, the end-to-end sync latency, backend health, live logs, and workflow runs, and it can restart SSPs, cancel and retry workflow runs, pause schedules and take backups.

Point a browser at http://your-scheduler:9668/admin and sign in one of two ways:

• An admin account. spky admin add <user> puts an existing app user on the _00_admin roster; they then sign in with their normal app credentials. The roster starts empty, so until you add someone nobody can sign in this way.
• The break-glass password. Set SPKY_ADMIN_PASSWORD on the scheduler and sign in with that alone. It bypasses the roster, which is what makes it useful when the database itself is the thing that is down, so the dashboard shows a persistent banner while a session is using it.

The same port also serves an MCP server at /admin/api/mcp, so an AI assistant can read the cluster and run the same actions. Tokens are minted from the dashboard’s Access page.

Everything works self-hosted except the actions that only Sp00ky Cloud can perform, because they act on containers rather than on processes: pulling newer images, wiping the scheduler volume, bouncing SurrealDB, and the backup catalog, schedule, retention and delete. Those answer 409 with Not linked to Sp00ky Cloud, and the dashboard shows them greyed out with that reason rather than hiding them. Backups themselves still work: configure the S3_* variables below and the dashboard lists the bucket directly.

Environment Variables

SSP (Sidecar)

All SPKY_* vars below are read directly from the process environment.

Circuit persistence

Without a snapshot directory every restart is a cold rebuild: the SSP re-pages the whole database while the scheduler holds sync frozen. Point these at a volume and a restart restores the snapshot and catches up only what it missed. Both are caches of SurrealDB, never the source of truth, so deleting them is always safe. See State persistence.

Scheduler

The scheduler reads most of its config from sp00ky.yml, and the SPKY_* vars in the first table below override the corresponding YAML field. The fields ingest_host, ingest_port, load_balance, replica_db_path, wal_path, ssp_poll_interval_ms, max_buffer_per_ssp and job_tables are YAML only.

The tables after it are env only and have no YAML equivalent: the admin plane, backup storage, the dead-man heartbeat, and the tuning knobs.

Core

Admin plane

The dashboard and its MCP server, on their own port. See Admin dashboard.

Machine pools

The listener machine pool agents connect to, and the docker provider a self-hosted scheduler can create machines with.

Backup storage

These carry no SPKY_ prefix. The backup plane is enabled as soon as any of S3_ENDPOINT, S3_ACCESS_KEY, S3_SECRET_KEY or S3_BUCKET is present, so a partial configuration turns backups on with defaults filling the rest. Any S3-compatible store works. Also read by a standalone SSP, which serves the same backup routes.

Heartbeat and alerting

An end-to-end probe: the scheduler writes _00_heartbeat:probe upstream and times the full round trip through /ingest, the WAL, the broadcast and every SSP’s circuit. It is what the dashboard’s latency reading and the /health staleness flag are built on.

Tuning

Next steps