Chronos/DBWaitlist

Gateway

Runs

One task, for one tenant, in its own copy of the data: start a run, hand it to an agent over SQL or MCP, propose its changes.

Self-hostedChronos Gateway runs on your own servers today. Releases and install script. The engine under it: Chronos DB, self-hosted

What a run is

A run is one agent task for one tenant. Your backend starts it with a developer key (cgk_...) and gets a run token (cgr_...) to hand to the agent. The agent reads and writes in the run’s world: a private copy of the attached tables that holds only that tenant’s rows. Nothing reaches your database until the run is proposed and its merge is within the rules, or a person approves it.

This page describes gateway 0.4.4 on Chronos DB 0.6.2.

  1. Your backend starts a run for one tenant: POST /v1/runs.
  2. The agent sends SQL or MCP tool calls with the run token. They run in the run’s world.
  3. Your backend, or the agent, proposes the run: POST /v1/runs/:id/propose.
  4. Within the rules, the change is written to the database in one transaction, each row locked and compared first. A rule broken, it is held for a person. A row changed meanwhile, it is a conflict and nothing is written.
  5. Webhooks tell your backend what happened.

Every call sends Authorization: Bearer and a token. Bodies are JSON. Errors read as below; code is one of the gateway’s own codes or a SQLSTATE from the engine.

an error
{"error": {"message": "this run's time ran out before it merged", "code": "expired"}}

Start a run

POST /v1/runs, with a developer key
curl -s localhost:7400/v1/runs -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \  -d '{"tenant": {"org_id": 42}, "intent": "remove the duplicate lead", "end_user": "user_7"}'
FieldTakesMeaning
tenantrequiredWhose rows the run may touch. {"org_id": 42}, {"column": "org_id", "value": 42}, "org_id = 42", or just 42 when a tenant column was set at connect. In the text form only a plain column name and = are taken; the value is a number, true, false or a quoted string.
intenttextWhat the run is for. Shown to approvers, in the console and in Slack messages.
end_usertextWho the run acts for. Kept with the run, sent in merge.held, and used as the default end_user of an approval link.
sourcea database’s nameWhich connected database the run works beside, when the gateway has several. The header X-Chronos-Source does the same. Without one: the first database (default). A name that is not connected: 404 no_source.
ttl_secondsa numberHow long the run and its token last, from 1 to GATEWAY_RUN_TTL in seconds. A run can ask for less than the default, not more. Out of range: 400.
may_changethe engine’sPart of the scope the run declares with its world, passed to the engine as given.
max_rowsthe engine’sPart of the declared scope, passed to the engine as given.
max_deletesthe engine’sPart of the declared scope, passed to the engine as given.
row_rulestextConditions each row the run changes must keep, on top of the policy’s: "payments: new.amount <= 100". A row that breaks one is outside the run’s scope, so its merge is held. They can only make the policy stricter.
act_as{"role", "settings"}Postgres only. The run’s merge is written as that role with those settings, so your grants and row-level security judge it. See Write as the end user.
run_idany JSONYour own id for the task, recorded on the run’s world.
prompt_versionany JSONRecorded on the run’s world.
modelany JSONRecorded on the run’s world.
metaany JSONAnything you want kept with the run. Returned with it as meta.

The engine holds a run to its tenant only in tables that have the tenant column, so the gateway refuses a column no attached table has.

AnswerWhen
201The run was made. Its world is forked and its token is in the answer.
400tenant is missing or not in one of its forms, or ttl_seconds is out of range.
400 tenant_columnNo attached table has that column. The message lists the attached tables and their columns.
400 act_asact_as is not an object, has a key other than role and settings, has no role, or settings is not an object.
404 no_sourceNo database is connected under that name.
429 too_many_runsThe tenant has had GATEWAY_RUNS_PER_HOUR runs in the last hour. A run.refused event is sent and no run is made.

What comes back

