Chronos/DBWaitlist

Chronos DB, self-hosted

Operate and secure

What is durable and when, backups, upgrades, limits, roles and tokens, TLS, and what Chronos protects and leaves to you.

Self-hostedChronos DB is one binary you run yourself. Releases and install script. To put agents on a database you already run, with approvals: Chronos Gateway

Where it stands

This page is for Chronos DB 0.6.2 (2026-11-19). It states what the engine guarantees today and what it does not, so you can judge it for your own use.

  • Beta. Try it on a staging copy, not production. It is not yet used in production anywhere outside.
  • One maintainer. The storage engine has not had an outside review. Treat it accordingly.
  • Platforms: macOS 13 or later and Linux, on x86-64 (x86-64-v2) and arm64. No Windows.
  • Not Postgres. It speaks the Postgres 16 wire protocol and much of its SQL, and mainstream drivers are tested, but it is not Postgres.
  • Benchmarks are engineering measurements on one machine, not published results. Measure your own workload.

What is durable, and when

OperationSafe when it returns?
write to mainyes: fsynced; concurrent callers share one fsync
merge into mainyes
merge into another worldno, until that world reaches main
write to another worldno, until merged. A crash can lose it (a later main commit does not save it), and the merge will say so. From 0.6.0: yes for a world made WITH (durable) (Durable worlds)
fork, discardno, until the next fsync; a lost fork is simply gone
batchall rows or none
CREATE, ALTER, DROPall or nothing: a crash comes back as before or after each, never halfway

What fsynced means follows alter system set synchronous_commit, which is kept across restarts:

ValueA commit reaches
full (the default)stable storage, through the drive’s cache (F_FULLFSYNC on macOS, fdatasync elsewhere). Survives power loss
normala plain fsync. On macOS the drive may still hold the write in its cache. On Linux it is the same as full
offthe OS only. Survives the process crashing, not the machine

Why writes to worlds are different

Writes to worlds other than main are not forced to disk one by one, for speed. Each world keeps its writes and logs them together, up to 64 KB at a time, when something needs them there: a fork from it, a merge of it or into it, a discard, a write by another agent, a checkpoint, a read of history or the past, or a clean shutdown. So a crash can lose a world’s writes since then, even when later writes to main were synced. Each world comes back as it was after some of its own writes, in order.

That trade is safe only because it is never silent. Every write to a world returns the world’s version, the number of writes since its fork.

  • Merge with a version: if a crash rolled the world back, the merge fails with N of your writes were lost; redo them or discard. Over HTTP it is 409.
  • Merge without a version: after a crash, every world that was open is flagged, and a plain merge is refused (55000). Check its diff, then merge with its current version (merge <world> confirm in the shell, MERGE WORLD w CONFIRM in SQL, confirm: true over HTTP or MCP), or discard it.
  • Clean shutdowns flag nothing. The flag survives restarts and checkpoints until the world is merged or discarded.
  • The clients track versions for you.

What is not proven

  • Real power loss is not tested. The crash, disk-full and kill tests reopen the folder with every acknowledged write and pass VERIFY DATABASE. They keep the OS page cache, so they do not prove the fsyncs themselves are correctly placed. Fault-injected storage (LazyFS, dm-log-writes) is not used yet.
  • A main write is visible before it is durable. It becomes visible to other sessions when it enters the shared snapshot, which is before its fsync returns. A power loss in that window can erase a write another session already read.

Crashes

  • Opening loads the manifest, replays the log after it, and reads pages only when needed. The time to reopen is the time to read the log since the last checkpoint.
  • Torn tails: a torn write at the end of the log is dropped. Corruption anywhere else refuses to open rather than guessing.
  • Checkpoints and cleanup can be interrupted at any step. The crash tests kill them at every step between their file writes, renames and deletions (232 points). Each time the folder reopens with the same rows and passes VERIFY DATABASE.
  • A full disk: a page write that fails part way is cut off its page file; the checkpoint that hit it fails, and the next one, once there is space, writes the rest. A log write that fails stops the process, as Postgres does, and the next open cuts the torn tail. Either way, after freeing space the folder opens with every acknowledged write.
  • A transaction a dead process left open is rolled back at the next open.
  • Merges replay as what they did (from 0.6.0). A world merge, partial merge or rebase is logged as one record holding every row it set, the merged world’s fate and a BLAKE3 digest. Opening the database writes those rows again and judges nothing, so recovery no longer depends on merge rules that may have changed since. Transaction commits keep their old record, and logs written by 0.5.5 replay as before.
  • A panic can leave internal locks poisoned. Most counters and flags recover, but a panic while the database holds one of its internal read-write locks makes later writes fail until a restart.
  • Run it under a supervisor that restarts it. Nothing restarts the process on its own.

The folder, checkpoints and cleanup

