Deploying
Run Spool for other people with spool build, spool apply and spool serve, sign them in, give programs tokens, and back up the store.
spool dev is for one person on one machine. spool serve is the server other people and programs reach. It is the same binary and the same store format. What changes is that every caller is known, and that the server reads a compiled manifest in place of the project's files.
This page says how Spool is meant to be run, and each command on it was run as shown.
What a deployment is
- One process on one machine. There is no cluster mode, no replica and no failover.
- One store file, a DuckDB database, which that process alone opens.
- One accounts file beside it, named after it:
spool.auth.sqliteforspool.duckdb. It holds people and tokens. - The project, at the version you built: the manifest, plus any strategy and extractor files.
Build
spool init companies
cd companiesspool buildmanifest ./.spool/manifest.json
hash d7d4b712d86302152897a67a5924cd1c2e26594e049685c2f007177e20633946
types company
wrote ./Dockerfile
wrote ./.dockerignorespool build checks the project and writes .spool/manifest.json, which holds every rule and declaration with a hash of the whole. It also writes a Dockerfile and a .dockerignore if the project has none.
Apply
spool apply --store spool.duckdbstore spool.duckdb
manifest d7d4b712d86302152897a67a5924cd1c2e26594e049685c2f007177e20633946
declared companyspool apply creates the store if there is none, declares new entity types, and computes the features again for each type whose declaration changed. Identities are not touched. It runs while the server is stopped, so a change of rules is: build, stop the server, apply, start the server.
Serve
spool serve --store spool.duckdb --listen 127.0.0.1:7765manifest d7d4b712d86302152897a67a5924cd1c2e26594e049685c2f007177e20633946
accounts spool.auth.sqlite
listening on http://127.0.0.1:7765
studio http://127.0.0.1:7765/
mcp http://127.0.0.1:7765/mcp
setup http://127.0.0.1:7765/setup#8903cd40f174a29b7c4f4151e5f06e9105827d80da047fb278e18ca1cab9193c
no admin can sign in yet: open that link, at the address people reach this server by, to make the first accountLeft out, --listen is 0.0.0.0:7765. Put a reverse proxy with TLS in front, and give the server the address people reach it by with --public-url https://spool.example.com. Spool does not terminate TLS.
A server refuses to start on a store that was applied with another manifest, and says to run spool apply first.
The first account
While no admin can sign in, the server prints a link when it starts. Whoever opens it makes the first account, with a username and a password, and is the admin who adds everyone else on the studio's People page.
Passwords are for getting started. They have no second factor and no reset by email. A server that people rely on should sign them in with Google: set SPOOL_GOOGLE_CLIENT_ID and SPOOL_GOOGLE_CLIENT_SECRET to an OAuth client of the type "Web application", whose redirect URI is the public URL followed by /auth/google/callback. The server prints the exact value on the line that begins with google. An admin then adds each person by the email of their Google account. Google is the only identity provider there is. There is no SAML and no generic OIDC.
Tokens for programs
A pipeline or an agent presents a token. Make one on the server's machine, or on the studio's Tokens page:
TOKEN=$(spool token add pipeline --store spool.duckdb)That is the token `pipeline`, kept in spool.auth.sqlite. It is shown this once.
A caller sends it as `Authorization: Bearer <token>`, and what it changes is recorded under `agent:pipeline`.The token itself is the only thing on standard output, which is why it can be caught in a variable. It is shown this once. The server keeps a hash of it.
spool token list --store spool.duckdbtoken made at made by last used
pipeline 2026-11-18T17:22:33.382Z spool token add neverA caller sends it as a bearer token, and what it changes is recorded as agent:pipeline:
curl -s -X POST http://127.0.0.1:7765/v1/load -H "Authorization: Bearer $TOKEN" -d '{"source": "crm", "entity_type": "company", "wait_ms": 5000, "rows": [{"id": "c-1", "name": "Acorn Tools", "country": "GB"}]}'Without one, the server says so:
curl -s http://127.0.0.1:7765/v1/info{"error":{"code":"unauthorized","message":"sign in, or send a token: `Authorization: Bearer <token>`"}}The command line takes the token from SPOOL_TOKEN and the address from SPOOL_URL:
SPOOL_TOKEN=$TOKEN spool showserver http://127.0.0.1:7765
api v1, engine 0.1.0, store format 11
manifest d7d4b712d86302152897a67a5924cd1c2e26594e049685c2f007177e20633946
head log position 0
documents 0
entity type `company`
records 1, 1 without an identity
identities 0
review 0 items open
extractor `companies` (python, extractors/companies.py)There are two kinds of caller. An admin adds people and makes tokens. Everyone else, and every token, can read everything and change identities. There are no finer permissions, and nothing limits a caller to one entity type or one source.
A container
docker build -t companies .
docker run -p 7765:7765 -v spool-data:/data companiesThe Dockerfile that spool build writes starts from the image ghcr.io/alexpatow/spool:0.1.0, builds the manifest in it, and runs spool serve with the store at /data/spool.duckdb, on a volume. For a project with a Python file, as the sample project has, it also copies uv in and runs spool build --install, which fetches what each strategy and extractor depends on, the sample extractor's model with it, so that the server fetches nothing as it runs. A changed project is applied with the server stopped: docker run --rm -v spool-data:/data companies apply.
Backing up
The store is one file and the accounts are another. Stop the server, copy both, start it. There is no online backup and no export.
Everything that decides an identity is in the store: the records, every judgement, and the whole log. Nothing is derived from the project at read time, so a copy of the store is a copy of the identities.
Upgrading
Until 1.0, nothing is promised about a store written by one version opening in the next. Where a release can upgrade a store, it does so when the store is opened, and the release notes say which formats it reads. Copy the store before starting a new version on it.
Stopping
The server stops on Ctrl-C or SIGTERM and prints stopping. It takes no new request, answers the ones it has within six seconds, finishes the runs it was given, however long they take, and prints stopped. If the process is killed first, the run is recorded as failed when the store is next opened.
What to watch
- Memory. A match holds its candidate pairs in memory. Five million records with 76 million candidate pairs peaked at 13.4 GB in the repository's benchmark.
- One writer. Calls that change the store run one after another. A long match holds up a load that arrives during it.
GET /healthzanswers{"status":"ok"}with no sign-in. There are no metrics and no tracing.- User code. Strategies and extractors that are
.pyfiles run withuv, and.tsfiles withbun. Both must be on the server's machine, and each run is limited by--task-timeout, 600 seconds unless set.