201
{  "id": "run_...",  "token": "cgr_...",  "sql_url": "https://gateway.example.com/v1/runs/run_.../sql",  "mcp_url": "https://gateway.example.com/v1/runs/run_.../mcp",  "status": "open",  "tenant": {"column": "org_id", "value": 42},  "intent": "remove the duplicate lead",  "end_user": "user_7",  "meta": {},  "source": "default",  "expires": 1767225600000,  ...}
FieldMeaning
idThe run’s id. It starts with run_.
tokenThe run token. It starts with cgr_ and is shown only now: the gateway keeps its hash. This is what the agent gets.
sql_urlGATEWAY_PUBLIC_URL + /v1/runs/:id/sql.
mcp_urlGATEWAY_PUBLIC_URL + /v1/runs/:id/mcp.
statusopen for a new run. See Statuses.
tenantThe tenant as {"column", "value"}, whatever form you sent.
created, updated, expiresTimes in milliseconds since 1970. expires is when the run and its token end.
hold_expiresNull until the run is held; then when the hold ends.
outcomeNull until something happens; then the last answer about its merge: merged rows, the reasons it is held, conflicts, or the error.
mergesThe ids of the merges that wrote the run to the database. Several for a run approved in parts. An undo names them.
sourceThe database it works beside: default, or the name another was connected under.
world, agentThe names of the run’s world and of its engine agent. Both are the run’s id.

Tenant scope

The engine holds each run’s agent to one tenant. Every read and write of a table that has the tenant column is filtered to that tenant, whatever SQL the agent sends: joins, subqueries, set row_security = off and past versions included.

  • A table with the tenant column: the run reads and changes only its tenant’s rows.
  • A child table: a table without the column but with a foreign key to one that has it, up to three hops away (order_items.order_id to orders.id), is held to the tenant through that key. A run reads and changes only the rows whose key names one of its tenant’s rows, and a row it writes must name one.
  • A shared table: a table with neither the column nor such a foreign key. Every run reads it in full, and a run’s writes to it are refused (42501), since every other tenant would see them. Give such tables the column or a key to a table that has it, change them outside runs, or do not attach them.
  • Masked columns read masked in a run, wherever the agent reads them. See Rules, labels and masks.

A run’s world keeps the tables as they were when it started. Between refreshes an agent may read a row that is out of date. That is safe: the merge compares every row it writes with the database, and the default rule check_reads = true holds a change if a row it read has changed. Only the run’s own tenant’s rows count for that check.

SQL

POST /v1/runs/:id/sql takes the run token, not a developer key. The body has sql and, optionally, params. The SQL is the engine’s, in Postgres’s dialect, whatever database the gateway is beside.

the agent’s calls
curl -s localhost:7400/v1/runs/$RUN/sql -H "Authorization: Bearer $RUN_TOKEN" -H 'Content-Type: application/json' \  -d '{"sql": "select id, name, owner from leads"}'curl -s localhost:7400/v1/runs/$RUN/sql -H "Authorization: Bearer $RUN_TOKEN" -H 'Content-Type: application/json' \  -d '{"sql": "delete from leads where id = 3"}'

The answer is the engine’s: {"results": [{"command", "columns", "types", "rows"}]}, one result per statement. An answer longer than GATEWAY_RUN_MAX_ROWS rows (1,000 by default) is cut, and that result says "truncated": {"rows": n, "kept": 1000}.

A run works only inside its own world. The gateway refuses SQL that would leave the world or merge it, even when the statement sits after others in one request. Words inside strings, quoted names, comments and dollar-quoted bodies are not mistaken for statements.

AnswerWhen
400sql is missing or empty.
400 forbidden_sqlA statement begins with merge, use, fork, discard, undo, restore or checkout, or is create, drop or alter of a branch or world.
401The token is missing, is not a run token, or is another run’s.
403, code the run’s statusThe run is not open or in conflict: its agent cannot act any more. The code is the status, such as held or merged.
403 expiredThe run’s time ran out.
409 world_lostThe run’s world is gone. See A lost world.
429Past GATEWAY_RUN_STATEMENTS_PER_MINUTE.
a SQLSTATEThe engine refused the statement. 42501 for a write to a shared table, for example.

MCP

