Installation

Getting started with Sp00ky involves setting up the CLI tool and configuring your project.

Prerequisites

Node.js (v22.12 or higher — the workspace pins >=22.21.1)
SurrealDB (v3.1 — the CLI defaults to surrealdb/surrealdb:v3.1.0-beta.3)
Rust (only if you’re building the SSP / scheduler from source — pre-built Docker images are used by default)

Step 1: Install the CLI

The Sp00ky CLI is your primary tool for generating code and managing schemas.

Bash

pnpm add -D @spooky-sync/cli

Step 2: Install Client SDKs

Install the core client and the bindings for your framework.

Bash

pnpm add @spooky-sync/core @spooky-sync/client-solid

Step 3: Run Infrastructure

The easiest way to start everything is with the Sp00ky CLI:

Bash

spky dev

This starts SurrealDB, the SSP sidecar, applies migrations, and runs your app dev server — all in one command. If your apps have a dev field configured in sp00ky.yml, those are started too. See the Dev Server page for details.

Alternatively, you can set up infrastructure manually with Docker Compose:

yaml

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_URL=http://surrealdb:8000
      - SPKY_DB_USER=root
      - SPKY_DB_PASS=root
      - SPKY_SSP_LISTEN_ADDR=0.0.0.0:8667
      - SPKY_SSP_REF_MODE=dedicated
    depends_on:
      - surrealdb

Run it with:

Bash

docker compose up -d

Step 4: Verify Your Setup

Run spky doctor from the project root to confirm everything is wired up:

Bash

spky doctor

It checks sp00ky.yml parses, the schema source exists, generated schema.gen.ts is up to date, and the migrations directory is in place. Each failed check comes with an actionable fix hint (e.g. spky generate).

For agent-driven workflows, pass --json for a stable, parseable contract:

Bash

spky doctor --json

Re-run spky doctor after every schema edit — it’s the fastest feedback loop for catching codegen drift.