a database folder
mydb/  LOCK            held while a process has the database open (one process at a time)  wal-<n>         write-ahead log segments: every change, checksummed, in order  manifest        the last checkpoint: each branch's tree roots, version and crash flag  pages/          pack-<n> files of immutable, content-addressed, LZ4-compressed pages (+ .idx)  remote, owner   only when attached to object storage (owner also with an anchor)  reads           which clients' SQL read which columns, and when; not published to a remote
  • A checkpoint folds every world’s recent changes into its page tree, writes a new manifest and drops the old log. It runs in the background once the log passes 64 MB, or on checkpoint in the shell. Only changed pages are written. Writers wait for one once the log passes 256 MB. The background checkpoint briefly pauses writers while it takes a consistent snapshot.
  • Cleanup deletes pages nothing uses any more: overwritten data, merged or discarded worlds. It runs after a checkpoint once page files double in size; in the background once 1,000 worlds, or worlds that changed 100,000 rows, were discarded since the last cleanup; or on gc in the shell. Live pages are copied out of mostly-dead files and made durable before the old files are deleted.
  • History costs disk. Pages and log that time travel still needs stay for the retention window: 1 hour for a new database, 30 days for a folder made by a release before 0.2.0. Dropping worlds frees their space only once history no longer holds them. Lower history_retention to free it sooner.
  • SHOW DISK gives bytes of pages in use (live), kept only for history (history), needed by nothing (reclaimable), and the log (log).
  • Files are created with the process’s default permissions. Nothing sets them tighter. Keep the folder 0700.

Backups and restore

back up
-- while it runs, as the database's own user or an agent with adminBACKUP DATABASE TO '/backups/db-1';# or the HTTP op, with the admin tokencurl -s localhost:7070/v1/backup -H "Authorization: Bearer $CHRONOS_ADMIN_TOKEN" \  -H 'Content-Type: application/json' -d '{"to":"/backups/db-1"}'# {"files":…,"bytes":…}# or from the command line, when nothing else has the folder openchronos mydb backup /backups/db-1
restore and verify
chronos restore /backups/db-1 newdb# restored /backups/db-1 into newdb, and verified itCHRONOS_KEY=<key> chronos restore /backups/db-1 newdb    # an encrypted backup needs the key
  • A backup is a database folder, consistent as of the moment it started: every write before then, none after. Worlds come with their unmerged work.
  • History comes too. A restored database can time travel as far back as the original could.
  • Each backup is a full copy. There are no incremental backups.
  • It never looks finished when it is not. It goes into a new or empty folder and is renamed into place at the end.
  • Writers keep going while it copies. Checkpoints wait for it, and writers wait once the log passes 256 MB, so very large copies can stall writes.
  • Restoring copies a backup into a new folder, opens it and verifies it. The backup is only read. Any closed database folder works as a backup too.
  • Verifying: VERIFY DATABASE, verify in the shell, or the verify HTTP op reads every page any world, reader or kept history needs, checks each against its hash, and checks every log record against its checksum. An error names what is missing or corrupt. It is not bounded in memory yet: it peaked at about 1.7 GB on a database of 646,000 pages.
  • Constraint violations, from 0.6.0: VERIFY DATABASE has five columns, pages, bytes, log_records, world and problem, with one row per NOT NULL, UNIQUE, FOREIGN KEY or CHECK violation in any world. With none, one row of counts, as before. The verify command and HTTP op list them too (violations: [{world, problem}]).
  • The merge ledger, from 0.6.0: VERIFY LEDGER recomputes the hash chain of every merge into main and returns seq, ok and detail per entry. See The merge ledger.
  • Who may: BACKUP and VERIFY need admin for an agent, and MCP’s safe mode does not allow them. BACKUP writes wherever the server process can. The Studio refuses backups, since they name a path.
  • No point-in-time restore of a backup. RESTORE WORLD ... TO and time travel reach back only within the history window, inside the same folder.
  • With object storage, the bucket is the backup: it holds the database as of the last checkpoint, so versioned buckets give you point-in-time copies. BACKUP refuses a cloud-backed database.

Losing the machine

Chronos is one process that writes one database. There is no replica that follows it and nothing fails over on its own. What keeps a database available is how fast another process can open it.

SetupData lost on losing the machine
One machine, backups onlyas old as the last backup
Object storage, wal_shipping = offeverything since the last checkpoint
Object storage, wal_shipping = async (the default)at most about wal_shipping_delay (1 s)
Object storage, wal_shipping = syncnone that was acknowledged
  • Object storage needs a build with --features s3 and --remote s3://bucket/prefix. Checkpoints upload finished page files, their indexes, then the manifest. The log ships too, in chunks, as it is written.
  • Another machine opens the bucket from an empty folder with --takeover, which fences the old writer off. The first read of a page downloads its whole page file (up to 64 MB), so the local disk needs room for the files a workload touches.
  • sync mode adds a round trip to the bucket to each commit to main and each merge. While the bucket cannot be reached for 10 s, new writes and merges are refused with 58030; reads work.
  • One writer, always. Two processes never write the same database: on a folder the second gets an error, on a bucket the lease refuses it.
  • Not here: a hot standby that follows the log, automatic failover, read replicas, several writers.

Upgrades

The on-disk format is versioned and read across releases. A release has changed authentication semantics before, so read the CHANGELOG before you upgrade. The sources document no downgrade path.

upgrade the binary
chronos mydb backup /backups/mydb-before-upgrade   # a full copy first; over SQL if a server has the folder opencurl -fsSL https://github.com/2090-labs/Chronos-DB/releases/latest/download/install.sh | CHRONOS_VERIFY=1 shchronos --version                                  # then restart the server

The install script renames the new binary into place, so a running server keeps the old one until it is restarted. What to know when coming from an older release:

Coming fromWhat changes
before 0.2.0A folder made then keeps 30 days of history, not 1 hour. An agent made then has no SCRAM verifier: it must use its token once over the HTTP API before it can log in on the Postgres port of a server with a token.
0.3The server token was the database’s own user. Since 0.4 it is the guest’s: with it, CREATE TABLE, writes to main, MERGE, CREATE AGENT and ALTER SYSTEM fail with 42501, and over HTTP with 403. Set CHRONOS_ADMIN_TOKEN for the people and the application that own the data, or pass --unsafe to run exactly as before. Under --safe, a role that logs in with its own password is now that role, not the guest.
before 0.5.0Five security fixes for what a role or agent with little could do; upgrading is recommended for anyone with more than one role or agent. A folder attached to MySQL before 0.5.0 cannot insert into AUTO_INCREMENT tables: attach again. A folder attached to MariaDB before 0.5.0 says kind: mysql, and works the same.
0.5.00.5.1 fixes chronos attach beside MySQL or MariaDB for a user with no right to create tables, adds serve --follow beside MongoDB, and removes a wrong warning at start. Nothing changes for a folder attached to Postgres.
0.5.10.5.2 lets a merge undone in part be undone again: undo by merge id marks a row that is as it was before its merge as already, and never refuses for it. Undoing a merge twice does nothing, where it was an error. serve and chronos refresh name the database a folder is attached to in their messages, not always Postgres. HTTP 500 and 502 answer Internal Server Error and Bad Gateway. Nothing changes in how merges are written.
0.5.20.5.3 makes undo by merge id of a big merge about 20 times faster (each row is found by its key) and joins followed by GROUP BY 2 to 4 times faster. Answers are the same; the folder and the attached database are taken as they are.
0.5.30.5.4 makes scans with a filter on an integer column, GROUP BY over text and joins on one whole-number column 20 to 25 percent faster on one core. Answers are the same; the folder and the attached database are taken as they are.
0.5.40.5.5 runs statements nested 100 parentheses or function calls deep (release builds refused 80) and types a nested coalesce, greatest or least once a level, where each level doubled the time. Answers are the same; the folder and the attached database are taken as they are.
0.5.50.6.0 logs each merge as the rows it wrote, in a hash-chained ledger. Its first checkpoint or merge on a folder writes data format 8, which 0.5.5 refuses: back up first (see below). Agents made without rights now read only their own worlds and main.
0.6.00.6.1 fixes two things about merges cut short by a crash. Beside Postgres or MySQL, recovery after the source committed a merge now settles exactly that merge (it could put rows in main that never reached the source, after a partial merge or a write to the world after the crash): upgrade if you merge into an attached database. And MERGE WORLD ... IN CHUNKS OF n takes CONFIRM and AT VERSION, so a chunked merge goes on in chunks after a crash. The folder format is the same (8): replace the binary and restart.
0.6.10.6.2 adds strict proposals for payments (Merges), refuses merges into an attached Postgres or MySQL that may lose a commit it acknowledged (CHRONOS_ATTACH_UNSAFE_SOURCE=1 merges anyway), commits MongoDB merges to a majority, journaled, adds chronos refresh --check, and fixes what an audit of 0.6.0 found. The data format is unchanged (8): replace the binary and restart.
  • Agents keep working across the 0.3 to 0.4 change: each has its own token.
  • The server says what changed as it starts: the server token is the guest’s.
  • A new folder made by chronos serve has protect_main on. Folders made earlier, or by the shell, the library or chronos import, keep the setting they have.

Speed on reports, measured

Chronos stores rows, not columns. It is built for many agents working in worlds, not for analytics. Against Postgres it wins on reports when it has more cores and loses core for core; a column store is faster than both. These are the project’s own measurements of 0.5.4, on 2026-11-16.

The machine: an 8 GB Apple M2 laptop. Chronos ran in process on disk. Postgres 18 ran at its defaults in a Linux virtual machine with 2 of the laptop’s cores, so the 2-thread column is the like-for-like one. Nothing else was running on the laptop. Time for one query, in milliseconds; lower is better.

Heavy analytical joins

Two queries of the CH-benCHmark over one TPC-C warehouse: Q3 joins four tables, Q18 three, each with a GROUP BY.

QueryChronos, 1 threadChronos, 2 threadsChronos, 8 threadsPostgres 18, 2 cores
Q3134885964
Q18197137100226
  • Q18 is faster than Postgres at the same two cores: 137 ms against 226.
  • Q3 is 1.4 times slower at the same two cores, and 2.1 times slower on one core.
  • 0.5.3 made these 2 to 4.5 times faster. In 0.5.2, on one thread, Q3 took 274 ms and Q18 915 ms. A join followed by GROUP BY kept every joined row before grouping; now each is grouped as it is made. Both versions and Postgres give the same answers.

Small reports

Five reports over two tables of 200,000 rows.

