60-second demo · Quick start · How it works · Compare · API · FAQ

StateKeep runs your workflows as persistent statechart actors (orders, loans, onboarding, support tickets, AI agent sessions) and lets you ship new versions to actors that are already running.

Each actor moves to the right version based on the path it took to get where it is. You don't replay events, write migration scripts, or keep old workers alive.

You define a machine in XState v5 JSON, deploy it with one HTTP call, and send events. StateKeep stores every actor's state, context (encrypted) and full event history in SQLite or PostgreSQL. It survives crashes, and it can run as a cluster.

Once a workflow is live, three problems show up.

docker compose up -d                                   # API on :3001, dashboard on /dashboard
sk() { curl -s -H 'content-type: application/json' -H "x-api-key: $STATEKEEP_API_KEY" "$@"; }

# 1. Deploy v1 of an order workflow
sk -X PUT localhost:3001/v1/definitions -d '{"id":"order-v1","definition":{"id":"order","initial":"placed","states":{
  "placed":{"on":{"PAY":"paid","HOLD":"on_hold"}}, "paid":{"on":{"SHIP":"shipped"}},
  "on_hold":{"on":{"RELEASE":"shipped"}}, "shipped":{"on":{"DELIVER":"delivered"}}, "delivered":{"type":"final"}}}}'

# 2. Two orders reach "shipped" by different paths
A=$(sk -X POST localhost:3001/v1/actors -d '{"definitionId":"order-v1"}' | jq -r .id)
B=$(sk -X POST localhost:3001/v1/actors -d '{"definitionId":"order-v1"}' | jq -r .id)
sk -X POST localhost:3001/v1/actors/$A/event -d '{"type":"PAY"}';  sk -X POST localhost:3001/v1/actors/$A/event -d '{"type":"SHIP"}'
sk -X POST localhost:3001/v1/actors/$B/event -d '{"type":"HOLD"}'; sk -X POST localhost:3001/v1/actors/$B/event -d '{"type":"RELEASE"}'

# 3. Ship v2 (held orders need an audit before delivery), only for orders that were held
sk -X PUT localhost:3001/v1/definitions -d '{"id":"order-v2","parentId":"order-v1","historyPath":["HOLD","RELEASE"],
  "definition":{"id":"order","initial":"placed","states":{
  "placed":{"on":{"PAY":"paid","HOLD":"on_hold"}}, "paid":{"on":{"SHIP":"shipped"}},
  "on_hold":{"on":{"RELEASE":"shipped"}}, "shipped":{"on":{"DELIVER":"audit"}},
  "audit":{"on":{"APPROVE":"delivered"}}, "delivered":{"type":"final"}}}}'

sleep 2                                               # the migrate worker moves B in the background
sk localhost:3001/v1/actors/$A | jq .definitionId    # "order-v1"  (paid normally: untouched)
sk localhost:3001/v1/actors/$B | jq .definitionId    # "order-v2"  (was held: now gets the audit step)

Both orders were in the same state. Their histories differed, so they got different versions, with no replay and no script.

flowchart LR
    E["Event for actor a"] --> R{"Routing rule (APV):<br/>earliest applicable change-point<br/>for a's family, time and history"}
    R -- "none" --> P["Process the event<br/>on a's current version"]
    R -- "change-point c" --> M["Migrate: map state (μ)<br/>and context (τ) to c's version"]
    M --> R
    M -- "state can't be placed" --> S["Stranded: held for rescue,<br/>never misplaced"]
    P --> C[("Commit state + event<br/>then acknowledge")]

• Every deployment registers a change-point: from logical time t, actors of this family whose history is π go to version d′. π is either an exact history, the actor's whole transition history from its first event (not a substring), or "all actors".
• Every actor carries a history fingerprint, a length-prefixed SHA-256 chain over the events that changed its state. Storage is constant per actor (one fingerprint, plus one per parallel region) and never grows with the history; routing never scans the log. The routing engine indexes the first 64 bits of the fingerprint, and every hit is confirmed against the full 256-bit value, so two histories that share a 64-bit key are never confused (details).
• Before each event, the actor is routed to a fixpoint through every pending version. Then the event runs.
• A migration places the actor in its landing state without running entry actions and without replay, so it never fires side effects (details).

This scheme is called APV (anchor-point versioning). The core properties of its routing model are machine-checked in Lean 4 (formal/APV.lean):

• determinism and progress (routing terminates and never revisits a version);
• completeness;
• safety (an actor is never placed in a state that doesn't exist);
• the parallel-region order;
• the garbage-collection frontier.

The proofs are about the model, not the shipped engine (a compiled WebAssembly module). The engine and the routing code are differentially tested against those same Lean definitions run as a program (test/test_model_oracle.js): the model is proved, and the code is tested against it.

When to pick what:

• Temporal if your workflow is code and replay fits.
• Camunda if BPMN and process modelling teams are the center of gravity.
• StateKeep if the workflow definition is the product: you need to version it as data, change it for instances already running, and audit it as plain database rows.

npx statekeep serve                    # SQLite in ./statekeep-data, API + workers on http://127.0.0.1:3000
curl localhost:3000/v1/health          # {"status":"ok",...}
npm install @statekeep/sdk             # client: deploy, spawn, send, preview

git clone https://github.com/mmujtaba0085/StateKeep && cd StateKeep
cp .env.example .env
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"   # paste as STATEKEEP_ENCRYPTION_KEY
# also set STATEKEEP_ADMIN_KEY and STATEKEEP_API_KEY in .env
docker compose up -d
curl localhost:3001/v1/health          # {"status":"ok",...}

npm install
cp .env.example .env                   # set the three keys as above
npm start &                            # API server
npm run migrate-worker &               # background migrations
node --env-file=.env src/workers/scheduler-worker.js &   # timers / delayed events

• Proofs: the routing model is machine-checked in Lean 4 with no sorry and only standard axioms (formal/). This covers the model, not the engine binary.

• Model-vs-code testing: the live routing code, the deploy-preview code and the analysis driver are compared hop-by-hop with the Lean definitions on random registries.

• Fault injection: npm run chaos and npm run chaos:workflows run generated workflows while they:

  • kill API servers, workers and services;
  • deploy new versions mid-flight;
  • fire storms of concurrent, duplicate and unknown events.

  Every actor is then checked against a ground-truth model kept independent of the system under test: no lost or duplicated events, no misrouted or misplaced actors. The full campaign (scripts/chaos-campaign.sh) runs on SQLite, PostgreSQL and a 2-server PostgreSQL cluster, at normal and hard intensity. The latest run covered 2,600 actors and 54 live deployments (2,417 migrations checked), with 42 API-server kills, 21 database-connection drops, 29 service crashes and 52 worker kills: 0 violations (results, raw summary). All runs were on a single host with generated workflows.

• Test suites: unit, property-based, integration, statechart (SC1–SC18), cluster and end-to-end. Run them with npm run test:all.

Everything else is in .env.example and docs/deployment.md.

Issues and pull requests are welcome. Read CONTRIBUTING.md, then run npm run test:all. If you're evaluating StateKeep for a real workload, open an issue describing it. Real-world cases shape the roadmap.

If StateKeep is useful to you, a ⭐ helps other people find it.

Apache 2.0 with the Commons Clause. Commercial licensing: mmujtaba0085@gmail.com.