Agents that speak MCP use mcp_url with the same run token. POST /v1/runs/:id/mcp takes one JSON-RPC message and answers MCP over HTTP. The agent gets only the tools that work inside a world, each pointed at the run’s world. Tools that fork, merge or discard worlds, or manage policies and reviews, are left out of tools/list and refused by name.

ToolNotes
describePointed at the run’s world.
findPointed at the run’s world.
sqlHeld to the same rule as POST /v1/runs/:id/sql: no statement that merges or leaves the world.
putPointed at the run’s world.
diffPointed at the run’s world.
historyPointed at the run’s world.
check_readsPointed at the run’s world.
merge_previewA preview only. Its target can be sent with a propose to settle rows against main as the preview saw it.
rebasePointed at the run’s world.
checkpointPointed at the run’s world.
rollbackPointed at the run’s world.
merge_policiesReads the policies. Not tied to a world.
check_merge_policyNot tied to a world.
merge_checksReads the merge checks. Not tied to a world.

Refusals come back as JSON-RPC errors with HTTP 200.

JSON-RPC codeWhen
-32001The run cannot act: it is not open or in conflict, or its time ran out.
-32002Past GATEWAY_RUN_STATEMENTS_PER_MINUTE. Each tool call counts as one statement.
-32601The tool is not available to a run.
-32602The sql tool was given a statement a run may not run.

Beside MongoDB a run also has MongoDB’s own tools: mongo_find, mongo_count, mongo_insert, mongo_update_one, mongo_update_many, mongo_delete_one and mongo_delete_many over MCP, and the same as POST /v1/runs/:id/mongo with tool and arguments. Each runs as SQL in the run’s world, so the tenant’s scope, masks and rules apply as with SQL. See MongoDB tools.

Read its changes

GET /v1/runs/:id/changes answers with a developer key or the run’s own token. It shows what the run’s world changes, in plain words and as rows, and the world’s version.

GET /v1/runs/:id/changes
curl -s localhost:7400/v1/runs/$RUN/changes -H "Authorization: Bearer $KEY"
FieldMeaning
statusThe run’s status.
versionThe world’s version now. Send it with an approval to approve exactly what you looked at.
totalHow many rows the run changes.
summaryCounts in words: ["3 leads changed", "1 lead removed"].
tablesCounts per table, as the engine gives them.
changesEach change as {text, kind, table, key, before, after}. kind is insert, update or delete. text reads like “Remove lead “Hooli””.
moreTrue when there are more changes than this page shows.
reasonsWhy the run is held, when it is.
  • ?limit= sets how many changes come back: 200 by default, 2,000 at most.
  • How changes read is set by labels: names for tables and columns, the column that titles a row, and columns hidden from approvers. See Rules, labels and masks.
  • Beside MongoDB a document’s change reads by field path: “Change the address.city of lead “Acme” from Pune to Mumbai”.
  • For a run that is over (merged, rejected, expired, discarded, undone) the answer is its record: status, outcome, and empty changes and summary. It reads even after its database was disconnected.

Propose

Proposing asks for the run’s changes to be written to the database. POST /v1/runs/:id/propose answers with a developer key or the run token. The engine judges the change against the merge policy, inside the merge.

POST /v1/runs/:id/propose
curl -s localhost:7400/v1/runs/$RUN/propose -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' -d '{}'
AnswerRun becomesMeaning
200 {"status": "merged", "merged": n}mergedWithin the rules: written to the database in one transaction, each row locked and compared first. merge.landed is sent with by: "rules".
202 {"status": "held", "reasons": [...], "message": "..."}heldA rule was broken. Nothing is written. The run waits for a person for GATEWAY_HOLD_TTL. merge.held is sent. See Approvals.
409 conflictconflictA row the run changed was changed in the database, or in main, since its world was forked. Nothing is written. The error carries conflicts, the rows. merge.conflict is sent.
409 expiredunchangedThe run’s time ran out before it merged.
409 heldunchangedThe run is already held: approve or reject it.
409, code the run’s statusunchangedThe run is over: merged, rejected, expired, discarded, undone or partly_undone.
409 world_lostfailedThe run’s world is gone. See A lost world.
429 too_many_proposesunchangedPast GATEWAY_RUN_PROPOSES_PER_MINUTE. No write is tried.
another refusal by the enginefailedThe merge failed for another reason. The error and the run’s outcome say why, with the engine’s code. run.failed is sent. A row that Postgres’s own row-level security refuses under act_as answers 42501 this way.
the engine’s own failureunchangedThe engine could not be reached, or answered with a 5xx. That is not the run’s fault, so nothing about the run changes. Try again.

