SnapState

A production-ready checkpoint and state-persistence API that AI agents use to save and resume multi-step workflows. Agents write checkpoints at each step; if a workflow is interrupted, it resumes from the last saved state rather than restarting.

Phase 1 — Core API, Redis state store, JavaScript SDK
Phase 2 — MCP server, Cloudflare R2 cold storage, Postgres accounts + billing, admin dashboard
Phase 3 — Agent identity + analytics, Python SDK, public docs site, production hardening

Quick start

1. Start infrastructure

docker-compose up -d
# Starts Redis 7 (port 6379) + Postgres 16 (port 5432)

2. Install server dependencies

cd server && npm install

3. Configure environment

cp .env.example .env
# Edit .env — defaults work with Docker Compose for local dev

4. Run database migrations

npm run migrate
# Applies all migrations (001 through 007)

5. Create an admin account + API key

npm start &

curl -X POST https://snapstate.dev/admin/accounts \
  -H "Authorization: Bearer admin_dev_secret_change_me" \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "name": "Your Name"}'

# Generate API key (save it — shown once)
curl -X POST https://snapstate.dev/admin/accounts/1/keys \
  -H "Authorization: Bearer admin_dev_secret_change_me" \
  -H "Content-Type: application/json" \
  -d '{"label": "development"}'

6. Start the dashboard (optional)

cd dashboard && npm install && npm run dev
# Opens at http://localhost:5173

7. View the docs site (optional)

cd docs && npm install && npm run dev
# Opens at http://localhost:5174

Architecture

HTTP request
  → Fastify (v3.0.0)
    → Auth middleware (Postgres key lookup + Redis 5-min cache)
    → Rate limit (Redis sliding window)
    → Route handler
      → checkpoint-writer  (Redis pipeline: HASH + STREAM + meta)
          ↳ usageTracker.track      (setImmediate, non-blocking)
          ↳ analyticsService.update (setImmediate, non-blocking)
          ↳ agentService.updateLastSeen (setImmediate, non-blocking)
          ↳ emitEvent               (fire-and-forget webhooks)
      → resume-engine  (Redis → Postgres → R2 fallback chain)

TTL Manager (background, every 60 s)
  → Scan wf:*:latest keys with TTL < 1 hour
  → archiver: read stream + gzip + R2 upload + Postgres record + delete Redis keys

Graceful shutdown (SIGTERM / SIGINT)
  → 10-second hard timeout
  → ttlManager.stop → app.close → Redis.quit → Postgres pool close

Redis key structure

API reference

All endpoints require:

Authorization: Bearer <api_key>
Content-Type: application/json

All responses include X-Request-Id (UUID v4).

Core checkpoint endpoints

Save a checkpoint

curl -X POST https://snapstate.dev/checkpoints \
  -H "Authorization: Bearer $SNAPSTATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_id": "wf_001",
    "step": 1,
    "label": "research_complete",
    "state": {"findings": []},
    "agent_id": "research-bot"
  }'

Optional headers: X-Checkpoint-TTL: 3600, If-Match: "<etag>" (optimistic concurrency).

Agent identity endpoints

Analytics endpoints

Webhook endpoints

Health endpoints

curl https://snapstate.dev/health
# { status, version, uptime_seconds, redis, postgres, r2, timestamp }

curl https://snapstate.dev/ready
# 200 { status: "ready" } or 503 { status: "not_ready", redis, postgres }

Admin API

All admin routes require Authorization: Bearer <ADMIN_SECRET>.

SDKs

JavaScript SDK

npm install @snapstate/sdk

import { SnapStateClient } from '@snapstate/sdk';

const cp = new SnapStateClient({ apiKey: 'snp_...', baseUrl: 'https://snapstate.dev' });

// Register an agent (upsert — safe to call every startup)
await cp.registerAgent({
  agentId: 'research-bot',
  name: 'Research Bot',
  capabilities: ['web_search', 'summarization'],
  metadata: { model: 'claude-sonnet-4-6', version: '2.1.0' },
});

// Save a checkpoint
await cp.save({ workflowId: 'wf_001', step: 1, state: { query: 'hello' }, agentId: 'research-bot' });

// Resume from last checkpoint
const { latestCheckpoint } = await cp.resume('wf_001');

// Replay history
const { checkpoints } = await cp.replay('wf_001', { fromStep: 1 });

See sdk/ for source.

Python SDK

pip install snapstate-sdk

from snapstate_sdk import SnapStateClient

with SnapStateClient(api_key="snp_...", base_url="https://snapstate.dev") as client:
    result = client.save(workflow_id="wf_001", step=1, state={"query": "hello"}, agent_id="research-bot")
    resumed = client.resume("wf_001")
    history = client.replay("wf_001", from_step=1)

Async support via async_save / async_resume / async_replay and async with context manager.

See sdk-python/ for source and sdk-python/examples/ for usage examples.

MCP Server

Exposes checkpoint tools to any MCP-compatible agent (Claude Desktop, Cline, Cursor) without requiring SDK installation.

cd mcp-server && npm install

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "snapstate": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server/src/index.js"],
      "env": {
        "SNAPSTATE_API_URL": "https://snapstate.dev",
        "SNAPSTATE_API_KEY": "snp_your_key_here"
      }
    }
  }
}

Documentation site

The public docs site (docs/) is a React + Vite + Tailwind app with 8 documentation pages:

• Getting Started — quickstart guide, first checkpoint in 5 minutes
• API Reference — all endpoints with interactive Try It playground
• JavaScript SDK — full method reference with code examples
• Python SDK — sync + async usage, error handling, typed dataclasses
• MCP Setup — Claude Desktop, Cline, and Cursor configuration
• Agent Identity — multi-agent coordination walkthrough
• Webhooks — event types, signature verification, best practices
• Pricing — free tier details, usage rates, interactive cost calculator

Build for production:

cd docs && npm install && npm run build
# Output: docs/dist/ (served at /docs/ by the API server)

Environment variables

Running tests

cd server
npm test                                    # Full test suite
node --test tests/checkpoints.test.js       # Core checkpoint tests
node --test tests/agents.test.js            # Agent identity tests
node --test tests/analytics.test.js         # Analytics tests

cd sdk-python
pip install -e ".[dev]"
pytest                                      # Python SDK tests (18 tests, no server needed)

Tests use Redis db 1 for isolation. Postgres tests require a running database.