ReportChronos, 1 threadChronos, 2 threadsChronos, 8 threadsPostgres 18, 2 cores
count(*) of a table5.53.01.64.3
count(*) with a filter10.15.42.44.8
GROUP BY with count and max18.410.15.016.3
join of both tables, then GROUP BY with sum75.140.519.529.8
count(*) of the join with a LIKE filter42.623.412.218.0
  • With every core, Chronos is 1.5 to 3.3 times faster than Postgres on two cores. That is more cores against fewer, not a like-for-like win.
  • At the same two cores it is mixed: the plain count and GROUP BY are 1.4 and 1.6 times faster; the filtered count and both joins are 1.1 to 1.4 times slower.
  • On one core all five are slower than Postgres on two, by 1.1 to 2.5 times.
  • 0.5.4 made the scans faster: on one core the filtered count went from 13.5 to 10.1 ms, GROUP BY from 24.0 to 18.4 and the join with GROUP BY from 95 to 75. The two heavy joins above barely moved.
  • What is left is mostly decoding stored rows: a quarter to a third of each query. That is the row format, and it is not changing.
  • All three builds were measured in one run on the idle laptop. Numbers shown here earlier for 0.5.3 were taken while other work ran on it: every time, Postgres’s too, was about 1.6 times higher.
  • A column store is faster. In October, DuckDB 1.5.5 ran these five reports 2.2 to 7 times faster than Chronos. It was not run again for 0.5.4.
  • These are times for one query, not queries a second. No throughput of reports under load has been measured.

Every number, the machines, and how to run them again are in BENCHMARKS.md, with the losses listed first.

How far back undo reaches

Two settings, for two kinds of undo. Neither has an upper limit.

WhatDefaultSet withUpper limit
A merge written to an attached database, undone by its id30 days after the mergeCHRONOS_UNDO_WINDOW_DAYS, a whole number of days, where chronos serve runsnone; it must be more than 0
Time travel, RESTORE, UNDO MERGE OF WORLD, UNDO AGENT and the audit trail, from the folder’s own history1 hour for a new databasealter system set history_retention = '7 days'none, unless you set one in CHRONOS_LIMITS (history_retention_ms)
  • The cost is storage. A longer undo window keeps more rows in the record table in the attached database. A longer history_retention keeps more old pages and log in the folder: a busy database’s disk grows with it.
  • Raising a window does not bring back what was already dropped. It covers what is still kept, and everything after.
  • Undo by id takes time with the rows. Through the gateway beside Postgres, on a laptop, undoing a merge of 10,000 rows of a 20,000-row table took 2.7 s, and its dry run 2.8 s (0.5.3). In 0.5.2 and before the same undo took 57 s: each row’s check read the whole table.

Limits and sizing

What a process holds in memory

  • Pages stay on disk and are read as queries need them, so a database can be many times the machine’s memory.
  • Page cache: decoded pages, up to CHRONOS_CACHE_MB (default 256). Pages are counted by the memory they take decoded, about 2.5 times their size on disk for small rows.
  • Page directory: about 90 bytes per page, and twice that while opening. This is the part that grows with the database: 330,000 pages (811 MB) take about 30 MB, so 100 GB of pages would take about 4 GB.
  • Grouping, sorting and joins hold up to CHRONOS_WORK_MEM (default 256MB), then spill to files in CHRONOS_SPILL_DIR.
  • One statement may hold up to CHRONOS_QUERY_MEM (default a quarter of the machine’s memory) before it fails with 53200. All statements together may hold twice that.
  • A query’s result is held whole before it is sent. There is no cap on the whole process.
  • An equality filter on a column with no B-tree index builds an in-memory search index that takes many times the table’s size: a 150,000-row table of 18.5 MB took 1.57 GB. Give the column a B-tree index, or lower CHRONOS_WORK_MEM.
  • Big statements and transactions spill to <database>/spill and stay within a bounded memory, with exceptions: INSERT ... ON CONFLICT, anything with RETURNING, tables with triggers and some others are still held in memory.

Fixed limits

LimitValue
Processes per folderone; share it through chronos serve
x86-64 CPUsx86-64-v2 (POPCNT, SSE4.2), about 2009 on. Build from source with RUSTFLAGS="-C target-cpu=x86-64" for anything older
A single row valuelimited by memory. Large blobs belong in object storage with a key in the row
World metadata64 KB
HTTP body, headers32 MB, 64 KB
Postgres message64 MB
Connections1000 per port (CHRONOS_MAX_CONNECTIONS)
Changed rows per merge into an attached main50,000 by default (CHRONOS_ATTACH_MAX_ROWS raises it, to 1,000,000)
Simulationsat most 1,048,576 worlds, and within max_worlds
Functions and triggersnest at most 40 deep (54001)
Nesting in one statement400 levels: one for each parenthesis, NOT, sign, cast and operator in a chain, ten for each subquery. Deeper is refused (54001), not a crash. From 0.5.5 a release build runs 100 nested parentheses or calls; 0.5.4 and older refused 80
Parameter numbers$1 to $65535
IsolationREAD COMMITTED and REPEATABLE READ. SERIALIZABLE and two-phase commit are refused

Limits you set inside the database

SettingDoesOver it
alter system set statement_timeout = '30s'every SQL session starts with it. A session may set its own to 0; only an agent’s max_query_ms cannot be raised57014
alter system set max_worlds = 10000live worlds besides mainfork refused, 53400 (HTTP 429)
alter system set world_idle_ttl = '7 days'worlds unused that long are discarded, unless pinned or forked from; logged as system
alter system set protect_main = onmain’s rows change only by merging a world, for everyone42501, naming a row
alter system set history_retention = '7 days'how far back time travel, undo and the audit trail reach

Limits the operator sets where the process starts

Two limits that nothing inside the database can raise, its own user and admins included.