A run can be proposed while it is open, in conflict or failed. The body may be empty. It takes:

FieldMeaning
evidenceFrom 0.4.0. [{kind, uri, sha256, note}]: what the change rests on, kept with the run. See Evidence.
confirm_deletesPassed to the engine’s merge. It goes with the policy rule confirm_deletes_over, which makes a merge that deletes more than a set number of rows need the count.
by_columnstrue: a row where the two sides changed different columns combines.
resolve"ours" (the run’s), "theirs" (main’s) or "fail".
rowsSingle rows: {"orders/7": "ours" | "theirs" | "delete" | {the row to keep}}.
targetThe target number a preview of the merge gave (the run’s MCP merge_preview).

Settle a conflict

A run in conflict changed rows that main, or the database, changed too since its world was forked. Proposing the same way again fails the same way. Propose again with the conflict settled, or have a person approve it settled. The engine judges the settled merge under the merge policy like any merge.

  • "by_columns": true: a row where the two sides changed different columns combines. Try this first.
  • "by_columns": true with "resolve": "ours" or "theirs": that side wins only for the columns both changed. Each column only one side changed keeps its value.
  • "rows": settle single rows, by key.
  • "resolve" without by_columns: whole rows, overwriting the other side’s changes to other columns. Use it last. A policy with overwrite = false, the default, sends it to a person.
  • "target": rows settle against main as that preview saw it.
propose again, combining by column
curl -s localhost:7400/v1/runs/$RUN/propose -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \  -d '{"by_columns": true}'

An agent whose run is in conflict can still send SQL and MCP calls, so it can read the rows again and change its work before the next propose.

Evidence with a propose

A propose can carry what the change rests on: a ticket, an order snapshot, a document. Whoever approves the run sees it.

propose with evidence
curl -s localhost:7400/v1/runs/$RUN/propose -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \  -d '{"evidence": [{"kind": "ticket", "uri": "https://tickets.example/42", "sha256": "ab12...", "note": "customer asked"}]}'
  • At most 50 items, each {kind, uri, sha256, note}. A malformed one is refused with 400 evidence.
  • Kept with the run as evidence: {items, in_engine}, and shown by GET /v1/runs/:id.
  • In the engine too, where the engine has ATTACH EVIDENCE (engine 0.6.0, which gateway 0.4.0 bundles): each item is attached to the run’s world, so a merge policy’s require_evidence can ask for kinds. in_engine says whether it was. See Evidence.
  • Store links and hashes, not the content or personal data.

Child runs

A run can hand part of its task to a sub-agent. A child run has its own token and its own world, forked from the parent run’s world, and its propose merges into the parent’s world, not your database.

POST /v1/runs/:id/children
curl -s localhost:7400/v1/runs/$RUN/children -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \  -d '{"intent": "fix the stage of each lead", "may_change": "leads.stage"}'# 201: a run, with its own token (only now) and "parent": "<the parent run's id>"
  • It takes intent, may_change, max_rows, max_deletes, row_rules, ttl_seconds, run_id and meta, as POST /v1/runs does. A developer key makes it.
  • Held to the parent. Its agent is held to the parent’s tenant. may_change must be within the parent’s (the parent’s when not given; 400 scope for more). Its time is no longer than the parent’s. Its agent may change its own world alone.
  • Its propose merges its world into the parent’s world and answers {status: "merged", into}, sending merge.landed with by: "parent". The parent’s own merge, later, is the one the merge policy judges, with the child’s rows in it.
  • The parent waits for its children. It can’t propose while a child is live (409 children_live). Discarding, rejecting or expiring the parent discards its children (run.discarded with parent).
  • One level. A child has no children of its own (400 depth).
  • Counted against GATEWAY_RUNS_PER_HOUR like any run (429 too_many_runs).
  • Listed: GET /v1/runs/:id of the parent has children: [{id, status, intent, created, expires, outcome}]; a child’s has parent.

