# 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

```bash
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:

```bash
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:

```bash
FAIL_WRITE=1 pnpm example
```

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

```bash
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

```bash
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

```typescript
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](queues-schedules-and-cancellation.md). Or keep your own queue/cron and use the [signed recovery webhook](how-to-resume-a-failed-ai-agent-run.md#recovery-webhooks).

Next: [How to resume a failed AI agent run](how-to-resume-a-failed-ai-agent-run.md) · [The replay contract](replay-contract-is-it-safe-to-rerun.md)