tidebase

<h1 align="center">Tidebase</h1>

Agent auth and credential brokering for AI agents, with checkpoints, queues, schedules, and approval gates. In your own Postgres.

<a href="#quick-start">Quick start</a> · <a href="#api-shape">API</a> · <a href="#what-tidebase-stores">Storage contract</a> · <a href="#current-scope">Scope</a>

!Tidebase Studio

Tidebase gives your AI agents an identity and a vault. When an agent calls an API, the call goes through Tidebase, which injects the credential, so the agent and the model never see the key. You can scope it, audit it, and revoke it.

It also keeps the durable parts: checkpoints, live state, queues, schedules, and approval gates, all in your own Postgres. Your code still runs in your app, worker, or job process; Tidebase does not run it. So "this run died at step 7, is it safe to rerun?" has an answer, and "the agent has my GitHub token in plaintext" stops being true.

Docs: <https://tidebase.dev> · Community: Discord · For AI assistants: /llms.txt

Why Tidebase

Agent products usually grow the same operational plumbing:

per-agent identity instead of one shared API key
a vault for third-party secrets and OAuth tokens
a way to call APIs without handing the secret to the model
status tables for runs and steps
checkpoint blobs for partial progress
retry flags and manual-review states
progress streaming to the UI
approval gates for risky actions
token and cost ledgers
webhook glue for recovery and external review surfaces

Tidebase packages that layer around your existing code, plus a credential broker so agents act on real services without holding the keys. It does not run your code (your runtime stays yours), and it is not an LLM proxy or a hosted worker runtime.

Quick Start

Fastest path (no Node needed), prebuilt server image:

docker compose --profile server up -d   # Postgres + ghcr.io/blueprintlabio/tidebase on :7373

Then point any SDK at http://localhost:7373 (npm i @tidebase/sdk or pip install tidebase).

Dev setup (server + Studio from source):

Start Postgres:

docker compose up -d postgres

Install dependencies:

pnpm install

Run the server and Studio:

pnpm dev

Server: http://localhost:7373
Studio: http://localhost:5173

Run the example workflow:

pnpm example

Force a failure after two completed checkpoints:

FAIL_WRITE=1 pnpm example

Copy the run id from Studio or the API, then resume:

TIDEBASE_RUN_ID=run_xxx pnpm example

The plan and fetch-sources steps are returned from checkpoints. Only write-report executes again.

Agent auth and credential brokering

Give an agent its own identity, vault a third-party secret, and let the agent call the API without ever holding the key. Tidebase makes the outbound call with the secret injected, and you can scope, audit, and revoke it.

import { Tidebase } from '@tidebase/sdk'

const tide = new Tidebase({ baseUrl: 'http://localhost:7373', apiKey: process.env.TIDEBASE_API_KEY })

// 1. Vault a secret behind a pinned upstream. The returned resource never carries the secret.
await tide.resources.connect('github', {
  provider: 'static',
  baseUrl: 'https://api.github.com',
  secret: process.env.GITHUB_TOKEN,
  scopesAllowed: ['repo.read'],
})

// 2. Inside a run, request a grant for what the agent needs to do.
const auth = tide.auth(runId)
const grant = await auth.request({
  resource: 'github:repo:acme/app',
  action: 'repo.read',
  scopes: ['repo.read'],
})

// 3. Make the call through Tidebase. The token is injected upstream; the agent and the LLM never see it.
const res = await auth.use(grant.grantId, { method: 'GET', path: '/user' })

Secrets are envelope-encrypted at rest (AES-256-GCM with a KMS-wrapped DEK). baseUrl pins the upstream and scopesAllowed caps any grant, so a leaked grant can't reach an arbitrary host. The proxy blocks private IPs and metadata hosts (SSRF defense), and GET /audit returns grant receipts with no secret material. For OAuth providers you can delegate custody to nango or openbao and Tidebase holds only an opaque connection reference.

Using Tidebase with AI coding agents

Make every AI session in your project use Tidebase correctly:

npx @tidebase/sdk init        # writes a Tidebase section into AGENTS.md/CLAUDE.md (idempotent)

