DEV Community: StateKeep

The XState persistence problem is five years old. Here is what we built to finally solve it.

StateKeep — Mon, 25 May 2026 03:41:27 +0000

In 2019 someone opened a GitHub issue in the XState repository. The title was "How do I persist XState actor state between server restarts?" It became one of the most-upvoted open issues in the repo. The answer from the core team was honest: XState doesn't handle persistence. Serialize the state object and store it yourself.
Five years later, that answer hasn't changed. Dozens of blog posts exist showing developers how to roll their own persistence layer. Every single one of them is a developer reinventing the same infrastructure that has nothing to do with their actual product.
We got tired of reinventing it. So we built StateKeep.

The problem with rolling your own
Persisting XState state sounds straightforward. Call actor.getSnapshot(), serialize it, store it in Redis or Postgres. On startup, rehydrate. Done.
It works. Until it doesn't.
XState v5 shipped in 2023 and changed the snapshot format. Teams with actors persisted in the old format had a bad week. Some serialized state just crashed on deserialization. Others silently corrupted context. The format was never treated as a public API — because XState is a library, and libraries are not responsible for what you do with their output.
Even before the v5 breakage, there was the migration problem. Your order management workflow lives in a table. You have 40,000 active orders. Your product team needs to add a quality review step. You write a migration script. You test it in staging. You run it in production at midnight. You discover that 847 orders were in an edge state you didn't account for. You spend the next three hours fixing them manually.
This is not a XState problem. It is not a developer competence problem. It is an infrastructure gap. There is no layer between "XState the library" and "your application database" that takes responsibility for keeping actors alive through code changes.

What Stately built — and where it ends
Stately saw this problem. They built Stately Cloud: a hosted service that persists your XState actors, keeps them alive between restarts, and gives you an API to send events and read state.
It is a real solution for the right use case. If you are building a side project, you are a JavaScript shop, and your data can live on their servers — Stately Cloud is worth evaluating.
Three things make it a hard no for a large chunk of teams:

Data residency. Your actor context contains your customer's data. For any team in fintech, healthcare, insurance, or enterprise SaaS with compliance requirements — sending that data to a third-party hosted service is often not an option. Stately Cloud has no self-hosted deployment.
Language lock-in. Stately Cloud requires XState. Not "XState-compatible JSON" — actual XState TypeScript. If your backend is Python, Go, Java, or anything other than JavaScript, you are locked out.
No path-based migration. When you update a workflow definition, Stately Cloud does not help you decide which of your 40,000 in-flight actors should move to the new version and where they should land. You write that logic yourself. That third one is the one we spent the most time on.

The migration problem is harder than it looks
Here is a scenario that sounds simple but breaks every migration tool I have seen.
You have a loan application workflow. 50,000 active applications. You need to add a compliance check step — but only for applications that went through the paid verification path, because that is the regulatory requirement for that specific path.
Your database has 50,000 actors. Some paid the verification fee. Some waived it. Both groups are currently in awaiting_documents. They are in the same state. They look identical to any query that reads current state.
Any system that routes migrations by current state will treat them identically. That is the wrong answer.
The correct answer requires looking at each actor's history. An actor that processed PAY_FEE belongs in the new compliance check flow. An actor that processed WAIVE_FEE does not. The only way to know which group an actor belongs to is to look at what events it has already processed.
This is the problem we built StateKeep to solve.

How StateKeep handles it
StateKeep is a self-hosted statechart hosting platform. You deploy XState-compatible JSON definitions via HTTP, spawn actors, and send events. Any backend language works — Python, Go, Java, Node, anything with an HTTP client.
When you deploy a new version, you declare a historyPath:
json

{
  "id": "loan-v2",
  "parentId": "loan-v1",
  "historyPath": ["SUBMIT_INFO", "PAY_FEE"],
  "definition": { ... }
}

StateKeep evaluates every actor. Each one carries a fingerprint of its event history — a rolling FNV-1a hash of every event type it has processed in order. Actors whose history matches the declared path migrate. Actors whose history does not match stay on the current version.
Alice paid the fee. Her fingerprint matches. She migrates to loan-v2, where the new definition routes her through the income verification step before approval.
Bob waived the fee. His fingerprint does not match. He stays on loan-v1, continuing normally.
Both actors keep running. Neither restarts. Neither loses context. No migration script. No midnight deployment anxiety.
The routing is not based on engineering confidence. It is backed by a formal mathematical proof that guarantees every actor ends up on exactly the correct version, with no actor evaluated twice, regardless of timing or evaluation order. The algorithm runs in native C at p50 1.26µs per actor — 50,000 actors in under a second on modest hardware.

