Self-hosted quickstart

This guide runs Spectron via Docker Compose alongside SurrealDB, bootstraps a Context, and exercises remember and recall. Full deployment options are in Docker.

Prerequisites

Docker and Docker Compose
An OpenAI or Anthropic API key for extraction and chat models

Step 1 — Start the stack

Use the compose.yaml from Docker deployment, then:

docker compose up -d

Spectron listens on port 9090 by default (check your compose file if you mapped a different host port).

Step 2 — Bootstrap keys and a Context

Follow the first-run steps in the Docker guide: create a management key, then create a Context and an end-user API key via the management API or CLI inside the container.

For native dev on the host (spectrond dev start + local SurrealDB), see the CLI dev start section and Configuration.

Export:

export SPECTRON_URL=http://localhost:9090
export SPECTRON_API_KEY=<context-api-key>
export SPECTRON_CONTEXT_ID=<context-id>
export SPECTRON_MANAGEMENT_API_KEY=<management-key>

Step 2b — Register scope paths

Before scoped writes or reads, register the paths you will use:

spectron scopes create org/acme \
  --url "$SPECTRON_URL" --api-key "$SPECTRON_API_KEY" --context-id \
    "$SPECTRON_CONTEXT_ID"

spectron scopes create org/acme/user/alice \
  --url "$SPECTRON_URL" --api-key "$SPECTRON_API_KEY" --context-id \
    "$SPECTRON_CONTEXT_ID"

For local dev with spectrond dev start, also export LLM provider env vars (embeddings alone is not enough for infer: full):

export OPENAI_API_KEY=sk-...
export SPECTRON_LLM_PROVIDER=openai
export SPECTRON_PROVIDER_OPENAI_API_KEY="$OPENAI_API_KEY"

Step 3 — Remember a fact

Using HTTP:

curl -sS "$SPECTRON_URL/api/v1/$SPECTRON_CONTEXT_ID/facts" \
  -H "Authorization: Bearer $SPECTRON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"King Charles III became head of state of the United Kingdom in September 2022.","infer":"full","scope":["org/acme/user/alice"]}'

Or install the CLI in your environment (or run via docker compose exec spectron …) and use:

spectron remember "Alice was promoted to Head of Platform at Acme." \
  --scope org/acme/user/alice \
  --url "$SPECTRON_URL" --api-key "$SPECTRON_API_KEY" --context-id \
    "$SPECTRON_CONTEXT_ID"

Step 4 — Upload a document

spectron documents upload ./returns-policy.pdf \
  --url "$SPECTRON_URL" --api-key "$SPECTRON_API_KEY" --context-id \
    "$SPECTRON_CONTEXT_ID"

Processing runs asynchronously on the worker tier.

Step 5 — Recall

spectron recall "What is Alice's role at Acme?" --json \
  --url "$SPECTRON_URL" --api-key "$SPECTRON_API_KEY" --context-id \
    "$SPECTRON_CONTEXT_ID"

Tier 1 or 2 hits avoid sending a large context block to the LLM.

Step 6 — Optional chat and MCP

spectron chat "Summarise what you know about Alice at Acme" \
  --url "$SPECTRON_URL" --api-key "$SPECTRON_API_KEY" --context-id \
    "$SPECTRON_CONTEXT_ID"

spectron mcp

Paste the printed MCP config into Claude Desktop, Cursor, or Claude Code.