Gateway
Rules, labels and masks
Which changes merge on their own and which wait for a person; how changes read in plain words; which columns agents never see.
Self-hostedChronos Gateway runs on your own servers today. Releases and install script. The engine under it: Chronos DB, self-hosted
How rules work
The rules are a merge policy: what a proposed change must keep to be written to your database without a person. The engine checks them inside each merge, on the rows it is about to write. A change within the rules merges. A change that breaks one is held and waits for a person to approve or reject it. Nothing is written while it waits.
- The gateway keeps the rules’ text and makes the engine’s policy match it. It does not judge merges itself.
- Every run’s agent is bound to the one policy, named by
GATEWAY_POLICY(gatewayby default). - A person’s approval merges a held change past the rules that held it. The row checks still run: each row the merge writes is locked and compared with the database first.
- Rules judge the change. Labels and masks are separate: labels set how a change reads to a person, masks set what an agent reads.
This page describes gateway 0.4.4 on Chronos DB 0.6.2.
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.
Every other rule is unset by default. An unset limit is no limit, an unset list is empty, and an unset flag is false. So by default a schema change, or a merge that overwrites newer edits with a whole side, is held too.
Every rule
These are the rules PUT /v1/policy takes, in the order the console shows them. A limit is a whole number, 0 or more, or null for no limit. A time is text such as '15 minutes'. A list is names in one string, such as 'orders,items'. A flag is true or false.
Size of one change
| Rule | Kind | Default | Meaning |
|---|---|---|---|
| max_rows | limit | 500 | Rows changed. More than this, and the change waits for a person. |
| max_deletes | limit | 0 | Rows deleted. 0 means every delete waits for a person. |
| confirm_deletes_over | limit | unset | Deleting more than this needs the approver to type the count. A propose passes the count as confirm_deletes. |
Per tenant, per hour
| Rule | Kind | Default | Meaning |
|---|---|---|---|
| rows_per_hour | limit | 5000 | Rows changed an hour, across all of a tenant’s runs. A job split into many small runs still counts. |
| deletes_per_hour | limit | unset | Rows deleted an hour, per tenant. |
Fresh data
| Rule | Kind | Default | Meaning |
|---|---|---|---|
| max_age | time | '15 minutes' | The oldest a run may be. Its work rests on what it read then. |
| check_reads | flag | true | Hold the change if rows the agent read were changed in the database since. Only the run’s own tenant’s rows count. |
| rerun_reads | flag | false | Re-run its reads first, and hold only if a read now gives something else. |
What it may touch
| Rule | Kind | Default | Meaning |
|---|---|---|---|
| tables | list | unset | Only these tables. Unset: any attached table. |
| review_tables | list | unset | Always review these tables: any change to them waits. 'payments' |
| review_columns | list | unset | Always review these columns, even for one row. 'users.email,accounts.owner' |
| require_scope | flag | true | Runs must say what they may change. The gateway gives each run its tenant. |
| overwrite | flag | false | May overwrite newer edits. False: a run never replaces what changed in the database since it began. |
| schema | flag | false | May change the schema: tables, views, functions, types. |
| critical | flag | false | May change critical columns: columns a reader marked critical. |
Side effects
| Rule | Kind | Default | Meaning |
|---|---|---|---|
| max_effects | limit | unset | Effects one change may queue: emails, webhooks, payments sent once it lands. |
| effects_per_hour | limit | unset | Effects an hour. |
| review_channels | list | unset | Always review these effect channels. 'payments,refunds' |
Values in each row
| Rule | Kind | Default | Meaning |
|---|---|---|---|
| row_rules | text | unset | Conditions each changed row must keep, or the change waits. 'payments: new.amount >= -50; prices: new.price <= old.price * 1.2' |
| max_nulled | limit | unset | The most values one change may set to empty. |
All runs together, per hour
| Rule | Kind | Default | Meaning |
|---|---|---|---|
| all_rows_per_hour | limit | unset | Rows changed an hour by every tenant’s runs together: a breaker if the agent goes wrong everywhere at once. |
| all_deletes_per_hour | limit | unset | Rows deleted an hour, all runs together. |
| all_effects_per_hour | limit | unset | Effects an hour, all runs together. |
Text from outside
| Rule | Kind | Default | Meaning |
|---|---|---|---|
| untrusted_columns | list | unset | Columns outsiders write: tickets, emails, web pages, where a prompt injection hides. 'tickets.body'. '*' makes every text column untrusted. Rows an agent writes after reading such text are tainted, and reading them counts as reading it. |
| untrusted_guards | list | unset | Tables that outside text may not steer. A run that read those columns needs a person to change these. Unset: any table. |
| trusted_columns | list | unset | Columns only you write, left out of '*' and 'table.*' above: a status your app sets. 'tickets.status' |
What a change leaves behind
| Rule | Kind | Default | Meaning |
|---|---|---|---|
| watch_totals | text | unset | Queries that give one number, run before and after each change. 'select sum(amount) from payments; select count(*) from orders' |
| max_shift | limit | unset (10) | The most a watched total may move, in percent. A change that moves one further waits for a person. Unset: 10. |
| max_unusual | limit | unset | A change this many times bigger than the runs’ usual size waits. |
Landing slowly
| Rule | Kind | Default | Meaning |
|---|---|---|---|
| canary | limit | unset | A bigger change lands only this many rows first. The rest lands when it is merged again after the wait. |
| canary_wait | time | unset (10 minutes) | How long the canary sits in the database before the rest may land. Unset: 10 minutes. |
| effects_delay | time | unset | Emails, webhooks and payments a change queues wait this long after it lands. An undo meanwhile takes them back unsent. |
Review
| Rule | Kind | Default | Meaning |
|---|---|---|---|
| reviewer | an agent’s name | unset | An agent that looks first: it approves, turns down, or passes the change to a person. The AI reviewer sets itself here. |
| review_every | flag | false | Every merge goes to the reviewer first, even one within the rules. |
| spot_check | limit | unset | A person sees one change in this many at random, even within the rules. |
| person_only | list | unset | The holds the reviewer cannot approve past. Unset: deletes, schema changes, outside text, the all-runs limits, spot checks and watched totals. 'none': it may approve past any. |
GET and PUT /v1/policy
Both take a developer key. Rules set with PUT are kept in the gateway’s store, applied to the engine at once, and win over GATEWAY_POLICY_RULES from then on.
curl -s localhost:7400/v1/policy -H "Authorization: Bearer $KEY"| Field | Meaning |
|---|---|
| name | The policy’s name (GATEWAY_POLICY). |
| rules | The rules as an object. Null when the gateway cannot read the text. |
| text | The rules as the engine reads them: max_rows = 500, max_deletes = 0, .... |
| unreadable | Null, or why the text could not be read. This happens only with rules set by hand in GATEWAY_POLICY_RULES. |
| source | set (by PUT, or the console) or config (GATEWAY_POLICY_RULES). |
| engine | The policy as the engine holds it, or null while there is no engine or no such policy yet. |
| known | Every rule’s name. |
curl -s -X PUT localhost:7400/v1/policy -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \ -d '{"rules": {"max_rows": 100, "max_age": "30 minutes", "check_reads": true}}'rulesis the whole set. A rule left out ends: a limit becomes no limit and a flag becomes false. In the example above,max_deletes = 0ends, so deletes would no longer wait for a person. Send every rule you want kept.- From 0.3.2 the answer says which rules ended, in
ended: the names of the rules that were set before and this set left out, such as["max_deletes", "require_scope", "rows_per_hour"](in alphabetical order). It is[]when none ended. - A value of null, or an empty string, unsets a rule.
- The engine must take the rules first. A rule it refuses changes nothing.
- The answer is the same as
GET, after the engine took the rules, plusended. - The next merge is checked against the new rules. A run that is already held stays held.
| 400 when | The message says |
|---|---|
rules is not an object | the rules are an object |
| a rule’s name is unknown | merge policies have no rule of that name, with the list of names |
| a limit is not a whole number, 0 or more | it is a whole number, 0 or more, or null for no limit |
| a flag is not true or false | it is true or false |
| a time, list, name or text is not a string | what it takes, with an example |
| a string has a control character | which rule has it |
check_reads is turned on beside MySQL or MariaDB with an engine before 0.4.11 | upgrade the engine, then POST /v1/setup |
Rules from configuration
| Setting | Default | Meaning |
|---|---|---|
| GATEWAY_POLICY | gateway | Name of the merge policy runs keep to. |
| GATEWAY_POLICY_RULES | the six default rules | The rules, as the engine’s text. It replaces the whole default list, until rules are set with PUT /v1/policy or in the console. |
Rules from the setting are applied when you connect a database. To change them later, set the variable, restart the gateway, then apply it:
curl -s -X POST localhost:7400/v1/setup -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' -d '{}'# {"ok": true, "policy": "gateway", "rules": "..."}GET /v1/status also shows the policy’s name and the rules in force.
Rules per database
A gateway beside several databases keeps rules, labels and masks for each. A request names its database with the header X-Chronos-Source or ?source=. Without one it means the first database, default. A name that is not connected answers 404 no_source.
curl -s -X PUT localhost:7400/v1/policy -H "Authorization: Bearer $KEY" -H 'X-Chronos-Source: shop' \ -H 'Content-Type: application/json' -d '{"rules": {"max_rows": 50, "max_deletes": 0, "check_reads": true}}'- This holds for
/v1/policy,/v1/labels,/v1/masks,/v1/setup,/v1/statusand/v1/refresh. - A run belongs to one database, and its merge is judged by that database’s rules.
GATEWAY_POLICY_RULESand the other start-up settings are read once for the gateway. The AI reviewer is the first database’s only.- MySQL and MariaDB: a run’s reads are checked against the database when the engine is 0.4.11 or later. The gateway asks the engine each time it applies the policy. With an older engine the default rules leave
check_readsoff, andPUT /v1/policyrefuses to turn it on, since that engine would refuse every merge. After upgrading it,POST /v1/setupturns the check on. The rows a merge writes are locked and compared either way.
Rules a run adds
A run can add its own row_rules when it is made (POST /v1/runs). They hold on top of the policy’s and can only make it stricter. A row that breaks one is outside the run’s scope, so its merge is held.
{"tenant": 42, "intent": "refund order 1181", "row_rules": "payments: new.amount <= 100"}Held reasons
When a propose breaks a rule, the answer is 202 with the reasons, as the engine gives them: one for each rule the change broke.
{"status": "held", "reasons": ["deletes 3 rows, more than 2"], "message": "..."}The same reasons are shown wherever the held run is:
GET /v1/runs/:idinoutcome, with thepolicythat held it and the world’sversionit was held at.GET /v1/runs/:id/changesasreasons.- The
merge.heldevent:{run, reasons, end_user, world, version, policy, asked, owner, changes}. - The console’s Review page, under “Why it’s waiting”, and the approval widget’s
GET /v1/approve. - A Slack message: “Waiting for approval”, the intent, how many changes, and “Held:” with the reasons.
A held change waits GATEWAY_HOLD_TTL (3 days by default), then expires. See Approvals.
Conflict policies
A conflict is not a rule broken. It means a row the run changed was also changed in the database, or in main, since the run’s world was forked. Nothing is written. A propose, or a person’s approval, says how to settle it, and the engine judges the settled merge under the rules like any merge.
| Send | Settles |
|---|---|
| "by_columns": true | A row where the two sides changed different columns combines. The safest; try it first. |
| "by_columns": true, "resolve": "ours" | As above, and for a column both changed, the run’s value. |
| "by_columns": true, "resolve": "theirs" | As above, and for a column both changed, main’s value. |
| "rows": {"orders/7": ...} | Single rows: "ours", "theirs", "delete", or the row to keep as an object. |
| "resolve": "ours" or "theirs" | Whole rows, overwriting the other side’s changes to other columns. Use it last. |
| "target": n | Rows settle against main as a preview of the merge saw it (the run’s MCP merge_preview). |
The rule overwrite decides the last resort. With overwrite = false, the default, a merge that takes a whole side over newer edits is sent to a person. The console’s Review page offers the same five choices for a run in conflict.
Labels
Labels decide how a change reads in plain words, to a person approving it. They name each table’s rows, say which column titles a row, name the columns, and hide the columns a person should not see.
curl -s -X PUT localhost:7400/v1/labels -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \ -d '{"tables": {"leads": {"name": "lead", "title": "name", "columns": {"owner": "owner", "org_id": null}}}}'| Key | Meaning | Without it |
|---|---|---|
| name | What one row is called: lead. | The table’s name with _ as spaces, made singular: leads to lead, companies to company. |
| plural | What several are called. | name + s, or the table’s name. |
| title | The column whose value names a row: “lead “Acme””. | The row’s key: lead #7. |
| columns | Each column’s label, or null to hide it. | The column’s name with _ as spaces. |
- With labels, a change reads “Change the owner of lead “Acme” from Bo to Ada”, “Remove lead “Hooli””, and a summary reads “3 leads changed, 1 lead removed”.
GET /v1/labelsanswers the labels;{"tables": {}}when none are set.PUTreplaces them all and answers what it kept.- 400 when the body has no
tablesobject, a table’s labels are not an object, a table has a key other thanname,plural,titleandcolumns, or a column maps to something other than text or null. - Beside MongoDB, labels name fields by path:
"columns": {"address.city": "city"}. - With Chronos Cloud linked and sharing
diffs, the columns your labels hide are left out of rows sent there. - Labels change words only. They do not change what an agent reads or what a merge may do.
Masks
A masked column is one agents never read as it is. The mask is the engine’s, set on its copy. Your database is never changed.
curl -s -X PUT localhost:7400/v1/masks -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \ -d '{"tables": {"customers": {"email": "hash", "phone": "partial", "notes": null}}}'| Mask | An agent reads |
|---|---|
| hash | A keyed hash of each value. The same value gives the same hash, so the agent can still join and count on it. |
| partial | The last four characters. |
| format | A value of the same shape. |
| null | NULL. Send it as the text "null". |
| JSON null | Unmasks the column. |
- An agent reads a masked column masked wherever it reads it.
- A column not named in a
PUTkeeps the mask it has. GET /v1/masksreads the masks back from the engine:{"tables": {"customers": {"email": "hash"}}}. Tables with none are left out. The gateway keeps no list of its own.- Runs started after a mask is set read it. A run’s world keeps the table as it was when the run started.
- 400 when a table is not attached, the table has no such column, or the mask is not one of
hash,null,partial,format. Nothing is set then. - People see
(masked)in place of a masked value in an undo’s preview. With Chronos Cloud linked and sharingdiffs, masked columns read"masked"there. - The AI reviewer reads masked columns masked too.
- The connection check lists, per table, columns whose names suggest values agents should not read (
sensitive: email, phone, ssn, password, token, card, address and the like). It is a hint for what to mask. - Needs engine 0.4.4 or later.
The gateway’s own documents do not say how a merge treats a write to a masked column. Try a proposal on a table with a masked column on a staging copy before you rely on it.
The AI reviewer
Optional. Set GATEWAY_REVIEWER_URL and GATEWAY_REVIEWER_MODEL, and a model reads each held change before a person. It approves it (merged as it was held), rejects it, or passes it on. A person then sees only what the model rejected or passed, with the model’s reason beside the rules’ reasons. Unset, people decide every held change.
| Setting | Default | Meaning |
|---|---|---|
| GATEWAY_REVIEWER_URL | unset | An OpenAI-compatible API’s base, such as https://api.openai.com/v1 or http://localhost:11434/v1 (Ollama). Plain http only to this machine, or without a key. |
| GATEWAY_REVIEWER_MODEL | unset, required | The model to ask. Hosted or open-weight. |
| GATEWAY_REVIEWER_KEY | unset | Its API key, sent as a bearer token. |
| GATEWAY_REVIEWER_MODEL_2 | unset | A second model on the same API. Both must approve, at the confidence below, for a change to merge. |
| GATEWAY_REVIEWER_MIN_CONFIDENCE | 0.8 | From 0 to 1. An approval less sure than this goes to a person. |
| GATEWAY_REVIEWER_INSTRUCTIONS | unset | Your rules for its decisions, in words. GATEWAY_REVIEWER_INSTRUCTIONS_FILE reads them from a file. |
| GATEWAY_REVIEWER_MAX_ROWS | 100 | The most changed rows it is shown. |
| GATEWAY_REVIEWER_COLUMNS | unset | Columns whose text the model reads as it is: leads.name,leads.stage, leads.*, or *. Other text it sees only as a placeholder. |
| GATEWAY_REVIEWER_AGENT | gateway_reviewer | The engine agent it decides as. |
What the model cannot do
- Its own engine agent. It decides as an engine agent that may only read and cannot unmask. The gateway makes it and names it as the policy’s
reviewer. - Holds only a person may approve. By default the engine refuses its approval of a change held for deletes, schema changes, outside text, the all-runs limits, a spot check or a watched total. Those go to a person with the reason, and the model is not asked. The rule
person_onlysets which. So does a strict change (from 0.4.1: it sends payment, payout, transfer or refund effects), whateverperson_onlysays. - Only what it was shown. A change written to after it was held is refused too.
- No answer is never an approval. If the model fails three times, answers out of form, or is less sure than the minimum confidence, the change goes to a person.
What the model is sent
- The run’s intent, why the change was held (with no values in it), and counts per table.
- Up to
GATEWAY_REVIEWER_MAX_ROWSchanged rows, as its agent reads them. Numbers, true and false, empty values and one-word values (a status, a date, an email, an id) are shown as they are. - Text from columns in
GATEWAY_REVIEWER_COLUMNS, cut to 300 characters. Any other text is a placeholder such as{"text": "#3", "chars": 214}; the same text gets the same placeholder within one review. - Columns in
untrusted_columnsare always placeholders, even when allowed, and masked columns stay masked.
The model is told that everything in the change is data, and to reject a change that tries to steer it. That lowers the risk of a prompt injection; it does not remove it. What bounds a wrong approval is the engine’s rules above. A hosted model receives what it is shown: to keep that in your network, use a model you run there.
Every decision is in the engine’s audit and in the merge.reviewed event: {run, world, version, verdict, reason, confidence, by: {reviewer, model}}, where verdict is approve, reject or pass. An approval also sends merge.landed with by: "reviewer". A run it rejects or passes stays held, with outcome.review saying so.
Rules made to pair with it: review_every, row_rules, all_rows_per_hour, untrusted_columns with trusted_columns, watch_totals with max_shift, canary with canary_wait, effects_delay, max_unusual and spot_check.
In the console
Policy
- The merge policy as a form, grouped as on this page, with one sentence at the top that says what the rules mean in plain words. The sentence changes as you type.
- It shows the policy’s name, whether the rules were set in the console or come from
GATEWAY_POLICY_RULES, and whether they are in force in the engine. - Saving applies the rules to the engine at once. The next merge is checked against them.
- Loosening a rule asks you first: raising or removing
max_rows,max_deletes,rows_per_hour,deletes_per_hourormax_effects, or turning offcheck_readsorrequire_scope. - Rules the console cannot read (set by hand in
GATEWAY_POLICY_RULES) are shown as text, with why. Saving replaces them. - With several databases, the picker chooses whose rules you are looking at.
Data and labels
- Masked columns: every column of every attached table, with what agents read: the real value, a keyed hash, the last 4 characters, a value of the same shape, or NULL.
- Labels: the labels as JSON, with a button that fills in a starting set from the attached tables. It hides
id, columns ending in_idand tenant columns, and takesname,title,email,subjectorlabelas a row’s title.