What it looks like in practice
typescript

import { createClient } from '@statekeep/sdk';

const sk = createClient({
  baseUrl: 'https://your-instance.com',
  apiKey: 'sk_...'
});

// Deploy a machine definition
await sk.deploy('loan-v1', {
  id: 'loan', initial: 'submitted',
  states: {
    submitted:       { on: { SUBMIT_INFO: 'under_review' } },
    under_review:    { on: { PAY_FEE: 'awaiting_docs',
                             WAIVE_FEE: 'awaiting_docs' } },
    awaiting_docs:   { on: { APPROVE: 'approved', REJECT: 'rejected' } },
    approved:        { type: 'final' },
    rejected:        { type: 'final' },
  }
});

// Spawn one actor per loan application
const actor = await sk.spawn('loan-v1', {
  applicantId: 'usr-001',
  loanAmount: 25000
});

// Send events as things happen in your system
await sk.send(actor.actorId, 'SUBMIT_INFO');
await sk.send(actor.actorId, 'PAY_FEE');

// Later — deploy a new version targeting only paid-path actors
await sk.deploy('loan-v2', newDefinition, {
  parentId: 'loan-v1',
  historyPath: ['SUBMIT_INFO', 'PAY_FEE'],
});
// Only actors who processed PAY_FEE migrate. Everyone else stays.

You can preview the migration before committing:

typescript

const preview = await sk.preview('loan-v2', newDef, { parentId: 'loan-v1', historyPath: ['SUBMIT_INFO', 'PAY_FEE'] });
console.log(preview.migration.wouldMigrate.length); // 1,203
console.log(preview.migration.wouldStay.length);    // 847

The preview uses the exact same evaluation function as the live deployment. What you see is what will happen.

What it does not do
StateKeep tracks state. It does not execute your code.
Guards (guard: 'isEligible') are ignored entirely — every transition fires unconditionally when the matching event arrives. Do not rely on guards to protect invalid transitions. Check eligibility in your backend before calling send. Actions (actions: 'sendEmail') are no-ops — state changes but nothing executes. Your backend reads the new stateValue from the response and handles side effects itself.
This is a deliberate design choice. The engine is pure data: JSON definitions in, state transitions out. No secrets, no database connections, no application context. Your business logic stays in your application where it belongs.
The upside: migrations never accidentally re-fire side effects. 50,000 actors migrating to a new version do not trigger 50,000 emails.

The current state
StateKeep is at early access. The platform is running in production, 400+ tests passing, the APV engine active, self-hosted on a VPS with AES-256-GCM encryption at rest, continuous backup via Litestream, full dashboard, CLI tooling, and a TypeScript SDK.
We are looking for developers who have hit the XState persistence problem or the workflow migration problem in production — people who have written that midnight migration script, who have lost actor state on a server restart, who have kept two versions of workflow code running forever because there was no clean upgrade path.
Free access for anyone willing to give honest feedback. Reach out at statekeep.support@gmail.com or comment below.

We built a statechart hosting platform where two actors in the same state can migrate to different versions — here's why that matters

StateKeep — Thu, 21 May 2026 15:10:04 +0000

If you have built anything with long-running stateful workflows — loan approvals, order processing, subscription lifecycles, insurance claims, onboarding funnels — you have probably hit a wall that nobody talks about cleanly.
You need to change the workflow. But you already have thousands of instances running.

The problem nobody has a clean answer to
The standard options are all painful.

Wait for instances to drain naturally. Fine if your workflows complete in minutes. Useless if they run for weeks or months waiting for human approval, document submission, or payment settlement.
Write a migration script. You query your database, move rows between tables, pray nothing is mid-transition, and hope you did not accidentally re-trigger a side effect for 40,000 customers.
Keep old code running forever alongside new code. Now you are maintaining two versions of your business logic indefinitely, and the operational complexity compounds with every release.
Temporal's approach: version markers in your workflow code. This works, but it means every code change requires careful getVersion() calls throughout your workflow function, and a non-determinism error on a long-running production workflow is a genuine incident. We have seen threads from teams where a change they believed was backwards-compatible broke in rare production scenarios after deployment.
None of these answers are wrong exactly. They are just the best available options in a space where the fundamental problem — migrating running stateful instances to a new version of their logic — has never been solved cleanly.