A run’s metadata

PATCH /v1/runs/:id/meta, with a developer key or the run token, adds keys to the run’s metadata in the gateway (what POST /v1/runs took as meta). A key set to null is removed. It answers {id, meta}, and the metadata is at most 64 KB. The Python client’s LangGraph checkpointer records its checkpoints here.

PATCH /v1/runs/:id/meta
curl -s -X PATCH localhost:7400/v1/runs/$RUN/meta -H "Authorization: Bearer $RUN_TOKEN" -H 'Content-Type: application/json' \  -d '{"step": "drafted", "old_key": null}'

Statuses

StatusMeaningHow a run gets there
openForked. Its agent works in its world.POST /v1/runs.
heldIts merge broke a rule. It waits for a person.A propose the rules hold. The agent can no longer send SQL or MCP calls.
conflictRows it changed were changed in the database or main since it forked.A propose, or an approval, that finds such rows.
mergedWritten to the database.A propose within the rules, or an approval of a held run or one in conflict.
undoneMerged, then put back: every row it wrote is as it was before.POST /v1/runs/:id/undo with nothing left: on a merged run, on a partly_undone one, or on a run that ended after a part of it was approved. See Undo.
partly_undoneMerged, then put back but for the rows changed since, which stay as they are. It can be undone again for those rows once they hold what the run wrote.An undo with skip_changed that left rows.
rejectedA person said no. Its world is dropped.POST /v1/runs/:id/reject, or a rejection through an approval link. Any run that is open, held, in conflict or failed can be rejected.
failedThe merge failed for another reason; the message says.A propose the engine refuses for a reason other than a rule or a conflict, or a lost world. A failed run can be proposed again while its time lasts.
expiredIts time ran out before it merged. Its world is dropped.Open, in conflict or failed past expires; held past hold_expires.
discardedThrown away by the developer. Its world is dropped.DELETE /v1/runs/:id, or its database was disconnected with ?discard_runs=true.

A run is live while it is open, held, in conflict or failed: its world is still there and it may yet merge. A partial approval merges some tables or rows and leaves the run as it was, with the rest in its world.

Time limits

SettingDefaultMeaning
GATEWAY_RUN_TTL1hHow long a run, and its token, lasts. A run can ask for less with ttl_seconds, not more.
GATEWAY_HOLD_TTL3dHow long a held change waits for a person before it expires. It counts from the propose that held it.
  • Times take 60, 60s, 15m, 1h or 1d.
  • Every 30 seconds the gateway drops the worlds of runs past their time and marks them expired. run.expired is sent with what the run was (was).
  • A run that is open, in conflict or failed expires at expires. A held run expires at hold_expires, so a person has the whole hold time even when the run’s own hour is over.
  • A propose after expires answers 409 expired. SQL and MCP calls after it answer 403 expired.
  • The policy rule max_age is separate: by default a change made more than 15 minutes after the run began is held for a person, not refused.
  • When a run ends, its engine agent is dropped too.

Rate limits

SettingDefaultLimitsPast it
GATEWAY_RUN_STATEMENTS_PER_MINUTE120SQL statements and MCP tool calls per run per minute. A call to /sql, /mongo or an MCP tool counts as one.429
GATEWAY_RUN_PROPOSES_PER_MINUTE6Proposes per run per minute. Each one locks and compares rows in your database.429 too_many_proposes
GATEWAY_RUNS_PER_HOUR60New runs per tenant per hour.429 too_many_runs, and a run.refused event with tenant, runs_in_the_last_hour and limit
GATEWAY_RUN_MAX_ROWS1000Rows one SQL answer returns to an agent.The answer is cut and marked truncated
  • 0 means no limit.
  • A minute begins with the first call counted in it. Statements and proposes are counted apart, and each run apart.
  • Runs made at the same moment may each pass the hourly limit by one. The policy’s hourly row limits, counted per tenant by the engine, still hold.
  • A loop that proposes a run again and again without settling its conflict hits too_many_proposes.

