Local and the server

spool dev is the whole engine on your machine: the server, an agent, the console, and a database file beside your work. A workflow you write against it is the same workflow hyperspool.dev runs, so replay, timers, approvals, events, schedules, artifacts and secrets can all be built and debugged before any of it leaves your laptop. This page says what each side does for you.

Everything you can try locally

spool dev --db ./spool.db

One process, one file, the console at http://localhost:18753. Add --bind 0.0.0.0 to reach it from the rest of your network; the admin token is then the only thing in front of it. From there:

• Runs are durable. Steps record their values once, sleeps end the process and wake it later, and a kill -9 mid-run picks up from the last checkpoint. The crash test shows it.
• Every authoring form works: YAML pipelines, scripts, workflows in your language, and graphs you draw on the canvas and save.
• Runs can wait for the outside world: signals, approvals, wait_for_event:, cancel_on:, child runs, and durable state cells shared across runs.
• Schedules tick, concurrency groups queue, and event handlers fire on the project bus.
• Debugging is the same: load a finished run on the canvas and each node shows its In / Out / Logs, with run from here to re-enter the graph at one node. spool run follow shows the same in a terminal.
• Artifacts, logs and annotations behave as they do on the service.
• Secrets and credentials are encrypted with a key written next to the database, and resolve by name the way a project’s do on the service.

You can take a workflow from first line to survived-a-crash without deciding where it will eventually live.

A webhook from a forge needs a URL the forge can reach, so repo-driven pipelines are easier to try on hyperspool.dev than against a laptop.

What local keeps, and what it forgets

State goes into the database file you name with --db, or $XDG_STATE_HOME/hyperspool/dev.db by default. Runs, steps, schedules, artifacts, secrets, agent tokens and event handlers live there and survive a restart. The server prints which stores sit where as it boots.

A few things stay in memory only:

• Pending dispatches. Runs themselves come back on restart, re-driven from their recorded history, so work is handed out again rather than lost.
• The bus event history. Handlers and waiters survive; the record of what was emitted does not.
• Users, orgs, projects and personal tokens. spool dev re-creates its dev org and default project on every start, which is why your data is still there. Extra projects, members or tokens you make locally are gone on the next start.

The admin token it prints is kept in <db>.token beside your database (readable only by you) and handed back on every later start, so a restart leaves your console session, its local context and an exported HYPERSPOOL_TOKEN working. Delete that file to roll it. A --db :memory: instance mints a fresh token each time.

Old runs are never aged out locally; the database holds every run until you delete the file.

What the service adds

• People: sign in, belong to several orgs and projects, invite members with roles, and use personal access tokens from anywhere.
• Somewhere to run that isn’t your laptop. Steps run on managed environments the service starts on demand, and on agents of your own when you need them.
• Runs measured in weeks. A 30-day sleep, or an approval that waits for someone to come back from leave, needs something that stays up for it.
• Deploys that don’t drop runs: a run in flight during a server restart is picked up again within seconds.
• Repos: spool repo connect connects a repository, and each push builds its .spool/ci.yaml. See CI from a repo and branch routing.
• Retention by plan: finished runs are kept 14 days on Free, 90 on Team and 365 on Business.
• Usage: what each project consumed, recorded per org.

Where steps run

Locally the engine and an agent are the same process: spool dev and spool run embed an agent advertising shell, polyglot and connector, so every node kind works with nothing to set up.

On hyperspool.dev, the service starts a managed environment when a step needs shell, polyglot, connector or build, and your own agents take anything else. What each step needs:

What you author	Runs on	Capability
A steps: job, or a shell node	an agent	shell
A script: job, or a code node	an agent	polyglot
An http node or a connector action	an agent	connector
A matrix: job, or a fan_out node	an agent, once per item	whatever its body needs
wait, approval, switch, transform, state, emit, event	the engine	none
A workflow: job or node	the engine starts the child	the child’s own steps decide

requires: on a job or node adds capabilities, such as build for a 16-core VM, or a tag only your own agents advertise. Managed environments lists what each environment has.

A run with nowhere to go says so. When no agent and no managed environment can take a step (a capability the managed pool doesn’t provide and none of your agents advertise, or an org on dedicated agents with none running), the run reports unroutable and names the missing capabilities. While an agent that could claim it is starting or busy, it reports waiting_for_agent. Following the run prints either, and spool agent list shows what can run your work.

Moving between them

The workflow files stay the same; you switch the context. A context is a server, an org and a project, and every server command uses one:

spool login https://api.hyperspool.dev  # saves a context for the service, makes it current
spool context list                      # your contexts, and any running spool dev
spool context use local                 # back to the spool dev
spool ls -c local                       # one command against another context
spool context get                       # which one commands use now, and why

spool dev saves a context named local (--name picks another). It becomes current only when you have none; otherwise commands keep going where they went, and spool dev prints how to switch. --project changes the project for one command, and --server <url> talks to a server without a context. In CI, HYPERSPOOL_SERVER with HYPERSPOOL_TOKEN, HYPERSPOOL_ORG and HYPERSPOOL_PROJECT does the same from the environment. Check spool context get first when a run isn’t where you expected. The CLI has the full order.

Local runs stay local: nothing is uploaded from spool dev, and a run id carries the org and project it belongs to, so the two never get mixed up.