Quickstart

Get Tidebase running and watch a crashed agent run resume from its last checkpoint, in about two minutes. Every command below is non-interactive and safe to run in a fresh clone — if you are an AI agent, you can execute this page top to bottom.

Prerequisites

• Docker (for Postgres)
• Node.js 20+ and pnpm

1. Clone and start

git clone https://github.com/BlueprintLabIO/tidebase
cd tidebase
docker compose up -d postgres
pnpm install
pnpm dev

This starts:

• Server at http://localhost:7373 (REST + SSE API; auto-runs the SQL schema on first boot)
• Studio at http://localhost:5173 (dashboard showing every run, step, gate, and event)

2. Run the example workflow

In a second terminal:

pnpm example

The example wraps three steps — plan, fetch-sources, write-report — in checkpointed steps.

3. Crash it, then resume it

Force a failure after two completed checkpoints:

FAIL_WRITE=1 pnpm example

Copy the run id from Studio (or GET http://localhost:7373/runs), then re-invoke with the same id:

TIDEBASE_RUN_ID=run_xxx pnpm example

plan and fetch-sources return instantly from their checkpoints. Only write-report executes again. That is the core guarantee: completed steps never repeat.

4. Verify

pnpm test

The suite (57 tests against real Postgres) asserts the durability invariants directly: checkpoint replay, lease mutual exclusion, gate exactly-once resolution, fenced zombie writers, and gap-free event ordering.

5. Use it in your own app

import { Tidebase } from '@tidebase/sdk'

const tide = new Tidebase() // reads TIDEBASE_URL, defaults to http://localhost:7373

await tide.run('my-workflow', { runId }, async (run, input) => {
  const a = await run.step('step-a', () => doA(input))
  const b = await run.step('step-b', () => doB(a))
  return b
})

Tidebase never executes your code — but since v0.5 it can re-invoke it for you: durable queues, cron schedules, and automatic requeue on worker death. Or keep your own queue/cron and use the signed recovery webhook.

Next: How to resume a failed AI agent run · The replay contract