Discard a run

DELETE /v1/runs/:id, with a developer key, throws a run away. Its world is dropped, it becomes discarded, and run.discarded is sent. Nothing reaches the database.

DELETE /v1/runs/:id
curl -s -X DELETE localhost:7400/v1/runs/$RUN -H "Authorization: Bearer $KEY"# {"status": "discarded"}

Only a live run is discarded. For a run that is already over, the call changes nothing and answers with the status it has. The console’s Runs page discards a run that is still open.

A lost world

A world’s unmerged work is not kept when the engine stops hard: a crash, or its machine lost. A call on such a run answers 409 world_lost. The run becomes failed, and run.failed is sent with code: "world_lost". Nothing of it reached the database. Start a new run.

This holds for one gateway and for several sharing a store. Work that was already merged is not affected: a merge whose outcome was lost around the database’s commit is settled when the engine starts, from the record of merges the database keeps, so nothing is written twice and nothing is lost. Runs, holds and approval links are in the gateway’s store and carry on.

When an answer is lost

  • Two decisions at once. Each decision on a run moves its status only from the status it was read with. A person’s approve, the AI reviewer, Chronos Cloud and the sweeper never overwrite one another: the one that comes second gets 409 run_changed, with the status now, and the outcome the first recorded stays.
  • An approval always names the version it merges: the caller’s version, else the one the run was held at (what merge.held, the reviewer and approval links showed), else, for a run in conflict, its world’s version then. A world written to since is refused (stale), never merged unseen.
  • A lost answer from the engine. When a propose or approve gets no answer (a timeout, a 5xx), or the sweeper finds a run’s world gone, the gateway asks the engine’s history whether the world merged. If it did, the run is recorded merged (outcome.reconciled: true, merge.landed with by: "reconciled") and the call answers {status: "merged", reconciled: true}, not expired. The gateway checks every live run whose world is gone the same way when it starts.
  • A merge the engine made is never recorded as rejected. A rejection or discard that finds the run’s world already gone asks the engine’s history first, and records the run merged when its merge landed (the rejection then gets 409 run_changed). An approval whose merge succeeded while a rejection or discard was recorded records it merged all the same (recorded_over in its outcome).
  • Undo after reconciling. The engine’s history gives no merge id today, so a reconciled run answers no_undo_record to an undo. Runs the reviewer or Chronos Cloud approved keep their merge ids, so they undo as any other.

List and read runs

CallTokenAnswers
GET /v1/runskey{"runs": [...]}. ?status= takes one status. ?limit= is 50 by default and 500 at most. ?source= or the header X-Chronos-Source narrows to one database; without it, every database’s runs.
GET /v1/runs/:idkey or runThe run, with its status and outcome. It reads from the run’s record, so it answers after its database is disconnected too.

A listed run has the same fields as the answer to POST /v1/runs, without token. What outcome holds depends on how the run ended:

Statusoutcome
merged, by the rules{"merged": n, "by": "rules"}
merged, by a person{"merged": n, "by": "person", "approved_by": {...}}, and "reads_checked": false when the person approved past a changed read
merged, found in the engine’s historyFrom 0.4.0: "reconciled": true, after a lost answer
held{"message", "reasons", "policy", "version"}; review too when the AI reviewer rejected or passed it
conflict{"message", "conflicts"}
rejected{"rejected_by", "reason"}
failed{"message", "code"}, or {"error", "code": "world_lost"}
undone, partly_undoneThe merge’s outcome, plus undone_by and undone (rows, skipped, merge, effects_not_undone). After a second undo, undone.rows counts every row put back over both.

Write as the end user

By default a run’s merge is written as the role the engine connects as, which sees every row. Beside Postgres, pass act_as when making the run, and its writes are made as your end user instead.