Give your assistant direct access to runs, gates, and recovery via MCP:

claude mcp add tidebase -e TIDEBASE_URL=http://localhost:7373 -- npx -y @tidebase/mcp

Or install the Claude Code plugin (skill + MCP server in one):

/plugin marketplace add BlueprintLabIO/tidebase
/plugin install tidebase@tidebase

Agent-readable docs live at tidebase.dev/llms.txt; every docs page also serves a raw .md twin.

Queues, schedules, and cancellation (v0.5)

Tidebase can now decide when your code runs, while still never executing it:

// durable queue: dedupe, delay, retries with backoff, concurrency caps
await tide.enqueue('generate-report', {
  queue: 'reports',
  input: { topic },
  dedupeKey: `report:${topic}`,
  maxAttempts: 3,
  deadlineMs: 600_000
})

// pull-mode worker: claims ready runs and executes registered workflows
tide.workflow('generate-report', generateReport)
await tide.work({ queues: ['reports'] })

// cron (UTC, 5-field), double-fires are structurally impossible
await tide.schedules.set('daily-digest', {
  cron: '0 9 * * *',
  workflowName: 'daily-digest'
})

// authoritative, one-way cancellation, workers observe it at step/gate
// boundaries; complete/fail can never resurrect a cancelled run
await tide.runs.cancel(runId, { reason: 'customer asked', actor: 'support' })

Push-mode dispatch is also available: configure a queue with an invokeUrl and Tidebase delivers signed run.invoke webhooks to your app instead of waiting for a claim. A queued job IS a run, queued is a lifecycle state, not a second table, so status never drifts.

See docs/production.md for the full lifecycle, replay contract, worker-death recovery model, and deploy discipline (versioned migrations via pnpm migrate, TIDEBASE_AUTO_MIGRATE=0 for expand/contract deploys).

Testing

pnpm test

The suite (84 TypeScript tests + 9 Python integration tests, run in CI on every push) uses the same Postgres in an isolated tidebase_test database. It is invariant-driven rather than coverage-driven: every test asserts a durability or safety guarantee through the public API or SDK, against real Postgres, including concurrency probes for the guarantees that only matter under contention.

What it proves:

completed steps replay from storage and never re-execute, including across crash + recovery-webhook resume
step and run leases are mutually exclusive and fenced, zombie workers cannot write back stale results
input-hash drift on replay is rejected before it can corrupt a run
failure classification honors the resume contract: unkeyed external writes park in manual_review, idempotency-keyed and read-only steps are safe_replay
per-run event logs are gap-free and strictly ordered under concurrent writers
gates resolve exactly once, require the resolve token, and replay their decision on resume
child runs are idempotent by edge name, so resumed fanouts reuse children
recovery webhooks and channel deliveries are HMAC-signed; the SDK rejects unsigned, tampered, or forged payloads
a slow or hung channel endpoint never blocks other writers to the run

See docs/testing.md for the full invariant map and conventions.

API Shape

import { Tidebase } from '@tidebase/sdk'

const tide = new Tidebase()

await tide.run('generate-report', { runId }, async (run, input) => {
  const plan = await run.step('plan', () => makePlan(input))

  await run.state.set({
    status: 'writing',
    progress: 0.7
  })

  return run.step('write-report', () => writeReport(plan))
})

Session Runs

tide.run() fits work shaped like a function. For open-ended execution, a protocol gateway in front of an agent, a REPL, a run that spans many requests, attach to a run as a session instead:

const session = await tide.runs.attach('mcp-session', { input: { agent: 'hermes' } })

// session is a RunContext: step/gate/state/usage/snapshots all work unchanged
await session.step('tool-call', { input: args }, () => callTool(args))

await session.complete({ calls: 12 }) // or session.fail(err)

The session holds the run lease with a background heartbeat (heartbeatMs, default 20s). If the process dies, the heartbeat stops, the lease expires, and the reconciler takes over, requeue or recovery webhook, exactly as if a workflow worker had crashed. A session that loses its lease (onLeaseLost) is a zombie: the server fences its writes. Pass runId to resume an existing session's run; completed steps replay from storage.

