Chronos/DBWaitlist

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 gatewayWith Chronos Gateway
The agent holds a database passwordThe agent holds a run token that opens one task, for one customer, for one hour
A prompt injection reads every tenant’s dataIt only ever sees its tenant’s rows, whatever SQL it sends
DELETE FROM leads runs on productionDeletes happen in a private copy; by default every delete waits for a person
A stale read overwrites someone’s editEach 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 logsYou 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

TermMeaning
Enginechronos, 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.
MainThe engine’s copy of the attached tables, kept fresh by a refresh on a timer or by following the database’s changes.
TenantThe customer a row belongs to, named by a column such as org_id.
RunOne agent task for one tenant. It has its own token and ends after a set time (1 hour by default).
WorldA run’s private copy of the data, holding only its tenant’s rows. The agent reads and writes here, never in the database.
ProposeAsk for a run’s changes to be written to the database.
Merge policyThe rules a proposed change must keep to be written without a person. By default: no deletes, at most 500 rows.
HeldA proposed change that broke a rule. It waits for a person to approve or reject it.
ConflictA row the run changed was changed in the database meanwhile. Nothing is written until it is settled.
UndoPutting back the rows a merged run wrote, each checked against the database first, for 30 days after the merge.

One run, start to merge

  1. Your backend starts a run for one tenant

    POST /v1/runs with a developer key and the tenant ({"tenant": {"org_id": 42}}, or just 42 when the tenant column was set at connect). The answer has the run’s id, its token (starts with cgr_, shown only then), sql_url, mcp_url and expires.

  2. 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.

  3. Propose

    Your backend, or the agent, proposes the run (POST /v1/runs/:id/propose). GET /v1/runs/:id/changes shows the change first, in plain words and as rows.

  4. 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.

  5. 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.

  6. 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, code conflict. With the default rule check_reads = true, a change is also held when a row the run read has changed.

  7. Webhooks tell your backend

    merge.landed, merge.held, merge.conflict, merge.rejected and the rest go to your backend, signed, or to a Slack channel in words.

  8. Undo later

    A merged run can be put back for 30 days: POST /v1/runs/:id/undo with {"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": true to undo the rest. Emails and webhooks already sent are listed, not unsent.

the whole path with curl
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 proposeMeaning
200 {"status": "merged"}Within the rules: written to the database.
202 {"status": "held", "reasons": [...]}A rule was broken. Nothing is written yet.
409, code conflictA 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 expiredThe run’s time ran out first.
429 too_many_proposesPast GATEWAY_RUN_PROPOSES_PER_MINUTE (6 by default). Each propose locks and compares rows in your database.

The same, as a picture

who talks to what
 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 ──> dropped

What 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 = off and 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_preview and 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/check reads 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

WhenWhat happens in the database
POST /v1/connect/checkThe gateway logs in with the URL you sent and reads the catalog. No writes. The URL isn’t kept.
POST /v1/connectThe 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=onThe 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 MCPNothing. 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 undoOne more transaction of the same kind: the rows go back, each locked and compared first.
Held, rejected, expired or discardedNothing.

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, with GATEWAY_STORE_URL, for several gateways).
  • chronos: the engine. The gateway runs it on 127.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.

DatabaseVersions testedURL
Postgres12 to 18, Supabase (through its pooler), Neon (pooled or direct). 11 or older is refused, saying so.postgres://...
MySQL8.0, 8.4mysql://user:password@host:3306/database
MariaDB10.5, 11mariadb://user:password@host:3306/database
MongoDB5.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>.

TokenWho holds itWhat it opensHow long
cgk_ developer keyyour backendeverything except a run’s own SQL and MCP, and the widget’s callsuntil revoked (chronos-gateway keys revoke <id>, or Keys in the console)
cgr_ run tokenone agentthat one run: its SQL, MCP, changes, status and proposeuntil the run ends or its time runs out (GATEWAY_RUN_TTL, 1 hour by default)
cga_ approval tokenone personone held change, at the version it was made for, onceGATEWAY_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_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 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/runs refuses 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

GATEWAY_POLICY_RULES, by default
max_rows = 500, max_deletes = 0, rows_per_hour = 5000, max_age = '15 minutes', check_reads = true, require_scope = true

In 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.

PageWhat you do there
Get startedWhat’s left to set up, in order, with a first run to copy.
OverviewEngine health, what is attached, runs held and merged, webhook backlog.
ReviewHeld 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.
RunsEvery run, by status, with its outcome; discard one still open; undo a merged one (the preview first).
PolicyThe 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 & labelsNames for tables and columns in approvals, and columns hidden from them.
WebhooksAdd one (its signing secret is shown once) or remove it.
KeysMake developer keys (each shown once) and revoke them.
ConnectCheck a database, copy the statements for the gateway’s role, attach tables; disconnect a database connected under a name.
ActivityWhat happened, newest first.

Versions and status

WhatNow
Current releaseGateway 0.4.4, on Chronos DB (the engine) 0.6.2.
Imageghcr.io/abhishekxdg/chronos-gateway, for linux/amd64 and linux/arm64.
Releasesgithub.com/2090-labs/chronos-gateway-releases: the installer, static Linux binaries (x86-64 and arm64), the Compose file and the Helm chart.
Client librariesPython (pip install chronos-gateway) and TypeScript (npm install @chronosdb/gateway; Node 18+, Deno, Bun).
StatusEarly. 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/changes read (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.undone goes 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.yaml pulls latest.

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 version the 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 diff never 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: 0 and null ask for documents without the field.
  • A console sign-in made with GATEWAY_API_KEY ends 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’s strict_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/children hands 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 an Idempotency-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 merged if it merged; a second decision at once gets 409 run_changed.
  • Evidence with a propose, and PATCH /v1/runs/:id/meta for 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, greatest and least no longer take minutes. Each level doubled the time: 22 deep took 3 seconds. 60 deep takes 19 ms now.
  • Faster reads: scans, GROUP BY and 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_undone run can be undone again. Once the rows that were left hold what the run wrote, they go back and the run becomes undone. 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 ended rejected, expired or discarded can be undone for what that part wrote.
  • PUT /v1/policy answers ended: 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_many and delete_many say 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 $regex and compare dates ({"$date": ...}).
  • Following MongoDB: GATEWAY_FOLLOW works 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_rows beside MySQL and MariaDB). A role made from earlier statements answers 409 undo_not_ready on undo, with the statements to run once.

Where to go next

Chronos Gateway · Chronos