EnvironmentDoesOver it
CHRONOS_MAX_DISK_BYTES=536870912the most the folder may hold: pages, log, history, spills. Reads, DELETE, DROP, TRUNCATE, merges, discarding worlds and cleanup still work, so a full database can free itselfa write, fork or spill is refused: 53100 (HTTP 507)
CHRONOS_LIMITS=/etc/chronos/limits.tomlceilings over the database’s own settings: max_worlds, history_retention_ms, world_idle_ttl_ms, statement_timeout_ms. A setting left at 0 (no limit) is the ceilingALTER SYSTEM SET past one: 42501 (HTTP 403), naming the limit
/etc/chronos/limits.toml
max_worlds = 100history_retention_ms = 86_400_000   # a dayworld_idle_ttl_ms = 604_800_000     # 7 daysstatement_timeout_ms = 30_000

A key the file does not know, or a value that is not a whole number, stops the database from opening. A change near the disk cap can still pass it a little; the filesystem’s own quota is the backstop.

Identities and tokens

There are three ways in (Postgres, HTTP, MCP) and one identity model. The short version: agents cannot write main, and a person approves merges.

WhoHow they are identifiedMay
The database’s own userthe shell; a loopback client when the server has no token at all; the admin token; the server token only with --unsafe; chronos mcp --allow-mergeeverything
An agentits own token; chronos mcp --agent NAMEread every world; change only worlds it forked, unless its can list allows more
The guestthe server token; no token on a server that has only an admin token; with --safe, every client that is not an agent, a role with its password, or the admin tokenread every world; fork; change only worlds guest forked, shared by every guest
A roleCREATE ROLE ... LOGIN PASSWORD, proving its own password on the Postgres port or in chronos studio --loginwhat its privileges allow
Processes of the same OS userthe folder and its Unix socketeverything: the files, and the socket chronos uses to share an open folder
  • The server and admin tokens are strings you choose, kept only in the process. Each is at least 24 characters, change-me is refused, and they must differ. Make each with openssl rand -hex 24. Changing one takes a restart.
  • Pass them in the environment (CHRONOS_TOKEN, CHRONOS_ADMIN_TOKEN), or from a secrets file your service manager reads. A flag shows in ps.
  • Without any token, loopback is trust. Every client on the machine is the database’s own user. Web pages are kept out: the HTTP API refuses any request with an Origin header, and a server without a token answers only loopback Host names.
  • Role passwords protect something only on a server with a token. Without one, a login under any other name is a superuser that may SET SESSION AUTHORIZATION to any role.
  • Reads are not scoped. Anyone who may read reads every world, main, its history and other agents’ worlds included. Keep out of the database what an agent must not see. Masked columns and an agent held to a tenant are the two things that narrow a read.
  • Failed logins slow down, per client address: after 10 wrong passwords or tokens the address waits 1 s, then 2 s, 4 s, up to 60 s. The count lives in memory only.
  • Safe mode and agents are guardrails for tool calls, not a sandbox. An agent that can run shell commands as the OS user that owns the folder can run chronos <folder> merge <world> itself.

Agents and their quotas

SQL, as the database's own user or an agent with admin
create agent bot with (can = 'read,fork,write_own', max_worlds = 10, world_ttl = '1 day');-- name | id | token      the token is shown once: keep italter agent bot set (writes_per_minute = 600, max_query_ms = 30000, max_concurrent = 4, max_memory_mb = 512);alter agent bot set (disabled = true);    -- its token stops working; false turns it back onshow agents;                              -- name, id, can, quotas, world_ttl, created, disabled, limitsdrop agent bot;                           -- its token stops working; its worlds stay, still its own
  • Agents are rows in the database, not OS or Postgres users. They survive restarts. No SQL statement or row command can read or write the table that holds them.
  • Tokens are chronos_ and 64 hex digits (32 bytes from /dev/urandom). Only the token’s blake3 hash is stored, with a SCRAM-SHA-256 verifier of it for Postgres logins.
  • Rotation: ALTER AGENT ... ROTATE TOKEN answers with the agent’s new token, and is a superuser’s to run since 0.5.0. To be rid of an agent, disable or drop it.
  • A new agent gets read, fork, write_own. The full list of capabilities is on Serve. admin is total, including making more admins.
  • An agent that merges into main (write_main and merge_own) should keep to a merge policy, and the one to start from is max_deletes = 0. See Merge policies.

All quotas are off (0) by default, for agents and for the guest.

SettingLimitsOver itHTTP
max_worldsits live worlds at oncerefused, 42501403
max_changesrows each of its worlds may change since its fork, across restarts. A transaction counts at COMMITrefused, 42501403
writes_per_minutestatements, batches and API writes, as a token bucket that holds a minute’s worthrefused, 53400429
world_ttlhow long its worlds livediscarded by the background worker (every 30 seconds), logged as system
max_query_mshow long one of its SQL statements runsstopped, 57014400, with code 57014
max_concurrentits statements and HTTP requests running at oncerefused, 53300429
max_memory_mbrows one of its statements holds; its sorts, groups and joins spill at a quarter of itstopped, 53200413
max_idle_mshow long a Postgres connection of its sits idle inside a transactionconnection dropped (FATAL 25P03), its transaction rolled back
max_threadsthreads one of its statements runs onslower, never refused
prioritynormal (the default) or low: a low-priority agent’s statements yield while the database’s own users’ statements runslower while others run, never refused
  • The rate limiter and max_concurrent are counted in memory: a restart resets them.
  • The guest has no quotas. Bound what it can do with the limits for the whole database.
  • A world isolates data, not CPU. An agent’s unfiltered scan in its own world competes with main’s traffic. max_threads, max_concurrent, max_query_ms and priority = low bound it.

