Tidebase

Tidebase

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

Quick start · API · Storage contract · Scope

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: dr