For a complete worked example, an MCP gateway that wraps any agent's MCP server in checkpointed tool calls and durable approval gates with one config-line change, see examples/mcp-gateway/.

Resume Contracts

Each step can declare the operational contract Tidebase should record for replay:

await run.step(
  'send-email',
  {
    input: { userId },
    sideEffects: ['email.send'],
    idempotencyKey: `welcome:${userId}`,
    replay: 'auto',
    checkpointInvariant: 'provider accepted the message id',
    verifiedBy: 'email provider response'
  },
  () => sendWelcomeEmail(userId)
)

Tidebase records that contract with the step and shows it in Studio. Final step failures are classified as:

failed_retryable when SDK retries remain.
manual_review when replay is manual, or when side effects exist without an idempotency key.
failed for hard failures.

This does not make external systems exactly-once. It makes the resume decision explicit instead of hiding it in logs and custom retry flags.

Versioned State And Snapshots

run.state.set() and run.state.patch() still update the current live run state. In v0.2 they also append a version to Tidebase's state history.

await run.state.patch({
  status: 'writing',
  progress: 0.7
})

You can label the current state when it becomes a meaningful review or restore point:

await run.state.save('before-approval', {
  reason: 'the user is about to approve sending'
})

Snapshots are a convenience API over labeled state versions for external targets such as reports, artifacts, workspaces, documents, or app state:

await run.snapshots.create('draft-v1', {
  target: { type: 'report', id: reportId },
  state: draft,
  reason: 'first complete draft'
})

The model is intentionally small:

current state = latest version in a stream
snapshot = labeled state version
time travel = read an older version
fork = create new app/run context from an older version
restore = append a new version based on an older version

Tidebase stores and exposes the versions. Your app decides what restore or fork means for its own state targets.

Child Runs And Fanout

Longer agent workflows often fan out to subagents and rejoin their results. Tidebase v0.2 models that as parent/child run edges plus a checkpointed join step.

const results = await run.fanout('research-options', [
  {
    name: 'flights',
    workflow: researchFlights,
    input: { destination }
  },
  {
    name: 'hotels',
    workflow: researchHotels,
    input: { destination }
  },
  {
    name: 'food',
    workflow: researchFood,
    input: { destination }
  }
])

Child run creation is idempotent by parent run and edge name. If the parent resumes, Tidebase returns the existing child runs instead of creating duplicates. The joined result is stored in a normal checkpointed step named join:<fanout-name>.

Gates And Channels

Channels deliver Tidebase events to external surfaces. The alpha supports webhook channels:

await tide.run(
  'generate-report',
  {
    input: { topic: 'channels' },
    channels: [{
      type: 'webhook',
      url: 'https://your-app.example.com/api/tidebase-events',
      events: ['run.failed', 'step.failed', 'gate.created']
    }]
  },
  workflow
)

Gates create durable approval decisions that can be resolved by Studio, a product UI, Slack/Teams adapter, internal tool, or local review page:

const decision = await run.gate('approve-send', {
  prompt: 'Send this report to the customer?',
  data: { reportId },
  channels: [{ type: 'webhook', url: process.env.REVIEW_WEBHOOK_URL! }],
  capability: {
    name: 'report.send',
    scopes: ['report:send'],
    reason: 'agent wants to send an external report'
  }
})

if (decision.decision !== 'approved') {
  throw new Error('Report was not approved')
}

Webhook gate payloads include a resolveUrl and resolveToken so a reviewer can resolve the gate. (Credentials are handled separately by the broker; see the agent auth section.)

When you cannot block on a human, an HTTP handler, a bot, a protocol gateway, use the non-blocking split that run.gate() is built on:

const gate = await run.gates.begin('approve-send', { prompt: 'Send it?', data: { reportId } })
if (gate.status === 'pending') {
  // return now; check back with run.gates.get(gate.gateId) on a later request
}

Gate begin is idempotent per name within a run: re-beginning a resolved gate returns its decision immediately, so retried callers converge on one answer.

Run a local approval channel:

pnpm example:review