Protecting main

  • Agents cannot write main unless they have write_main, and cannot merge unless they have merge_own or merge. The guest and MCP safe mode never can.
  • The approval step is a person merging. An agent forks, writes and tells you its world. You read the diff, then merge or drop it.
  • Approve the version you read: MERGE WORLD w AT VERSION n, or HTTP merge with version. An agent that keeps writing to its world while you review does not get its later writes merged with it.
  • protect_main makes main’s rows change only by merging a world, for every user, the database’s own user and admins included. Definitions, RESTORE and UNDO still go straight in. A folder chronos serve makes starts with it on.
  • Only the shell on the database’s machine turns it off (chronos <folder>, then ALTER SYSTEM SET protect_main = off). An agent, or a client of the server over Postgres or HTTP, is refused (42501), so a leaked token cannot turn it off first.
  • Merge policies and merge checks bound what an agent’s merge may do without a person. Merges a policy refuses wait in SHOW REVIEWS. See Merge policies and Merge checks.
undo, within the history window
undo agent bot since '-2 hours';              -- put back every row bot changed in the current world since thenundo agent bot since '-2 hours' skip changed; -- ...leaving rows someone changed after itundo merge of world agent_7;                  -- put back a merge someone ranrestore world main to '-10 minutes';          -- the whole world as it wascheckpoint world agent_7 as 'before';         -- name a moment; later: restore world agent_7 to checkpoint 'before'

These reach back as far as history does: 1 hour for a new database. They are ordinary writes: durable, in history, and themselves undoable. An agent needs restore to run them, and merge too for the undos. Agents’ own rows are never put back from the past, so rights removed stay removed.

Tenants

There are two different things called a tenant.

A tenant per database

Give each tenant its own folder and its own chronos serve process:

two tenants, two processes
CHRONOS_TOKEN=$ACME_TOKEN CHRONOS_KEY_FILE=/secrets/acme  chronos serve /data/acme  --listen 10.0.0.5:7071 --pg 10.0.0.5:5441 --tls-cert acme.pem --tls-key acme.keyCHRONOS_TOKEN=$GLOBEX_TOKEN CHRONOS_KEY_FILE=/secrets/globex chronos serve /data/globex --listen 10.0.0.5:7072 --pg 10.0.0.5:5442 --tls-cert globex.pem --tls-key globex.key
  • Nothing is shared: files, memory, caches, crashes, the server token, agents and their tokens, and, with a key each, encryption.
  • An agent’s token only works in its own tenant: agents are rows in that tenant’s database.
  • One process cannot serve many folders. A reverse proxy maps names to ports.

An agent held to one tenant’s rows

An agent made WITH (tenant = 'org_id = 42') reads and changes only rows of that tenant: of tables with the column, and of tables tied to one through their foreign keys (up to three hops). A table with neither is shared by every tenant: the agent reads it whole and may not write it.

TLS

  • --tls-cert and --tls-key turn on TLS for both ports. HTTP becomes HTTPS only, and Postgres refuses connections that do not use TLS.
  • An address that is not loopback refuses to start without them, unless --insecure-no-tls says something else encrypts the connection: a VPN, a TLS proxy in front, a container whose port is published only on the host’s 127.0.0.1. It then warns at start.
  • Files: PEM, the certificate chain first; the key as PKCS#8, PKCS#1 or SEC1. TLS 1.2 and 1.3 (rustls).
  • No client certificates. Clients are identified by token only.
  • TLS protects tokens, it does not replace them.
  • A certificate change takes a restart.
  • Outbound: chronos import postgres://... never sends a password in the clear or as MD5 to a server it has not checked (sslmode=verify-full), unless --allow-plaintext-password is given.

Flags and client settings: Serve.

Encryption and rollback detection

an encrypted database
chronos keygen                                        # prints a new key: 64 hex digitsCHRONOS_KEY_FILE=/run/secrets/chronos chronos serve mydb  # a new folder is encrypted from its first byte
  • What is encrypted (ChaCha20-Poly1305): log records, each bound to its place in the log; the manifest and its history copies; every page; every spill file. Page names become keyed hashes. Tampered bytes are refused, never read as data.
  • What is not: the file names, sizes and timing of writes. Pages are encrypted deterministically so equal pages still dedupe: someone with the files can tell two pages are the same, not what is in them.
  • Backups and uploads are the same bytes, so they are encrypted too, and restoring needs the key.
  • The key is never stored. The folder keeps only a check value. Lose the key and the data is gone. Prefer CHRONOS_KEY_FILE with a 0600 file over CHRONOS_KEY, since a process’s environment can be read by its OS user.
  • Chosen at creation. An existing folder cannot be encrypted in place, and there is no key rotation yet.

An anchor catches someone putting back an older, consistent copy of the folder’s files, which would otherwise open as that older state, even encrypted.

