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.
- Your backend starts a run for one tenant:
POST /v1/runs. - The agent sends SQL or MCP tool calls with the run token. They run in the run’s world.
- Your backend, or the agent, proposes the run:
POST /v1/runs/:id/propose. - 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.
- 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.
{"error": {"message": "this run's time ran out before it merged", "code": "expired"}}Start a run
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"}'| Field | Takes | Meaning |
|---|---|---|
| tenant | required | Whose 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. |
| intent | text | What the run is for. Shown to approvers, in the console and in Slack messages. |
| end_user | text | Who the run acts for. Kept with the run, sent in merge.held, and used as the default end_user of an approval link. |
| source | a database’s name | Which 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_seconds | a number | How 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_change | the engine’s | Part of the scope the run declares with its world, passed to the engine as given. |
| max_rows | the engine’s | Part of the declared scope, passed to the engine as given. |
| max_deletes | the engine’s | Part of the declared scope, passed to the engine as given. |
| row_rules | text | Conditions 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_id | any JSON | Your own id for the task, recorded on the run’s world. |
| prompt_version | any JSON | Recorded on the run’s world. |
| model | any JSON | Recorded on the run’s world. |
| meta | any JSON | Anything 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.
| Answer | When |
|---|---|
| 201 | The run was made. Its world is forked and its token is in the answer. |
| 400 | tenant is missing or not in one of its forms, or ttl_seconds is out of range. |
400 tenant_column | No attached table has that column. The message lists the attached tables and their columns. |
400 act_as | act_as is not an object, has a key other than role and settings, has no role, or settings is not an object. |
404 no_source | No database is connected under that name. |
429 too_many_runs | The 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
{ "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, ...}| Field | Meaning |
|---|---|
| id | The run’s id. It starts with run_. |
| token | The run token. It starts with cgr_ and is shown only now: the gateway keeps its hash. This is what the agent gets. |
| sql_url | GATEWAY_PUBLIC_URL + /v1/runs/:id/sql. |
| mcp_url | GATEWAY_PUBLIC_URL + /v1/runs/:id/mcp. |
| status | open for a new run. See Statuses. |
| tenant | The tenant as {"column", "value"}, whatever form you sent. |
| created, updated, expires | Times in milliseconds since 1970. expires is when the run and its token end. |
| hold_expires | Null until the run is held; then when the hold ends. |
| outcome | Null until something happens; then the last answer about its merge: merged rows, the reasons it is held, conflicts, or the error. |
| merges | The ids of the merges that wrote the run to the database. Several for a run approved in parts. An undo names them. |
| source | The database it works beside: default, or the name another was connected under. |
| world, agent | The 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_idtoorders.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.
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.
| Answer | When |
|---|---|
| 400 | sql is missing or empty. |
400 forbidden_sql | A statement begins with merge, use, fork, discard, undo, restore or checkout, or is create, drop or alter of a branch or world. |
| 401 | The token is missing, is not a run token, or is another run’s. |
| 403, code the run’s status | The run is not open or in conflict: its agent cannot act any more. The code is the status, such as held or merged. |
403 expired | The run’s time ran out. |
409 world_lost | The run’s world is gone. See A lost world. |
| 429 | Past GATEWAY_RUN_STATEMENTS_PER_MINUTE. |
| a SQLSTATE | The 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.
| Tool | Notes |
|---|---|
| describe | Pointed at the run’s world. |
| find | Pointed at the run’s world. |
| sql | Held to the same rule as POST /v1/runs/:id/sql: no statement that merges or leaves the world. |
| put | Pointed at the run’s world. |
| diff | Pointed at the run’s world. |
| history | Pointed at the run’s world. |
| check_reads | Pointed at the run’s world. |
| merge_preview | A preview only. Its target can be sent with a propose to settle rows against main as the preview saw it. |
| rebase | Pointed at the run’s world. |
| checkpoint | Pointed at the run’s world. |
| rollback | Pointed at the run’s world. |
| merge_policies | Reads the policies. Not tied to a world. |
| check_merge_policy | Not tied to a world. |
| merge_checks | Reads the merge checks. Not tied to a world. |
Refusals come back as JSON-RPC errors with HTTP 200.
| JSON-RPC code | When |
|---|---|
| -32001 | The run cannot act: it is not open or in conflict, or its time ran out. |
| -32002 | Past GATEWAY_RUN_STATEMENTS_PER_MINUTE. Each tool call counts as one statement. |
| -32601 | The tool is not available to a run. |
| -32602 | The 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.
curl -s localhost:7400/v1/runs/$RUN/changes -H "Authorization: Bearer $KEY"| Field | Meaning |
|---|---|
| status | The run’s status. |
| version | The world’s version now. Send it with an approval to approve exactly what you looked at. |
| total | How many rows the run changes. |
| summary | Counts in words: ["3 leads changed", "1 lead removed"]. |
| tables | Counts per table, as the engine gives them. |
| changes | Each change as {text, kind, table, key, before, after}. kind is insert, update or delete. text reads like “Remove lead “Hooli””. |
| more | True when there are more changes than this page shows. |
| reasons | Why 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 emptychangesandsummary. 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.
curl -s localhost:7400/v1/runs/$RUN/propose -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' -d '{}'| Answer | Run becomes | Meaning |
|---|---|---|
200 {"status": "merged", "merged": n} | merged | Within 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": "..."} | held | A rule was broken. Nothing is written. The run waits for a person for GATEWAY_HOLD_TTL. merge.held is sent. See Approvals. |
409 conflict | conflict | A 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 expired | unchanged | The run’s time ran out before it merged. |
409 held | unchanged | The run is already held: approve or reject it. |
| 409, code the run’s status | unchanged | The run is over: merged, rejected, expired, discarded, undone or partly_undone. |
409 world_lost | failed | The run’s world is gone. See A lost world. |
429 too_many_proposes | unchanged | Past GATEWAY_RUN_PROPOSES_PER_MINUTE. No write is tried. |
| another refusal by the engine | failed | The 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 failure | unchanged | The 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:
| Field | Meaning |
|---|---|
| evidence | From 0.4.0. [{kind, uri, sha256, note}]: what the change rests on, kept with the run. See Evidence. |
| confirm_deletes | Passed 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_columns | true: a row where the two sides changed different columns combines. |
| resolve | "ours" (the run’s), "theirs" (main’s) or "fail". |
| rows | Single rows: {"orders/7": "ours" | "theirs" | "delete" | {the row to keep}}. |
| target | The 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": truewith"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"withoutby_columns: whole rows, overwriting the other side’s changes to other columns. Use it last. A policy withoverwrite = false, the default, sends it to a person."target": rows settle against main as that preview saw it.
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.
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 400evidence. - Kept with the run as
evidence: {items, in_engine}, and shown byGET /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’srequire_evidencecan ask for kinds.in_enginesays 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.
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_idandmeta, asPOST /v1/runsdoes. A developer key makes it. - Held to the parent. Its agent is held to the parent’s tenant.
may_changemust be within the parent’s (the parent’s when not given; 400scopefor 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}, sendingmerge.landedwithby: "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.discardedwithparent). - One level. A child has no children of its own (400
depth). - Counted against
GATEWAY_RUNS_PER_HOURlike any run (429too_many_runs). - Listed:
GET /v1/runs/:idof the parent haschildren: [{id, status, intent, created, expires, outcome}]; a child’s hasparent.
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.
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
| Status | Meaning | How a run gets there |
|---|---|---|
| open | Forked. Its agent works in its world. | POST /v1/runs. |
| held | Its merge broke a rule. It waits for a person. | A propose the rules hold. The agent can no longer send SQL or MCP calls. |
| conflict | Rows it changed were changed in the database or main since it forked. | A propose, or an approval, that finds such rows. |
| merged | Written to the database. | A propose within the rules, or an approval of a held run or one in conflict. |
| undone | Merged, 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_undone | Merged, 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. |
| rejected | A 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. |
| failed | The 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. |
| expired | Its time ran out before it merged. Its world is dropped. | Open, in conflict or failed past expires; held past hold_expires. |
| discarded | Thrown 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
| Setting | Default | Meaning |
|---|---|---|
| GATEWAY_RUN_TTL | 1h | How long a run, and its token, lasts. A run can ask for less with ttl_seconds, not more. |
| GATEWAY_HOLD_TTL | 3d | How long a held change waits for a person before it expires. It counts from the propose that held it. |
- Times take
60,60s,15m,1hor1d. - Every 30 seconds the gateway drops the worlds of runs past their time and marks them
expired.run.expiredis sent with what the run was (was). - A run that is open, in conflict or failed expires at
expires. A held run expires athold_expires, so a person has the whole hold time even when the run’s own hour is over. - A propose after
expiresanswers 409expired. SQL and MCP calls after it answer 403expired. - The policy rule
max_ageis 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
| Setting | Default | Limits | Past it |
|---|---|---|---|
| GATEWAY_RUN_STATEMENTS_PER_MINUTE | 120 | SQL 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_MINUTE | 6 | Proposes per run per minute. Each one locks and compares rows in your database. | 429 too_many_proposes |
| GATEWAY_RUNS_PER_HOUR | 60 | New 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_ROWS | 1000 | Rows one SQL answer returns to an agent. | The answer is cut and marked truncated |
0means 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.
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 thestatusnow, 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 (whatmerge.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.landedwithby: "reconciled") and the call answers{status: "merged", reconciled: true}, notexpired. 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
mergedwhen its merge landed (the rejection then gets 409run_changed). An approval whose merge succeeded while a rejection or discard was recorded records itmergedall the same (recorded_overin its outcome). - Undo after reconciling. The engine’s history gives no merge id today, so a reconciled run answers
no_undo_recordto an undo. Runs the reviewer or Chronos Cloud approved keep their merge ids, so they undo as any other.
List and read runs
| Call | Token | Answers |
|---|---|---|
| GET /v1/runs | key | {"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/:id | key or run | The 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:
| Status | outcome |
|---|---|
| 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 history | From 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_undone | The 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.
{"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 ROLEandset_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 becomesfailedandrun.failedis sent, notmerge.rejected. It is the same when a person approves the run. - Once, in Postgres:
GRANT authenticated TOthe 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
BYPASSRLSrole is refused, since it would judge nothing. run.createdcarriespg_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).
pip install chronos-gateway # or: npm install @chronosdb/gatewayfrom 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)andrun.undo();run.child(intent, may_change="leads.stage")andrun.children();run.set_meta({...});run.propose(evidence=[...]);gw.effects(). - TypeScript:
run.undo({ preview: true })andrun.undo();run.child({ intent, mayChange })andrun.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.
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=Falseto leave the propose tool out, so your code proposes. ChronosCheckpointSaverwraps 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
withblock ends. - Webhook signatures are checked with
verify_signature(Python) orverifySignature(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.