In another terminal:

REQUIRE_APPROVAL=1 \
TIDEBASE_CHANNEL_WEBHOOK=http://localhost:8788/tidebase-events \
pnpm example

Open http://localhost:8788, approve the gate, and the workflow continues.

Recovery Webhooks

Tidebase can call back into your app when a run fails and has a recovery webhook configured. The SDK can handle that webhook and resume the matching workflow.

const run = await tide.runs.create('generate-report', {
  input: { topic: 'checkpoints' },
  recoveryWebhook: 'https://your-app.example.com/api/tidebase'
})

Tidebase records each recovery attempt with delivery status, HTTP status, response body, and errors. If TIDEBASE_WEBHOOK_SECRET is set on both the server and SDK, recovery payloads are signed with x-tidebase-signature.

The example includes a local webhook server:

pnpm example:webhook

Usage Tracking

Tidebase can record generic resource usage for a run without proxying model or provider calls:

await run.usage.record({
  kind: 'llm',
  provider: 'openai',
  model: 'gpt-4.1-mini',
  label: 'draft-response',
  inputTokens: 1200,
  outputTokens: 420,
  costUsd: 0.012
})

Usage records are stored with the run, emitted as usage.recorded events, and summarized in Studio. The same ledger can track non-LLM resources:

await run.usage.record({
  kind: 'tool',
  provider: 'internal-search',
  quantity: 8,
  unit: 'queries',
  costUsd: 0.004
})

What Tidebase Stores

runs and attempts
named checkpointed steps
input hashes to prevent stale checkpoint reuse
step resume contracts
live run state
versioned state streams
labeled state versions and snapshots
parent/child run edges
append-only run events
recovery attempts
webhook channel deliveries
durable gates and decisions
credential/capability audit metadata
generic usage records for tokens, units, and cost

Everything is backed by Postgres and designed for self-hosting from day one.

Current Scope

Postgres-backed run store
authoritative run lifecycle with first-class cancellation and deadlines
durable queues (dedupe, delay, priority, retries/backoff, concurrency and rate caps)
cron schedules (UTC, double-fire-proof)
pull-mode workers (tide.work) and push-mode signed invocation webhooks
reconciler (lease-expiry requeue/recovery, deadline cancels, cron, dispatch)
versioned migration runner
TypeScript SDK
Python SDK incl. asyncio (sdk-python/, tidebase.aio)
SvelteKit Studio
live state set/patch
state history and labeled snapshots
child runs and fanout joins
SSE event stream
signed recovery webhooks
webhook channels
durable gates
usage/resource ledger
dogfood workflow
agent auth + credential broker: per-agent keypair identity, run-bound grants, a vault that stores secrets and injects them into proxied calls (the client and the LLM never see them), a policy engine, SSRF defense, and Nango/OpenBao backends

Not In This Alpha

As of v0.7.0 (June 2026). Earlier alphas listed queues, schedules, cancellation, approval gates, API auth, and credential brokering here. Those have all shipped (v0.5 through v0.7): durable queues with retries/backoff, cron, authoritative cancel, exactly-once gates, session runs, opt-in bearer auth, a reconciler that detects dead workers and re-dispatches, and in v0.7 the agent auth control plane and credential broker. What remains deliberately out of scope:

Tidebase-hosted code execution (your runtime stays yours; this one is permanent, not pending)
LLM gateway/proxying
hosted channel adapters
agent memory (conversation or embedding storage)
multi-tenant auth (single shared API key today)
hosted cloud

Alpha Notes

This is ready for local demos and early feedback, not production.

Important limits:

Migrations are versioned and advisory-locked; dev auto-migrates on boot, and TIDEBASE_AUTO_MIGRATE=0 + pnpm migrate gives expand/contract deploy discipline.
API auth is opt-in: set TIDEBASE_API_KEY on the server and the SDK (Studio: VITE_TIDEBASE_API_KEY). Without it the API is open, use only in trusted local/self-hosted environments.
External side effects still need idempotency keys in user code.
Tidebase remembers what happened and can call recovery webhooks, but it does not guarantee that user code will be available to resume.