an anchor
chronos --anchor /var/lib/chronos-anchors/mydb serve mydb   # or CHRONOS_ANCHOR=/var/lib/chronos-anchors/mydb
  • It holds the database’s identity and how far its log has got, rewritten durably after every checkpoint’s manifest and at every clean close.
  • At open, a folder behind its anchor refuses: database folder is older than its anchor: rolled back? (code XX0A1). So does a folder that is not the one the anchor belongs to, and an existing folder whose anchor is missing.
  • Keep it outside the folder, somewhere whoever can write the folder cannot: another volume, owned by another user.
  • After a restore, open once with --anchor-reset.
  • Not covered: commits since the last checkpoint or clean close are not in the anchor, so cutting the log back within that stretch goes unnoticed.

Audit trail and metrics

There is no dedicated security log. What is recorded:

  • SHOW AUDIT [FOR AGENT name] [LIMIT n] (HTTP audit, admin only): what agents, the guest and system did, newest first: at, agent, world, action and rows. It is read from the log, so it survives restarts and lasts as long as history does.
  • SHOW HISTORY (HTTP history): each world’s forks, writes, commits, merges and discards.
  • The merge ledger (from 0.6.0): a hash-chained row per merge into main, written with its data: who merged what, under which policy, the rows, a digest. VERIFY LEDGER checks the chain. With it, SHOW DECISION PROVENANCE and SHOW TOMBSTONES: see Merges.
  • Grants and transfers of worlds (from 0.6.0) are in SHOW SECURITY AUDIT.
  • SHOW WORLDS: owner, created, expires, active and parent.
  • SHOW METRICS and GET /metrics (Prometheus’ text format): each kind of operation’s count and latency (p50, p95, p99, max), and counters such as rows_written, errors, conflicts, spilled_bytes, cache_hits, cache_misses, worlds, disk_bytes. Per database, not per client.

Not recorded: who, when it is the database’s own user (the shell, the server or admin token, MCP without --agent). Its changes are in SHOW HISTORY but not in the audit trail. Nor reads, logins, failed logins or client addresses. Creating, changing or dropping an agent is only a write to main, not an event of its own. Lowering history_retention drops the audit trail with the history.

What Chronos protects, and what it leaves to you

Chronos is a database. It controls what agents do to the data inside it. It cannot see, stop or undo anything an agent does anywhere else.

What it protects: data inside Chronos

  • Agents write in worlds, not in main. An agent’s work reaches main only by a merge.
  • Merges go through rules. A merge policy lets an agent’s merge through on its own only within limits you set; everything else waits for a person. Merge checks are SQL rules every merge’s result must keep.
  • Decisions on stale data are caught. A world that checks its reads is held when something it read changed before its merge.
  • Any agent’s changes can be undone, within the history window.
  • Agents held to one tenant see only its rows.
  • Masks hide columns. Masked columns show agents a stand-in instead of the value.
  • Beside your own database: in an attached folder, the same rules apply before a merge is written to the source, and nothing reaches the source any other way.

What it leaves to you: everything outside the database

  • Cloud and platform APIs. An agent that calls your cloud provider, your hosting platform or a SaaS API directly never goes through Chronos. Chronos does not see those calls and cannot undo them.
  • Files on disk, the database folder included: an agent with shell access to the machine can delete it. Run agents in containers that do not mount the folder.
  • Other services’ data, even when an agent copied it from Chronos. NOTIFY ON MERGE queues effects until a merge, but what a worker then does with them is the worker’s. An undo does not unsend a webhook or an email.
  • Rolling back the agent itself. Reverting an agent means reverting its prompt, its tool schema and its model together, and Chronos does not version that. It can say which run made each change, if you put the run’s id in the world’s metadata when it is forked.
  • Network rules, rate limits and a proxy in front of a server that clients you do not control can reach.

Scope credentials for those systems the way Chronos scopes agents: one token per agent, with only the rights its task needs, never an account-wide key, and nothing an agent can find in an unrelated file.

A hardened deployment

  1. Keep both ports on loopback unless something else must reach them. Then give a numeric address, CHRONOS_TOKEN (openssl rand -hex 24, in the environment, not on the command line) and TLS.
  2. Set CHRONOS_ADMIN_TOKEN and keep it for people. Never pass --unsafe on a server agents can reach.
  3. Keep the server and admin tokens out of agents’ reach: not in an agent’s environment, its container, a .env file its tools can read, or a repository it works in. An agent connects with its own token only.
  4. ALTER SYSTEM SET protect_main = on, so a leaked admin token can still merge, but not quietly rewrite main. Turn it on after chronos import, which writes main’s rows.
  5. Give every agent its own agent and token, with only the rights it needs, and set max_worlds, max_changes, writes_per_minute, world_ttl, max_query_ms, max_concurrent and max_memory_mb.
  6. Set max_worlds and world_idle_ttl for the whole database.
  7. For MCP, give each agent its token and the server’s /mcp, or run chronos mcp <folder> --agent NAME where only you start it. Never --allow-merge for an agent you do not fully trust.
  8. Run the server as its own OS user, with the folder 0700, and agents as other OS users, or in containers that hold only their token.
  9. Encrypt with CHRONOS_KEY_FILE, point CHRONOS_SPILL_DIR at a private directory on an encrypted disk, and keep the key somewhere other than the backups.
  10. Put the server behind a proxy that limits connections and request rates if clients you do not control can reach it.

