Gateway
Chronos Gateway
Let AI agents change the database you already run, only through checked, approved merges. Self-hosted, beside Postgres, MySQL, MariaDB or MongoDB.
Self-hostedChronos Gateway runs on your own servers today. Releases and install script. The engine under it: Chronos DB, self-hosted
What it is
Chronos Gateway lets AI agents change data in a database you already run, without giving them access to that database. Each agent task gets its own private copy of one customer’s rows. The agent reads, writes and deletes there. Nothing reaches your database until the change passes your rules and the rows it touches still match what is live. A change your rules do not allow waits for a person to approve it.
You run it on your own machines: an installer for Linux, a Docker image, a Compose file and a Helm chart. There is no account to make. The gateway sends nothing outside your network unless you set up webhooks or link it to Chronos Cloud, and both are optional.
| Without a gateway | With Chronos Gateway |
|---|---|
| The agent holds a database password | The agent holds a run token that opens one task, for one customer, for one hour |
| A prompt injection reads every tenant’s data | It only ever sees its tenant’s rows, whatever SQL it sends |
DELETE FROM leads runs on production | Deletes happen in a private copy; by default every delete waits for a person |
| A stale read overwrites someone’s edit | Each row is locked and compared with the database at write time; a changed row stops the merge |
| You find out what it did from the logs | You see “Remove lead ‘Hooli’” and approve it, or turn it down |
What it is not
- Not a proxy in front of your database. Your app keeps reading and writing the database exactly as it does today. The gateway sits beside it, never in its path. While the gateway is down, agents can’t start runs or merge; your database and your app aren’t affected.
- Not a hosted service. Everything runs on your servers. The link to Chronos Cloud is off unless you set
GATEWAY_CLOUD. - Not a new home for your data. The database stays where it is. The gateway’s engine holds a copy of the tables you choose, and writes back only through a merge.
- Not a way to make your database highly available. Several gateways can share one store and take turns leading, which keeps the gateway’s API up. The database agents work on is yours to keep up.
- Not a judge of direct writes. The rules judge merges. Your app’s own writes to the database are not checked by the gateway.
The words used
| Term | Meaning |
|---|---|
| Engine | chronos, the Chronos DB engine. The gateway starts it and keeps it running. It holds a copy of the tables you choose, and it alone decides what may be written back to the database. |
| Main | The engine’s copy of the attached tables, kept fresh by a refresh on a timer or by following the database’s changes. |
| Tenant | The customer a row belongs to, named by a column such as org_id. |
| Run | One agent task for one tenant. It has its own token and ends after a set time (1 hour by default). |
| World | A run’s private copy of the data, holding only its tenant’s rows. The agent reads and writes here, never in the database. |
| Propose | Ask for a run’s changes to be written to the database. |
| Merge policy | The rules a proposed change must keep to be written without a person. By default: no deletes, at most 500 rows. |
| Held | A proposed change that broke a rule. It waits for a person to approve or reject it. |
| Conflict | A row the run changed was changed in the database meanwhile. Nothing is written until it is settled. |
| Undo | Putting back the rows a merged run wrote, each checked against the database first, for 30 days after the merge. |
One run, start to merge
Your backend starts a run for one tenant
POST /v1/runswith a developer key and the tenant ({"tenant": {"org_id": 42}}, or just42when the tenant column was set at connect). The answer has the run’sid, itstoken(starts withcgr_, shown only then),sql_url,mcp_urlandexpires.The agent works in its own world
The agent sends SQL (
POST /v1/runs/:id/sql) or MCP tool calls (mcp_url) with the run token. They run in the run’s world. The agent sees and changes only its tenant’s rows. Beside MongoDB a run also has MongoDB’s own tools (find,count,insert,update_one,update_many,delete_one,delete_many). Agents write the same SQL whatever the database.Propose
Your backend, or the agent, proposes the run (
POST /v1/runs/:id/propose).GET /v1/runs/:id/changesshows the change first, in plain words and as rows.The rules decide: merge or hold
The engine checks the change against the merge policy. Within the rules, it merges:
200 {"status": "merged"}. A rule broken, it is held:202 {"status": "held", "reasons": [...]}, and nothing is written yet.A person approves a held change
A person approves it (written, with the same checks) or rejects it (dropped). The person can be on your team, in the console’s Review page or through the API, or your own end user, in an approval widget on your site. A held change waits 3 days by default (
GATEWAY_HOLD_TTL), then expires. An AI reviewer can be set to decide held changes before a person does.The write: one transaction, every row locked and compared
A merge is one transaction in your database. Each row the merge writes is locked and compared with the database first. If any of them changed since the agent read it, nothing is written: the answer is
409, codeconflict. With the default rulecheck_reads = true, a change is also held when a row the run read has changed.Webhooks tell your backend
merge.landed,merge.held,merge.conflict,merge.rejectedand the rest go to your backend, signed, or to a Slack channel in words.Undo later
A merged run can be put back for 30 days:
POST /v1/runs/:id/undowith{"preview": true}says what would go back, in words, and which rows changed since; without it, it is done. The undo goes through the database as any merge does: each row locked and compared, one transaction. A row someone changed since stays theirs unless you pass"skip_changed": trueto undo the rest. Emails and webhooks already sent are listed, not unsent.
export KEY=cgk_... # your developer key# 1. start a run for tenant 42curl -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"}'export RUN=run_... # "id" from the answerexport RUN_TOKEN=cgr_... # "token" from the answer: this is what the agent gets# 2. the agent works, in its worldcurl -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"}'# 3. see the changes, then proposecurl -s localhost:7400/v1/runs/$RUN/changes -H "Authorization: Bearer $KEY"curl -s localhost:7400/v1/runs/$RUN/propose -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' -d '{}'# 202 {"status": "held", "reasons": [...]}: the default rules allow no deletes# 4. a person approvescurl -s localhost:7400/v1/runs/$RUN/approve -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \ -d '{"by": "ada@example.com"}'# {"status": "merged"}: now it is in the database, every row checked| Answer to propose | Meaning |
|---|---|
| 200 {"status": "merged"} | Within the rules: written to the database. |
| 202 {"status": "held", "reasons": [...]} | A rule was broken. Nothing is written yet. |
| 409, code conflict | A row the run changed was changed in the database meanwhile. Nothing is written. Propose again with the conflict settled (by_columns, resolve, rows), or have a person approve it settled. |
| 409, code expired | The run’s time ran out first. |
| 429 too_many_proposes | Past GATEWAY_RUN_PROPOSES_PER_MINUTE (6 by default). Each propose locks and compares rows in your database. |
The same, as a picture
your app ─────────────── reads and writes, as today ──────────────────> database ^ your backend ── start a run for tenant 42 ──> gateway ──> engine │ written only on a merge, the agent ───── SQL / MCP, run token ───────> gateway ──> its world │ each row checked (tenant 42 only) │ your backend ── propose ──> rules kept ─────────────────────────> merged ──┘ a rule broken ──> held ──> approved ──> merged └─> rejected ──> droppedWhat never happens
- An agent never gets the database’s credentials. It holds a run token. The token opens one run: its SQL, MCP, changes, status and propose. It stops working when the run ends or its time runs out.
- Nothing reaches the database except a checked merge. An agent’s SQL or MCP call writes nothing to the database. Neither does a held, rejected, expired or discarded run.
- A merge never overwrites a row that changed. Every row it writes is locked and compared first. One difference and nothing is written.
- A run never sees another tenant’s rows. The engine filters every read and write to the run’s tenant, whatever SQL the agent sends: joins, subqueries,
set row_security = offand past versions included. - MCP agents get no tool that merges, forks or drops worlds. They get the tools that work inside the run’s world (
describe,find,sql,diff,merge_previewand others). - The gateway’s own database role is never an owner or a superuser. It may read and write the attached tables and keep its own record tables. The connection check gives the exact statements.
- The connection check keeps nothing.
POST /v1/connect/checkreads the catalog with the URL you send, writes nothing, and forgets the URL. - No answer is never an approval. With an AI reviewer set, a model that fails, answers out of form or is not sure enough sends the change to a person.
What reaches the database, and when
| When | What happens in the database |
|---|---|
POST /v1/connect/check | The gateway logs in with the URL you sent and reads the catalog. No writes. The URL isn’t kept. |
POST /v1/connect | The engine logs in as the gateway’s role and reads the attached tables to copy them. |
Every GATEWAY_REFRESH_EVERY (5 minutes by default) | The engine reads the attached tables again. |
Every second, with GATEWAY_FOLLOW=on | The engine reads the changes since the last second from its replication slot (MongoDB: a change stream on each attached collection), then the rows they name. |
| An agent’s SQL or MCP | Nothing. It runs in the run’s world. |
| A merge (rules kept, or a person approved) | One transaction: each row the merge writes is locked and compared with the database, then written, and the merge is recorded in the gateway’s own table (chronos.merges in Postgres, chronos_merges in MySQL, MariaDB and MongoDB). If any row changed meanwhile, nothing is written. |
| An undo | One more transaction of the same kind: the rows go back, each locked and compared first. |
| Held, rejected, expired or discarded | Nothing. |
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 check_reads = true holds a change if a row it read has changed. A person’s approval is checked the same way. When what the run read changed, the console and the approval page say so and let the person approve anyway (skip_read_check), which merges without that check and is recorded as reads_checked: false. The rows the run changed are still checked.
The two programs
chronos-gateway: the HTTP API on port 7400, tokens, runs, approvals, webhooks and the console. It keeps its own state in SQLite in its data folder (or in a Postgres of its own, withGATEWAY_STORE_URL, for several gateways).chronos: the engine. The gateway runs it on127.0.0.1(loopback), starts it again if it stops, and stops it cleanly on shutdown. With several databases connected, each has its own engine.
Anything that decides what may reach the database is the engine’s: worlds, merge policies, the tenant scope and the checked write. The gateway stores, shows and relays.
Databases and versions
The URL you connect with says which database it is. The same check, attach, runs, rules, approvals and undo follow.
| Database | Versions tested | URL |
|---|---|---|
| Postgres | 12 to 18, Supabase (through its pooler), Neon (pooled or direct). 11 or older is refused, saying so. | postgres://... |
| MySQL | 8.0, 8.4 | mysql://user:password@host:3306/database |
| MariaDB | 10.5, 11 | mariadb://user:password@host:3306/database |
| MongoDB | 5.0, 7.0 (a replica set; one member is enough) | mongodb://user:password@host:27017/database |
One gateway can work beside several databases at once, each with its own engine, tenant column, rules, labels and masks. See Connect a database.
The three kinds of token
Each token is 32 random bytes with a prefix. The gateway stores only their SHA-256 hashes. Every API call sends Authorization: Bearer <token>.
| Token | Who holds it | What it opens | How long |
|---|---|---|---|
| cgk_ developer key | your backend | everything except a run’s own SQL and MCP, and the widget’s calls | until revoked (chronos-gateway keys revoke <id>, or Keys in the console) |
| cgr_ run token | one agent | that one run: its SQL, MCP, changes, status and propose | until the run ends or its time runs out (GATEWAY_RUN_TTL, 1 hour by default) |
| cga_ approval token | one person | one held change, at the version it was made for, once | GATEWAY_APPROVAL_TTL (1 day by default) |
A Slack message of a merge also carries an undo link (a cgu_ token): it undoes that one merged change, once, as far as its rows are unchanged, for whoever holds it, until GATEWAY_APPROVAL_TTL. GATEWAY_SLACK_UNDO=off sends no such link. See Undo and Webhooks and Slack.
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.
- 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 table with neither the tenant column nor such a foreign key is shared: 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 don’t attach them. POST /v1/runsrefuses a tenant column that no attached table has (400 tenant_column). The message lists the attached tables and their columns.- A run is held only by its own tenant’s rows: another tenant’s rows changing do not hold a run that read the same tables.
The default rules
max_rows = 500, max_deletes = 0, rows_per_hour = 5000, max_age = '15 minutes', check_reads = true, require_scope = trueIn plain words: a change is written without a person only if it deletes no rows, changes at most 500 rows, keeps its tenant under 5,000 changed rows an hour (counted across all its runs), was made within the last 15 minutes, every row it read still matches the database, and it declares its tenant (every gateway run does). Anything else is held. Change the rules in the console or with PUT /v1/policy: see Rules, labels and masks.
The console
The console is the gateway’s own admin page, at /console on its address. On a new gateway it asks for the setup code from the log, makes your first key and signs you in. Everything it does goes through the same API as your backend, and the engine still decides every merge.
| Page | What you do there |
|---|---|
| Get started | What’s left to set up, in order, with a first run to copy. |
| Overview | Engine health, what is attached, runs held and merged, webhook backlog. |
| Review | Held runs and conflicts, newest first. Each change in words and rows (before and after). Approve all of it, only some tables, or reject it with a reason; send it to someone else as an approval link. Keys: j/k move, a approves, r rejects. |
| Runs | Every run, by status, with its outcome; discard one still open; undo a merged one (the preview first). |
| Policy | The merge policy as a form, with what it means in plain words. Saving applies it to the engine at once. Loosening a rule asks you first. |
| Data & labels | Names for tables and columns in approvals, and columns hidden from them. |
| Webhooks | Add one (its signing secret is shown once) or remove it. |
| Keys | Make developer keys (each shown once) and revoke them. |
| Connect | Check a database, copy the statements for the gateway’s role, attach tables; disconnect a database connected under a name. |
| Activity | What happened, newest first. |
Versions and status
| What | Now |
|---|---|
| Current release | Gateway 0.4.4, on Chronos DB (the engine) 0.6.2. |
| Image | ghcr.io/abhishekxdg/chronos-gateway, for linux/amd64 and linux/arm64. |
| Releases | github.com/2090-labs/chronos-gateway-releases: the installer, static Linux binaries (x86-64 and arm64), the Compose file and the Helm chart. |
| Client libraries | Python (pip install chronos-gateway) and TypeScript (npm install @chronosdb/gateway; Node 18+, Deno, Bun). |
| Status | Early. Try it on a staging copy of your database first. |
New in 0.4.4
- Masked values stay out of a run’s plain-words diff: an approval link, the console and
GET /v1/runs/:id/changesread(masked), as the undo preview did. - A deleted webhook gets nothing more: its deliveries still due are dropped. A webhook’s URL is never logged, and its secret is kept sealed.
- One slow receiver no longer holds the others back: a webhook or effects channel that timed out is tried once a pass, so Slack approvals and other channels go out meanwhile.
- A Chronos Cloud undo of a run is recorded in the run: it says
undone,merge.undonegoes to the webhooks, and its merges are undone together. - MongoDB tools write all of a call’s documents or none, and each write counts against
GATEWAY_RUN_STATEMENTS_PER_MINUTE: a call past it is refused whole (429). - A new setup code works after a lockout, and
deploy/compose.yamlpullslatest.
New in 0.4.3
- A merge from Chronos Cloud is an approval like any. Of a run’s world: only of a run held or in conflict, at the
versionthe person saw, into main (else 409 or 400). Before, the cloud could merge a run its agent was still writing. - Masked columns stay out of the cloud. A cloud
diffnever returns SQL, and a refusal loses its detail and, for an integrity error, its message. - A late approval that meets a conflict is kept until the hold ends, not expired by the next sweep.
- The gateway listens while a first attach copies the database, so an orchestrator’s liveness probe no longer kills it.
- MongoDB
$exists: 0andnullask for documents without the field. - A console sign-in made with
GATEWAY_API_KEYends when that key changes. Sign in again after upgrading. - Engine unchanged (0.6.2). The data format is unchanged (8).
New in 0.4.2
- A strict change waits on the database as it was. A person’s approval of a held run that sends payment, payout, transfer or refund effects is refused (409
strict_target, nothing merged) once other changes reached the database since the hold, as the engine’s own strict proposals are. A strict change is approved whole, never in part. See Approvals. - Engine unchanged (0.6.2). The data format is unchanged (8).
New in 0.4.1
- Strict changes are for a person, in their window. A held run that sends payment, payout, transfer or refund effects (or ones its merge policy names in
strict_channels) is never approved by the AI reviewer; a person approves it within 15 minutes (the policy’sstrict_window), and<chronos-approve>shows the time left. See Approvals. - Engine 0.6.2, which this release bundles: strict proposals, merges refused when an attached Postgres or MySQL may lose a commit it acknowledged, MongoDB merges committed to a majority and journaled, and fixes from an audit of 0.6.0. The data format is unchanged (8).
New in 0.4.0
- Child runs.
POST /v1/runs/:id/childrenhands part of a run to a sub-agent: its own token, its world forked from the parent’s, held to no more than the parent may change. See Runs. - Effects delivered. What a merge queues (
NOTIFY ON MERGE) is delivered to your receiver, signed, with anIdempotency-Key, and retried. See Webhooks. - No lost or double decisions. A propose or approve that times out is checked against the engine’s history and recorded
mergedif it merged; a second decision at once gets 409run_changed. - Evidence with a propose, and
PATCH /v1/runs/:id/metafor a run’s metadata. - Engine 0.6.0, which this release bundles: tenant agents kept to their tenant everywhere, and every merge into main in a hash-chained ledger. Its first checkpoint or merge writes data format 8, which 0.5 can’t open: back up the data folder before you upgrade.
New in 0.3.4
- Deeply nested SQL runs again. The engine refused a statement nested 80 parentheses or function calls deep as too complex. It runs 100 and more now (engine 0.5.5, which this release bundles).
- Nested
coalesce,greatestandleastno longer take minutes. Each level doubled the time: 22 deep took 3 seconds. 60 deep takes 19 ms now. - Faster reads: scans,
GROUP BYand joins on one whole-number column are 20 to 25 percent faster (engine 0.5.4). - The gateway’s own code is unchanged from 0.3.3.
New in 0.3.3
- Undo of a big run is about 20 times faster. Each row an undo puts back is now found by its key; before, its check read the whole table. Undoing a run that wrote 10,000 rows beside Postgres took 57 seconds and takes 2.7 (engine 0.5.3, which this release bundles).
- The gateway’s own code is unchanged from 0.3.2.
New in 0.3.2
- Undo after a partial undo: a
partly_undonerun can be undone again. Once the rows that were left hold what the run wrote, they go back and the run becomesundone. The console’s button reads “Undo the rest”. See Undo. - Undo after a part was approved: a held run with a part approved (
only_tables,only_keys) that then endedrejected,expiredordiscardedcan be undone for what that part wrote. PUT /v1/policyanswersended: the rules that were set before and the new set left out.- One link per Slack message: a retry of a Slack delivery carries the same approval or undo link, not a new one.
- Slack messages name MariaDB as MariaDB, not MySQL.
- MongoDB tools:
update_manyanddelete_manysay in their descriptions that a filter matching more than 1,000 documents is refused, not cut to the first 1,000.
New in 0.3.1
- Disconnect a database connected under a name:
DELETE /v1/sources/:name, and Disconnect on the console’s Connect page. - Undo from Slack: a Slack message of a merge carries a link, Review and undo.
- MongoDB filters take
$regexand compare dates ({"$date": ...}). - Following MongoDB:
GATEWAY_FOLLOWworks beside MongoDB, through a change stream on each attached collection. - Undo with the gateway’s own role: the statements the connection check gives now make and grant the table that keeps what merges write (
chronos.merge_rows;chronos_merge_rowsbeside MySQL and MariaDB). A role made from earlier statements answers409 undo_not_readyon undo, with the statements to run once.