POST /v1/runs with act_as
{"tenant": {"org_id": 42}, "intent": "clean up leads", "end_user": "u-17", "act_as": {"role": "authenticated", "settings": {"request.jwt.claims": {"sub": "u-17", "role": "authenticated"}}}}
  • The engine locks and compares the rows as its own role, then runs the writes after SET LOCAL ROLE and set_config(name, value, true) for each setting. Postgres’s own grants and row-level security policies judge each write as the end user’s.
  • A row they hide or refuse fails the merge with code 42501, and nothing is written. The run becomes failed and run.failed is sent, not merge.rejected. It is the same when a person approves the run.
  • Once, in Postgres: GRANT authenticated TO the role the gateway connects as.
  • Settings must be custom ones (prefix.name). A value that is not text, such as the claims object, is sent as its JSON text.
  • A superuser or BYPASSRLS role is refused, since it would judge nothing.
  • run.created carries pg_role. The settings’ values are never shown or logged.
  • The run’s agent keeps its role for the whole run. A new end user is a new run.
  • Not beside MySQL, MariaDB or MongoDB.

Python and TypeScript

Client libraries wrap the API: Python (chronos-gateway on PyPI) and TypeScript (@chronosdb/gateway on npm, for Node 18 or later, Deno and Bun).

install
pip install chronos-gateway          # or: npm install @chronosdb/gateway
Python
from chronos_gateway import Gatewaygw = Gateway("http://localhost:7400", key=KEY)  # your developer keywith gw.run(tenant=42, intent="reassign Bo's open leads to Ada", end_user="user_7") as run:    # MCP clients (Claude Code, the Claude Agent SDK): run.mcp_server()    # tool-use loops (OpenAI, Anthropic): run.openai_tools() and run.call_tool(name, args)    my_agent(run)               # your agent    result = run.propose()if result.held:                 # a rule wants a person    link = gw.approval(run.id, end_user="user_7")    # in your page: <script src="{link.script}"></script> {link.html}

From gateway 0.4.0, clients 0.3.0 (on PyPI and npm):

  • Python: run.undo(preview=True) and run.undo(); run.child(intent, may_change="leads.stage") and run.children(); run.set_meta({...}); run.propose(evidence=[...]); gw.effects().
  • TypeScript: run.undo({ preview: true }) and run.undo(); run.child({ intent, mayChange }) and run.children(); run.propose({ evidence }); gw.effects().

Agent frameworks (Python)

chronos_gateway.adapters gives a run’s tools to agent frameworks. Each needs its framework installed; none is imported until asked.

adapters
from chronos_gateway.adapters import (langchain_tools, claude_agent_options, openai_agents_tools,    crewai_tools, pydantic_ai_toolset, pydantic_ai_deps, ChronosDeps, ChronosCheckpointSaver)tools = langchain_tools(run)                       # LangChain / LangGraph: tools for the runoptions = claude_agent_options(run, system="...")  # Claude Agent SDK: the run as an MCP servertools = openai_agents_tools(run)                   # OpenAI Agents SDKtools = crewai_tools(run)                          # CrewAI: query, changes, propose (0.3.0)agent = Agent(model, deps_type=ChronosDeps, toolsets=[pydantic_ai_toolset()])   # Pydantic AI (0.3.0)agent.run_sync(task, deps=pydantic_ai_deps(run))graph = builder.compile(checkpointer=ChronosCheckpointSaver(MemorySaver(), run))  # LangGraph (0.3.0)
  • CrewAI and Pydantic AI take propose=False to leave the propose tool out, so your code proposes.
  • ChronosCheckpointSaver wraps another LangGraph checkpointer and records each checkpoint on the run: in its metadata always, and as a checkpoint of its world (lg-<id>) where the engine lets the run’s agent make one. It logs, and never raises, when the gateway can’t be reached.
  • A run left without a proposal is discarded when the with block ends.
  • Webhook signatures are checked with verify_signature (Python) or verifySignature (TypeScript), on the raw body.

Events a run sends

run.created, merge.landed, merge.held, merge.reviewed, merge.conflict, merge.rejected, merge.undone, merge.undo_conflict, run.expired, run.discarded, run.failed and run.refused. With several databases, every event’s data says source. From 0.4.0: a child run’s run.created carries parent, and merge.landed says by: "parent" for a child merged into its parent’s world, by: "reconciled" for a merge found in the engine’s history. See Webhooks and Slack.

Next

Runs · Chronos