Agents in containers

  • Give the container the agent’s token and nothing else. Not the folder, not the folder’s socket directory ($TMPDIR/chronos-<uid>/), not the server token or the admin token.
  • Connect with the token, not the folder. Over MCP, the server’s /mcp with the agent’s bearer token; over Postgres, the agent’s name as the user and its token as the password; over HTTP, the same bearer token. chronos mcp <folder> opens the folder and takes an agent’s name, not its token, so it does not belong in the container.
  • Let the container reach the server, and nothing else private. A container on Docker’s default bridge can still reach the host and its network. Chronos does not install firewall rules.

Known gaps

  • A panic can leave internal locks poisoned, which makes later writes fail until a restart.
  • No request-rate limits on either port beyond agents’ own quotas and the wait after failed logins.
  • No pg_hba.conf, no client certificates, no replication, no tablespaces.
  • Reads are not scoped per table, row or world.
  • No key rotation for encryption at rest.
  • The audit trail does not record logins, reads, or what the database’s own user did.
  • No high availability built in: no hot standby, no automatic failover, no read replicas.
  • No incremental backups, and no restore of a backup to an arbitrary timestamp.
  • Real power loss is not tested with fault-injected storage.
  • A role whose password is kept as an md5 hash is asked for MD5, which shows the name is such a role.

Differences from Postgres most likely to surprise an application:

  • A multi-statement simple Query is not one implicit transaction.
  • Some unique and foreign-key conflicts surface at COMMIT, not at the statement.
  • LOCK TABLE serializes other LOCK TABLEs but does not block ordinary writers (it warns).
  • A GIN index on jsonb is accepted but finds nothing: every query scans. Index an expression instead.
  • The world is connection state, a hazard behind a pooler without a reset query.

What to do meanwhile: bind to loopback or a private network only your own services reach; put TLS in front whenever the traffic leaves the machine; use --safe and agent tokens so untrusted callers never get the database’s own user’s rights; and set the limits.

How releases are built and signed

A release is made from a version tag. The release build runs the same steps each time and ends in a draft release, which the maintainer reviews and publishes by hand.

  1. Gate: the crash suite, kill -9 under concurrent merges, the simulated interleavings, and the fuzz tests at 100,000 rounds.
  2. Build: x86_64-unknown-linux-musl and aarch64-unknown-linux-musl (static, each in a build image pinned by digest), then aarch64-apple-darwin and x86_64-apple-darwin (cross-compiled with cargo-zigbuild). Each has the Studio’s UI built in and is packed as chronos-<target>.tar.gz.
  3. Publish: each tarball is signed with cosign, keyless, as the release builds’ Google service account. SHA256SUMS is written, install.sh is filled in with the release’s tag and signer, and all of them go into a draft release in the public repository.
  4. Smoke: on Linux, the draft’s files are downloaded and installed with install.sh, checksum and signature checked, and the binary is run.
  • 0.5.0 to 0.6.2 were built on the maintainer’s Mac, while the build service is offline, with the release’s own toolchain (Rust 1.95.0, zig 0.15.2 for every target), and signed as before, as the same service account.
  • Releases up to v0.4.1 were made by a GitHub release workflow and signed with its identity. install.sh accepts both signers, so CHRONOS_VERSION=v0.4.1 still installs verified.
  • The macOS builds are cross-compiled on Linux. They need macOS 13 or later. The arm64 build is ad-hoc signed by the linker.
  • Reproducibility, as far as it was checked: two clean x86-64 musl builds with the same SOURCE_DATE_EPOCH gave the same binary and the same tarball, checked before 0.2.0. The arm64 macOS tarball was byte-identical across two builds, checked on 2026-10-16. Nothing verifies this for every release.
  • For 0.5.0, the arm64 macOS build was run by the maintainer; the x86-64 macOS one was not.
  • No telemetry. The binary connects out only when told to.
  • No container image is published.

Verify a download

The install script always compares the tarball’s SHA-256 with the release’s SHA256SUMS. With CHRONOS_VERIFY=1 it also checks the signature, which needs cosign:

verified install
curl -fsSL https://github.com/2090-labs/Chronos-DB/releases/latest/download/install.sh | CHRONOS_VERIFY=1 sh

By hand, for one target. The signer’s identity is the value of SIGNER_ACCOUNT in the release’s own install.sh:

by hand
T=x86_64-unknown-linux-muslB=https://github.com/2090-labs/Chronos-DB/releases/download/v0.6.2curl -fsSLO $B/chronos-$T.tar.gz -O $B/chronos-$T.tar.gz.sigstore.json -O $B/SHA256SUMS -O $B/install.shgrep " chronos-$T.tar.gz$" SHA256SUMS | sha256sum -c -      # macOS: shasum -a 256 -c -grep '^SIGNER_ACCOUNT=' install.sh                          # the identity to expectcosign verify-blob --bundle chronos-$T.tar.gz.sigstore.json \  --certificate-identity "<SIGNER_ACCOUNT from install.sh>" \  --certificate-oidc-issuer https://accounts.google.com \  chronos-$T.tar.gz
  • The checksum proves the file is the one the release lists. The signature proves the release builds’ identity signed it.
  • A signature that does not verify makes the script stop with has no valid signature from Chronos DB’s release builds; nothing was installed.
  • Reading the identity from install.sh trusts that file. Take it from the same release over HTTPS, and compare it across releases.

Reporting a vulnerability

Do not open a public issue. Use GitHub’s private vulnerability reporting on the public repository. The aim is a reply within 3 working days. Data-loss and corruption bugs count as security problems: report them privately too.

Operate and secure · Chronos