Record a browser workflow once, get a durable, private, reusable API you and your agents own and call forever.
Explore the docs »
Live App
·
View Demo
·
Report Bug
·
Request Feature
Cairn turns slow browser workflows into private APIs. Useful work is often stuck behind a sequence of clicks: log in, pass an OTP, search, open a detail page, and copy out the answer. Cairn watches that workflow once, compiles the hidden multi-request backend flow, verifies it end to end, and exposes a typed API that belongs to the account that recorded it.
Every API Cairn creates is private to its owning account. There is no marketplace, public catalog, browsing of other people's APIs, payments, tokens, or credits. APIs are called with an account-scoped agent key, and one account cannot see or call another account's APIs.
Production URL used by the SDK and CLI by default:
https://cairn-ai-gamma.vercel.app
Core invariants:
- Agents call typed contracts, not raw browser sessions.
- An operation must verify before it is registered as an API.
- Every API is private to its owning account. Cross-account lookups return
404. - Account-scoped agent keys are SHA-256 hashed before storage and the raw key is shown only once.
- Session secrets, CSRF tokens, cookies, and browser state stay outside agent-visible schemas.
- Invocation logs store hashes and metadata so usage is auditable without exposing full payloads by default.
The lifecycle of one API:
- Record - complete the task once in the browser while Cairn captures interactions and underlying network requests.
- Compile / synthesize - turn the evidence into an operation definition: input schema, output schema, execution plan, fresh-token handling, selectors, allowed domains, success predicates, and OpenAPI.
- Verify end to end - replay the operation against a known input and expected output before anything is registered.
- Register as a private API - wrap the verified operation as a permissioned skill owned by your account, with a stable slug, schemas, README, and verification record.
- Invoke - call the API with your agent key. Invocation is auth-gated and scope-checked; it is never payment-gated.
- Re-verify and repair on drift - scheduled checks catch target-site changes. Repairs publish only after they verify; low-confidence repairs stay in human review.
stateDiagram-v2
[*] --> Submitted
Submitted --> Captured: recording captured
Captured --> Compiled: operation synthesized
Compiled --> Verifying: replay starts
Verifying --> Registered: verification passed
Verifying --> NeedsReview: verification failed
Registered --> Active: private API callable by owner
Active --> Invoked: agent call
Invoked --> Active: success
Active --> Reverify: scheduled check
Reverify --> Active: still valid
Reverify --> DriftDetected: route, schema, token, or selector failure
DriftDetected --> RepairCandidate
RepairCandidate --> Active: repair verifies
RepairCandidate --> NeedsReview: low confidence or expanded permission
The repair path exists in the codebase: reverifyLatest replays the operation, repairLatest re-verifies it, and repairAndVerify proposes a new operation version when drift is detected. A repaired version is registered only when verification passes.
Cairn runs locally as one small Node HTTP server (src/server.js) with no required external services. It already models the production boundaries: account identity, account-scoped agent keys, private API records, skill manifests, verification records, invocation logs, optional Postgres persistence, a Vercel adapter, and AWS artifact/worker infrastructure for the next phase.
flowchart TB
subgraph Clients["Clients"]
Dashboard["Dashboard UI"]
SDK["Node SDK"]
CLI["npx cairn CLI"]
Agent["MCP or OpenAPI agent"]
end
subgraph App["Cairn app"]
Server["src/server.js"]
Vercel["api/cairn.js adapter"]
Apis["apis.js"]
Accounts["accounts.js and agentAuth.js"]
Pipeline["pipeline.js"]
Policy["policy.js"]
Executor["executor.js"]
Repair["repair.js"]
end
subgraph Storage["Durable storage"]
Postgres["Postgres / RDS"]
S3["S3 artifacts"]
Secrets["Secrets Manager"]
end
subgraph Targets["Target websites"]
Sites["Approved target sites"]
end
Dashboard --> Server
SDK --> Server
CLI --> Server
Agent --> Server
Vercel --> Server
Server --> Accounts
Server --> Apis
Server --> Pipeline
Server --> Policy
Server --> Executor
Pipeline --> Repair
Accounts --> Postgres
Apis --> Postgres
Pipeline --> Postgres
Pipeline --> S3
Executor --> Sites
Executor --> S3
Executor --> Secrets
Runtime responsibilities:
| Area | Files | Responsibility |
|---|---|---|
| HTTP server | src/server.js |
Routing, dashboard/static pages, JSON APIs, MCP surface, sandbox demo endpoints |
| Vercel adapter | api/cairn.js, vercel.json |
Runs the same Node app as a Vercel Function |
| SDK and CLI | src/sdk/client.js, bin/cairn.js |
Account creation, list/inspect/record/call private APIs, MCP |
| Accounts and auth | src/cairn/accounts.js, src/cairn/agentAuth.js |
Account creation, agent key issuing, SHA-256 hashing, request authentication, account matching |
| Private APIs | src/cairn/apis.js |
API record creation, owner-scoped lookup, OpenAPI generation, per-API README, demo workflows |
| Persistence | src/cairn/database.js, migrations/*.sql |
Postgres pool, migrations, API loading, account/submission/invocation persistence |
| Pipeline | src/cairn/pipeline.js |
Record, synthesize, verify, register, invoke, reverify, repair |
| Execution | src/cairn/executor.js |
Input validation, deterministic replay, fixture execution, output matching, failure classification |
| Policy | src/cairn/policy.js |
Skill creation, scope checks, input limits, invocation audit records |
| Synthesis and repair | src/cairn/synthesizer.js, src/cairn/repair.js |
Recording-to-operation compiler, fresh-token lifting, drift classification, repaired operation proposals |
| AWS setup | infra/aws/cloudshell-setup.sh, docs/AWS_STORAGE.md, docs/AWS_DATABASE.md |
RDS, S3, SQS, EventBridge, and Secrets Manager setup guidance |
Every protected Cairn API is private to its owning account and gated by an account-scoped agent key.
- Create or attach to an account with
POST /api/accounts. For a new account, the response includesagentAuth.agentKeyonce. Cairn stores only a SHA-256 hash of it. - Store the raw key, for example as
CAIRN_AGENT_KEY, and send it asAuthorization: Bearer <agentKey>on protected calls. - The agent key resolves to exactly one account. Listing, inspecting, invoking, recording, usage, and MCP
tools/list/tools/callonly ever see that account's APIs.
Create or attach to an account:
curl -X POST http://localhost:3000/api/accounts \
-H "Content-Type: application/json" \
-d '{"accountId":"demo-user"}'The response shape:
{
"account": { "id": "demo-user", "status": "active" },
"agentAuth": {
"type": "bearer",
"header": "Authorization",
"scheme": "Bearer",
"agentKey": "cairn_agent_...",
"note": "Store this key now. Cairn only returns the raw agent key once."
},
"next": {
"listApis": "http://localhost:3000/api/apis",
"recordWorkflow": "http://localhost:3000/api/workflows/recordings"
}
}If the account already exists, calling POST /api/accounts without a valid key returns 409 account_auth_required. Re-send with the account's existing agent key.
Follow these steps to run Cairn locally with in-memory state. Add DATABASE_URL later when you want durable state.
- Node.js
>=18 - npm
- Optional: Postgres, only when using
DATABASE_URL
Clone the repository and install dependencies:
git clone https://github.com/arav31/Cairn-AI.git
cd Cairn-AI
npm installCreate a local environment file:
cp .env.example .envUseful local defaults:
| Name | Required | Used for |
|---|---|---|
PORT |
no | Local HTTP port. Defaults to 3000. |
HOST |
no | Bind host. Defaults to 127.0.0.1; use 0.0.0.0 in containers. |
CAIRN_PUBLIC_URL |
production | Public app URL used as the Vercel base URL fallback. |
CAIRN_ENABLE_DEMO_APIS |
no | Set to true to seed the three demo APIs owned by demo-user. |
CAIRN_BASE_URL |
optional | Base URL for the SDK/CLI. Defaults to production. |
CAIRN_ACCOUNT_ID |
optional | Default account id for the SDK/CLI. Defaults to demo-user. |
CAIRN_AGENT_KEY |
protected calls | Bearer key returned once by POST /api/accounts. |
DATABASE_URL |
production database | Postgres connection string for durable APIs, accounts, and logs. |
DATABASE_SSL |
production database | Set to true for RDS. Set to false only for trusted local Postgres. |
DATABASE_SSL_REJECT_UNAUTHORIZED |
optional | Set to true only when a trusted CA chain is configured. |
DATABASE_POOL_MAX |
optional | Postgres connection pool size. Defaults to 3. |
AWS values for the next backend phase are documented in .env.example, docs/AWS_STORAGE.md, and docs/AWS_DATABASE.md.
Start the app:
npm startOpen the dashboard and demo UI:
http://localhost:3000
http://localhost:3000/dashboard
If port 3000 is busy:
PORT=3005 npm startTo explore with the three deterministic demo APIs pre-loaded:
CAIRN_ENABLE_DEMO_APIS=true npm startRun the test suite:
npm testThe package is not published to npm yet. Install it from GitHub:
npm install github:arav31/Cairn-AIThe SDK and CLI call your own private APIs. Create an account once to get an agent key, then list, inspect, record, and call the APIs that belong to that account. There are no credits or payments.
const { CairnClient } = require("cairn");
const cairn = new CairnClient({
baseUrl: "https://cairn-ai-gamma.vercel.app",
accountId: "demo-user",
agentKey: process.env.CAIRN_AGENT_KEY
});
// Create the account once and capture the agent key, returned only once.
const account = await cairn.createAccount();
process.env.CAIRN_AGENT_KEY ||= account.agentAuth.agentKey;
// List the APIs that belong to your account.
const { apis } = await cairn.listApis();
// Call one of your APIs. Auth-gated, never payment-gated.
const result = await cairn.invoke("demo-user/compareInsurancePrices", {
input: {
coverageType: "auto",
zipCode: "78701",
driverAge: 35,
vehicleYear: 2021
}
});SDK surface:
| Method | Description |
|---|---|
createAccount(accountId?) |
Create or attach to an account; captures agentAuth.agentKey. |
listApis() |
List the APIs owned by your account. |
getApi(slug) |
Inspect one API: contract, operation, verification. |
apiReadme(slug) |
Markdown README for one API. |
apiOpenApi(slug) |
OpenAPI document for one API. |
recordWorkflow({ title, targetUrl, goal }) |
Submit a workflow recording to be compiled into a private API. |
invoke(slug, { input }) |
Call one of your APIs. |
mcpToolList() |
MCP tools/list over your APIs. |
mcpCall(name, args) |
MCP tools/call for one of your APIs. |
discovery() |
Fetch /.well-known/cairn.json. |
Default base URL is https://cairn-ai-gamma.vercel.app. The SDK reads CAIRN_BASE_URL, CAIRN_ACCOUNT_ID, and CAIRN_AGENT_KEY from the environment when options are not passed.
The CLI (bin/cairn.js) wraps the SDK. CAIRN_AGENT_KEY is sent as the bearer key; every API is private to your account.
# Create an account, print the agent key once, or re-attach to it.
npx cairn account create --account demo-user
npx cairn login --account demo-user
# List the APIs that belong to your account.
npx cairn apis
# Submit a workflow recording for compilation.
npx cairn record --title "Compare civic records" --url http://localhost:3000/civic --goal "Return record status"
# Call one of your APIs.
npx cairn call --api demo-user/compareInsurancePrices --input '{"coverageType":"auto","zipCode":"78701"}'
# Inspect docs for one API.
npx cairn readme --api demo-user/searchProperties
npx cairn openapi --api demo-user/searchProperties
# MCP.
npx cairn mcp list
npx cairn mcp call --api compareInsurancePrices --input '{"coverageType":"auto","zipCode":"78701"}'Defaults: --base-url https://cairn-ai-gamma.vercel.app, --account demo-user.
Discovery endpoints:
GET /.well-known/cairn.json
GET /openapi.json
GET /api/stateYour APIs require a matching agent bearer key:
GET /api/apis
GET /api/apis/:slug
GET /api/accounts/:id/usagePer-API documents require a matching agent bearer key:
GET /api/tools/:slug/openapi.json
GET /api/tools/:slug/readme.md
GET /api/tools/:slug/verification
GET /api/tools/:slug
POST /api/tools/:slug/invokeAccounts, recording, MCP, and skill-level invoke:
POST /api/accounts
POST /api/workflows/recordings
POST /mcp
POST /api/invokeThere are intentionally no catalog, public tool list, integrations, token, payment, or Stripe webhook routes. Cross-account requests to protected routes return 404.
Invoke an API:
curl -X POST http://localhost:3000/api/tools/demo-user/compareInsurancePrices/invoke \
-H "Authorization: Bearer $CAIRN_AGENT_KEY" \
-H "Content-Type: application/json" \
-d '{
"input": {
"coverageType": "auto",
"zipCode": "78701",
"driverAge": 35,
"vehicleYear": 2021
}
}'Request body: { input, caller? }. Response shape:
{
"apiId": "demo-user/compareInsurancePrices",
"result": {
"allowed": true,
"output": {}
}
}If policy blocks the call, result.allowed is false and the HTTP status is 403. If execution fails after passing policy, the response carries result.error.
MCP list:
curl -X POST http://localhost:3000/mcp \
-H "Authorization: Bearer $CAIRN_AGENT_KEY" \
-H "Content-Type: application/json" \
-d '{ "jsonrpc": "2.0", "id": "tools", "method": "tools/list" }'MCP call:
curl -X POST http://localhost:3000/mcp \
-H "Authorization: Bearer $CAIRN_AGENT_KEY" \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": "call-1",
"method": "tools/call",
"params": {
"name": "compareInsurancePrices",
"arguments": { "coverageType": "auto", "zipCode": "78701" }
}
}'initialize does not require auth; tools/list and tools/call do, and they only ever see APIs owned by the authenticated account.
Submitting a recording is how a workflow becomes a private API. The endpoint accepts the upload today; wiring real artifact capture and synthesis to it is the next recorder/compiler step.
POST /api/workflows/recordings{
"title": "Compare flight refund options",
"targetUrl": "http://localhost:3000/civic",
"goal": "Return refund eligibility, policy notes, and next available action.",
"artifacts": []
}It responds 202 with an accepted submission id. The submission is owned by the authenticated account.
Three deterministic demo APIs are available for local exploration and tests. They run via fixtures, no live sandbox needed, and are opt-in. They are owned by a demo-user account.
Enable them with an environment variable:
CAIRN_ENABLE_DEMO_APIS=true npm startOr when embedding the app:
const { createApp } = require("cairn/server");
const app = createApp({ seedDemoApis: true });Seeded APIs:
| API | Slug | Input required |
|---|---|---|
| Compare Insurance Prices | demo-user/compareInsurancePrices |
zipCode |
| Search Properties | demo-user/searchProperties |
location |
| Business Renewals | demo-user/checkBusinessRenewals |
businessName, state |
When DATABASE_URL is set, demo APIs are only seeded if no stored APIs are loaded and demo seeding is enabled, so a configured database is not polluted by accident.
Local runs work without a database: APIs, accounts, agent keys, submissions, and logs live in process memory and are lost on restart.
For durable state, set DATABASE_URL and run the migrations:
npm run db:migrateMigrations apply in order: 001_initial_schema.sql then 002_private_apis_no_payments.sql. Migration 002 drops credit/payment tables, renames marketplace_listings to apis with an owner_account_id and no pricing columns, and renames the invocation audit column listing_slug to api_slug.
Tables after both migrations:
| Table | What it stores |
|---|---|
accounts |
Account identity: id, status, metadata. |
agent_api_keys |
Account-scoped agent keys: SHA-256 hash, prefix, label, status. |
api_operations |
Full operation definition: schemas, execution plan, OpenAPI, selectors, success predicates. |
skill_manifests |
Permissioned skill wrapper: owner, scopes, risk tier, version pointers. |
apis |
Private API record: slug, owner account, visibility, quality gate, verification freshness, contract. |
verification_records |
Verification history used to check whether an API version still works. |
workflow_submissions |
Recording submissions by account. |
invocation_logs |
Policy decision, input/output hashes, status, caller account, and API slug. |
On boot with DATABASE_URL set, Cairn reloads APIs from Postgres so they can be listed, inspected, invoked, and re-verified after a restart.
AWS is for the next phase: storing recordings, traces, and artifacts in S3, then running synthesis, verification, and repair as workers. The current app does not require AWS.
The helper script is:
infra/aws/cloudshell-setup.shRun it from AWS CloudShell after cloning the repo:
rm -rf Cairn-AI
git clone https://github.com/arav31/Cairn-AI.git
cd Cairn-AI
bash infra/aws/cloudshell-setup.sh
set -a
. ./cairn-prod.env
set +a
npm install
npm run db:migrateThe script writes cairn-prod.env with DATABASE_URL, RDS settings, SQS queue URLs, EVENTBRIDGE_BUS_NAME, and SECRETS_PREFIX. After AWS creates it, sync the non-empty values to Vercel and redeploy. See docs/AWS_STORAGE.md and docs/AWS_DATABASE.md for details.
The app runs locally as a plain Node HTTP server. On Vercel, api/cairn.js adapts the same server to a Vercel Function and vercel.json rewrites routes into it.
npx vercel@latest deploy --prod --force --scope trend-pactCurrent production project:
trend-pact/cairn-ai
https://cairn-ai-gamma.vercel.app
These exist for recorder/compiler/repair testing. They are not seeded as APIs.
/meridian- modern JSON REST CRM sandbox: login, OTP, search, detail./civic- legacy server-rendered records portal with CSRF and ViewState-style hidden state.
Demo recorder, verify, and repair endpoints drive the lifecycle against those sandboxes:
POST /api/demo/record
POST /api/demo/reverify
POST /api/demo/repair
POST /api/demo/drift-civic
POST /api/demo/reset-driftA typical durability demo: record the civic workflow, drift-civic to move a route, reverify to watch it fail, then repair to publish a verified new version.
bin/cairn.js CLI: account, apis, record, call, readme, openapi, mcp
src/sdk/client.js Installable Node SDK
public/ Dashboard + demo UI assets
public/styles.css Shared styling
api/cairn.js Vercel Function adapter
vercel.json Vercel rewrites and function config
src/server.js HTTP server, routes, dashboard, MCP surface, sandbox endpoints
src/cairn/accounts.js Account normalization and durable account creation
src/cairn/agentAuth.js Agent key issuing, hashing, request authentication, account matching
src/cairn/apis.js Private API records, owner-scoped lookup, OpenAPI, README, demo workflows
src/cairn/database.js Postgres pool, migrations, API/account/submission/invocation persistence
src/cairn/pipeline.js Record/synthesize/verify/register, invocation, reverify, repair
src/cairn/executor.js Deterministic workflow execution and output matching
src/cairn/policy.js Skill creation, scope checks, invocation logs
src/cairn/synthesizer.js Recording-to-operation compiler
src/cairn/repair.js Drift classification and repair proposals
src/data/seed.js Synthetic CRM, civic, insurance, and property data
migrations/001_initial_schema.sql Base schema
migrations/002_private_apis_no_payments.sql Drop payments, private per-account apis table
tests/*.test.js Node test runner coverage
npm testRun tests with and without DATABASE_URL; the in-memory path keeps local runs fast and the persistent path exercises migrations and durable reload.
The product foundation - record, verify, register a private API, invoke, re-verify, repair - is in place. The forward plan focuses on durability and ownership, not payments or a marketplace.
- Scheduled re-verification for every registered API, with health signals from pass rate, latency, and freshness.
- Repair proposals backed by trace diffs and confidence scores; auto-publish only safe route/selector fixes after verification.
- Rollback to the last verified operation version, and alerts on repeated drift.
- Team/tenant ownership for APIs, agent keys, and submissions, so a team can share private APIs without exposing them publicly.
- Per-API rate limits, scopes, risk tiers, and domain allowlists.
- OAuth/OIDC for enterprise agent runtimes; audit exports for compliance.
- Connect the browser recorder/compiler output to
POST /api/workflows/recordings. - Store recording bundles, traces, and generated artifacts in S3; resolve secrets only inside workers and redact traces before any LLM-assisted repair.
- Move synthesis, verification, and repair onto workers so long jobs stay off the request path.
- Publish the SDK under a real npm package name.
- Generate typed clients from per-API OpenAPI schemas.
- Add a hosted MCP configuration page for common agent clients, plus examples for ChatGPT Actions, Cursor, n8n, and direct REST.
See the open issues for proposed features and known issues.
Contributions are welcome when they preserve Cairn's account-scoped privacy model and keep APIs auth-gated, not payment-gated.
- Fork the project.
- Create your feature branch:
git checkout -b feature/my-change. - Commit your changes:
git commit -m "Describe the change". - Push to the branch:
git push origin feature/my-change. - Open a pull request.
For bugs and feature requests, use GitHub Issues.
The root project currently has no declared license file. Do not assume MIT, Apache, or any other open-source license applies to the repository root until a root license is added.
Nested packages may have their own licenses; check the relevant subdirectory before reusing code from them.
Project link: https://github.com/arav31/Cairn-AI
Issues and feature requests: https://github.com/arav31/Cairn-AI/issues
- othneildrew/Best-README-Template for the README structure.
- Model Context Protocol for the agent tool interface shape.
- OpenAPI for API contract documentation.
- Node.js, PostgreSQL, Vercel, and AWS for the runtime and deployment stack.