What we built
StateKeep is a statechart hosting platform. You upload an XState-compatible machine definition, spawn actors against it, and send events. StateKeep handles persistence, event history, encryption at rest, and version migration.
The part that is different: when you deploy a new version, each running actor migrates based on its event history fingerprint — not its current state.
Every actor carries a compact hash of every event type it has processed, in order. When you deploy a new version with a historyPath, the platform checks each actor's fingerprint against the path you declared. Actors whose history contains that path migrate. Actors whose history does not contain it stay on the current version.
The consequence: two actors in the same state can receive different migration decisions in the same deployment.

The concrete example
A loan application workflow. Two customers, Alice and Bob. Both are currently in awaiting_documents.
Alice paid the verification fee to get there. Bob waived it.
You deploy a new version that adds an income verification step — but only for customers who paid the fee, because that is the regulatory requirement for that path.
You declare:
json

{
  "id": "loan-v2",
  "parentId": "loan-v1",
  "historyPath": ["START_APPLICATION", "SUBMIT_INFO", "PAY_FEE"],
  "definition": { ... }
}

The platform evaluates every actor. Alice's history contains that path. She migrates to loan-v2, landing in the new income_verify state. Bob's history does not contain PAY_FEE. He stays on loan-v1, continuing to awaiting_documents as before.
Both actors keep working. Neither restarts. Neither loses context. No migration script was written. No side effects were re-fired. The decision was made per-actor, based on history, in under a second.

What this looks like in practice
Deploy a new version targeting a specific path:
typescript

import { createClient } from '@statekeep/sdk';

const sk = createClient({
  baseUrl: 'https://your-instance.com',
  apiKey: 'sk_...'
});

// Deploy v2 — only actors who paid the fee are eligible
await sk.deploy('loan-v2', loanV2Definition, {
  parentId:    'loan-v1',
  historyPath: ['START_APPLICATION', 'SUBMIT_INFO', 'PAY_FEE'],
});

// Deploy a wildcard version — all actors migrate
await sk.deploy('order-v2', orderV2Definition, {
  parentId: 'order-v1',
  // no historyPath = all actors eligible
});

Preview what will happen before committing:

const preview = await sk.preview('loan-v2', loanV2Definition, {
  parentId:    'loan-v1',
  historyPath: ['START_APPLICATION', 'SUBMIT_INFO', 'PAY_FEE'],
});

console.log(preview.migration.wouldMigrate.length); // 1,203 actors
console.log(preview.migration.wouldStay.length);    // 847 actors

The preview calls the exact same evaluation function as the live deployment. What you see is what will happen.

What StateKeep does and does not do
StateKeep is a state tracker, not a side effect executor. It does not run your action handlers or evaluate your guards.
Guards (guard: 'isEligible') are stubbed to false — guarded transitions never fire. Actions (actions: 'sendEmail') are no-ops — state changes but nothing executes. Your backend reads the new stateValue from the event response and handles side effects in its own code.
This is intentional. It means migration never accidentally re-fires side effects. An actor migrating from v1 to v2 does not trigger emails, charges, or notifications — because StateKeep never ran any of those in the first place.
The supported pattern: model routing decisions as explicit events rather than guards. Your backend evaluates the condition and sends APPROVE_FAST_TRACK or APPROVE_STANDARD. The machine routes deterministically from there. No guards needed.

Rescue deployments
When a buggy version reaches actors before you catch it, you deploy a rescue version targeting only the actors whose history includes the buggy path:

typescript

await sk.deploy('loan-v2-rescue', fixedDefinition, {
  parentId:    'loan-v2-buggy',
  historyPath: ['START_APPLICATION', 'SUBMIT_INFO', 'PAY_FEE', 'TRIGGER_BUG'],
});

Only actors whose history contains TRIGGER_BUG migrate to the fix. Everyone else is unaffected. No system-wide freeze. Forward-only. No rollback.

The audit trail
Every routing decision is logged. For every actor evaluated in a deployment, there is a record of: which version it was on, which version it moved to (or why it stayed), its history fingerprint at decision time, and the registered prefix hash it was compared against.
GET /v1/actors/:id/decisions returns the full routing history for a single actor. When a customer asks "why didn't my application get the new income verification step," the answer is in the database, not in a support ticket.

Early access
We are at early access stage. The platform is running on a VPS, 432 tests passing, real migration engine deployed.
We are specifically looking for developers who have hit the workflow migration problem in production — people who have written migration scripts they were not happy with, people who have hit non-determinism errors on Temporal after a versioning change, people who have kept old workflow code running forever because they had no other option.
Free access, no strings attached. We want honest feedback from people who understand the problem space. If that is you, reach out at statekeep.support@gmail.com with a sentence about what you are building. We will get you set up.
We are not looking for validation. We are looking for the edge cases we have not thought of yet.