Chronos DB, self-hosted
The chronos command
Every command and flag: the shell, serve, attach, refresh, backup and restore, and the environment variables they read.
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
Synopsis
One binary does everything. This page is for Chronos DB 0.6.2 (2026-11-19).
chronos [-b branch] [--remote s3://bucket/prefix [--takeover]] [--anchor FILE [--anchor-reset]] <folder> [command]chronos serve <folder> [--listen 127.0.0.1:7070] [--pg 127.0.0.1:5433|off] [--token T] [--admin-token A] [--tls-cert cert.pem --tls-key key.pem | --insecure-no-tls] [--safe | --unsafe] [--studio-api] [--refresh-every 5m] [--follow]chronos mcp <folder> [--allow-merge | --agent NAME] [--unmask]chronos studio <folder> [--port N] [--no-open]chronos studio <folder> --login [--port N | --listen ADDR:PORT] [--host NAME[:PORT]]... [--tls-cert cert.pem --tls-key key.pem | --insecure-no-tls] [--no-open]chronos attach <new folder> (--tables a,b | --schema s) [--lazy-tenant column] [--fields a,b] [--yes]chronos refresh <attached folder> [--unfollow | --tenant value | --check]chronos import <folder> postgres://user:password@host:port/database [--dry-run] [--allow-plaintext-password]chronos import <folder> <table> <data.csv> --schema <schema.csv>chronos restore <backup> <new folder>chronos keygenchronos -V | --versionchronos -h | --helpchronos mydb # interactive shell (the folder is created if missing)chronos mydb get users 1 # one command, then exitCHRONOS_TOKEN=$(openssl rand -hex 24) chronos serve mydb # HTTP on 127.0.0.1:7070, Postgres on 127.0.0.1:5433chronos mcp mydb # MCP server for AI agents, over stdioCommands
| Command | Does |
|---|---|
| chronos <folder> | the interactive shell, when stdin is a terminal |
| chronos <folder> <command...> | runs one shell command or SQL statement and exits |
| chronos <folder> < script.txt | runs stdin, one command per line (SQL may span lines and ends with ;) |
| chronos serve <folder> | the HTTP JSON API and the Postgres protocol, until SIGTERM or Ctrl-C |
| chronos mcp <folder> | an MCP server over stdio |
| chronos studio <folder> | a web UI for the database on 127.0.0.1, beside a running serve too |
| chronos attach <new folder> | a folder that works beside a Postgres, MySQL, MariaDB or MongoDB you already run |
| chronos refresh <attached folder> | main takes the source’s rows as they are now |
| chronos import <folder> postgres://... | a whole Postgres database, moved in one command |
| chronos import <folder> <table> <data.csv> --schema <schema.csv> | a copy of one Postgres table |
| chronos <folder> backup <new folder> | copies the database into a new folder |
| chronos restore <backup> <new folder> | starts a database from a backup folder, and verifies it |
| chronos keygen | prints a new encryption key |
| chronos -V, chronos --version | prints chronos <version> |
| chronos, chronos -h, chronos --help | usage and the shell’s help, exit code 2 |
- One folder, several processes. A folder is open in one process at a time. When
chronos <folder>,chronos mcp,chronos studioorchronos importfinds another chronos process holding it, it runs as a session inside that process instead, over a Unix socket.serveand--remotenever do: they must own the folder. - The socket is
chronos-<hash>.sockin$TMPDIR/chronos-<uid>/, a folder only its user can open (mode0700). Both ends check the other runs as the same OS user. A shell command there is the database’s own user; tokens and--safedo not apply to it. - Stopping.
serve,mcp,studioand the interactive shell close the database cleanly on SIGTERM or Ctrl-C. Ctrl-C at the shell prompt only clears the line being typed. - A file is not a folder.
chronos: <name> is a file; give a database folder(exit 2). - Unknown options fail with
chronos: unknown option --x; see chronos --help(exit 2), rather than opening a database called--x. - Not on this page:
chronos initandchronos cloudbelong to a hosted service that is not open yet.
The shell
chronos <folder> opens the folder, making it if it is missing, and starts on main. -b <world> starts on another world, which must exist.
chronos mydb # interactivechronos mydb "select count(*) from users;" # one statement, then exitchronos -b agent-7 mydb diff # one command on another worldchronos mydb < script.txt # a file: a script runs on past a failed lineThe shell runs SQL and its own commands. A line is SQL when its first word is select, insert, update, delete, create, drop, alter, begin, commit, rollback, show, restore, with, explain, values, savepoint, release, set or simulate, or when it starts merge branch, undo merge, backup database, verify database, or fork, use, switch, diff, merge or replay followed by world. SQL may span lines and ends with ;. Anything else is one of the commands below, one line each.
- The prompt is
chronos:<world>>, with(transaction)while a transaction is open and-while a SQL statement continues. - Skipped: empty lines and lines starting
#or--. - Leaving:
quit,exit,.quit,\qor Ctrl-D.
| Command | Does |
|---|---|
| help, ? | the command list |
| get <table> <id> | prints a row as JSON |
| put <table> <id> <json> | writes a row, e.g. put users 1 {"name": "Ada"} |
| del <table> <id> | deletes a row (an error if there is none) |
| scan <table> [n], ls <table> [n] | lists rows, the first 20 unless n |
| find <table> [where <f> = <v> [and ...]] [match <words>] [near <field> [numbers]] [limit n] [offset n] | filters (a value is JSON if it parses, else text), text search, vector search (near embedding [0.1, 0.2]); best matches first, 20 unless limit |
| tables | tables and row counts |
| describe [table] | fields, example and allowed values, a sample row |
| fork <name> [from <world>] | a new world from the current one (or <world>), and switches to it |
| use <world> | switches world |
| worlds (or branches) | lists worlds: * marks the current one, and each fork shows its parent and change count |
| diff [world] | what changed since the fork: + added, - deleted, ~ changed (by field) |
| merge [world] [ours|theirs] [confirm | at <version>] | merges into the parent (the current world unless named). On conflict nothing is merged and the rows are listed; then ours keeps the world’s values and theirs the parent’s. confirm merges a world that was open in a crash, once you have checked its diff. at <version> (diff shows it) merges only what you read. Merging the world you are on moves you to its parent |
| discard [world] [cascade] | drops a world (the current one unless named); cascade drops its forks too |
| undo [world] | undoes the latest merge into the current world, or the merge of world: puts back the rows it changed, and refuses if any changed again since |
| migrate <folder> | applies the folder’s new .sql files in name order, each in one transaction; applied ones are recorded and skipped |
| checkpoint | compacts the log, which speeds up the next open. Not SQL’s CHECKPOINT WORLD |
| backup <folder> | copies the database, while it runs, into a new folder |
| verify | reads every page and log record, checking each |
| gc | deletes pages nothing uses any more (it runs on its own too) |
$ chronos mydbchronos:main> put users 1 {"name": "Ada", "role": "admin"}chronos:main> put users 2 {"name": "Linus", "role": "user"}chronos:main> describe usersusers (2 rows) name string e.g. "Ada" role string e.g. "admin"chronos:main> fork agent-7 # instant private copychronos:agent-7> put users 1 {"name": "Ada L.", "role": "admin"}chronos:agent-7> diff1 change on agent-7~ users/1 name: "Ada" -> "Ada L."chronos:agent-7> mergemerged 1 change from agent-7 into main; now on mainchronos:main> find users where role = admin match ada- Inside a transaction (
begin;),get,put,del,scanandfindgo to it;fork,use,mergeanddiscardfail witha transaction is open: commit; or rollback; first. - Tables starting
_sonosare the database’s own:get,put,del,scan,ls,findanddescriberefuse them. - Through another process: when a server or another shell has the folder open, the shell says
chronos: connected through the chronos process that has this folder open (type help)and works the same. - A world that does not exist:
chronos: no branch 'x'; see: chronos <folder> branches(exit 1).
serve
chronos serve <folder> serves the HTTP JSON API on 127.0.0.1:7070 and the Postgres protocol on 127.0.0.1:5433. Its flags, tokens, every HTTP operation, TLS and the clients are on Serve: HTTP API and clients. The short version:
| Flag | Default | Effect |
|---|---|---|
| --listen <addr> | 127.0.0.1:7070 | the HTTP API’s address |
| --pg <addr>|off | 127.0.0.1:5433 | the Postgres protocol’s address; off turns it off |
| --token <T> | CHRONOS_TOKEN | the server token, at least 24 characters: a client that sends it is the guest |
| --admin-token <A> | CHRONOS_ADMIN_TOKEN | the token that is the database’s own user over the network, at least 24 characters |
| --safe | off | every client that is not an agent, a role with its password, or the admin token is the guest, loopback without a token too |
| --unsafe | off | the server token is the database’s own user, as before 0.4; not with --safe |
| --tls-cert <file>, --tls-key <file> | CHRONOS_TLS_CERT, CHRONOS_TLS_KEY | HTTPS only, and TLS on the Postgres port; both or neither |
| --insecure-no-tls | off | listen off loopback without TLS, with a warning |
| --studio-api | off | also serve POST /studio/api/<op>, for the admin token only |
| --refresh-every <time> | off | attached folders: a refresh on a timer (60s, 5m, 1h) |
| --follow | off | attached folders: take the source’s changes as they happen |
chronos serve mydb # loopback, no tokenchronos serve mydb --pg off # HTTP onlyCHRONOS_TOKEN=… CHRONOS_ADMIN_TOKEN=… chronos serve mydb --listen 10.0.0.5:7070 --pg 10.0.0.5:5433 \ --tls-cert cert.pem --tls-key key.pem # other machines, with TLSchronos serve ./crm --follow --refresh-every 1h # an attached foldermcp
chronos mcp <folder> serves the database to an AI agent as MCP tools, over stdio. There is no token: whoever starts the process decides who it is.
| Command | Acts as | Tools listed | Changes |
|---|---|---|---|
| chronos mcp mydb | safe mode (the default) | 27: all but merge, restore, undo_merge | only worlds forked in this session |
| chronos mcp mydb --agent bot | the agent bot | those bot has the rights for | what bot may change; its forks stay its own across sessions |
| chronos mcp mydb --allow-merge | the database’s own user | all 30 | everything |
| Flag | Effect |
|---|---|
| --allow-merge | lets the MCP client merge. It gives the session everything, not just merging |
| --agent <name> | the session acts as that agent, with its rights and quotas, and what it does is in the audit trail. It takes a name, not a token. An unknown or disabled agent is refused at start (exit 1). With both --agent and --allow-merge, the session acts as the agent |
| --unmask | masked columns read as they are. Without it they read masked, with --allow-merge too |
| -b <world> | the world must exist or the command exits 1. Tools do not use it: each call names its own branch (default main) |
claude mcp add chronos -- chronos mcp /path/to/mydbclaude mcp add chronos -- chronos mcp /path/to/mydb --agent bot{ "mcpServers": { "chronos": { "command": "chronos", "args": ["mcp", "/path/to/mydb"] } }}- Use an absolute folder path: the client picks the working directory.
- Safe mode without
--agentleaves no audit trail. Use--agentto get the audit trail and quotas. - Anyone who can run
chronos mcpon the folder can name any agent. The flag names who does what; the OS decides who may start it. - Protocol: JSON-RPC 2.0, one message per line.
toolsonly: no resources, no prompts. Methods:initialize,ping,tools/list,tools/call. - Over HTTP instead:
chronos serveanswers the same tools atPOST /mcpfor an agent’s token. See Serve.
studio
chronos studio <folder> serves a web UI for the database. It works beside a running chronos serve, chronos mcp or shell on the same folder. Ctrl-C stops it, and closes the database if the Studio opened it.
chronos studio mydb # opens http://127.0.0.1:<free port>/#t=<session key> in your browserchronos studio mydb --port 7071 # a fixed portchronos studio mydb --no-open # print the link, don't open a browserchronos mydb "create role admin login superuser password 'a long passphrase';"chronos studio mydb --login # http://127.0.0.1:<free port>/: sign in as adminchronos studio mydb --login --listen 0.0.0.0:8443 --host db.example.com \ --tls-cert cert.pem --tls-key key.pem # https://db.example.com:8443/, for the team| Flag | Effect |
|---|---|
| --port <n> | a fixed port on 127.0.0.1. Without it, a free port |
| --no-open | print the link and do not open a browser |
| --login | a sign-in page instead of a key in the link: people sign in with a database role and its password, and the Studio acts as that role |
| --listen <addr:port> | with --login: where it listens. Not together with --port |
| --host <name[:port]> | with --login: a name the Studio answers to; repeat it for several. The port is the one listened on unless given |
| --tls-cert <file>, --tls-key <file> | with --login: needed anywhere but loopback |
| --insecure-no-tls | with --login: listen off loopback without TLS, with a warning |
- Without
--loginthe Studio serves 127.0.0.1 only.--listen,--host,--tls-certand--tls-keyare refused without--login(exit 2). - The key’s link carries a random 256-bit key after
#, which browsers never send to a server. Anyone with the link, on this machine, can use the database as you. - With
--login, a role that is not a superuser runs SQL as itself and sees the status, the worlds and the tables. Everything else the Studio offers needs a superuser role. - Backups are refused in the Studio: its server reads and writes no files by path. Run
chronos mydb backup <folder>instead.
attach
chronos attach makes a new folder that works beside a database you already run. It copies the tables named into the folder in one consistent read. Agents fork worlds and work there as anywhere. Merging a world into main writes its rows to the source first, in one transaction, after checking each row is still as main has it. A row changed in the source meanwhile comes back as a conflict, and nothing is written.
export CHRONOS_SOURCE_URL='postgres://agent_writer:not-a-real-password@staging-db:5432/crm?sslmode=verify-full'chronos attach ./crm --tables public.leads,public.accounts # or --schema appchronos serve ./crmexport CHRONOS_SOURCE_URL='mysql://chronos:not-a-real-password@db.internal:3306/shop?ssl-mode=VERIFY_IDENTITY'chronos attach shop --tables customers,ordersexport CHRONOS_SOURCE_URL='mongodb://chronos:not-a-real-password@db.internal:27017/shop?replicaSet=rs0&tls=true'chronos attach shop --tables customers,orders --fields org_id| Flag | Sources | Effect |
|---|---|---|
| --tables <a,b,...> | all | the tables to attach, comma-separated. For Postgres, schema.table. For MongoDB, the collections |
| --schema <schema> | Postgres | every ordinary table of a schema. Refused for MySQL and MongoDB: --schema is for Postgres |
| --lazy-tenant <column> | Postgres | tables with that column, and those whose foreign key points straight at one, start empty. A tenant’s rows are loaded the first time a world is forked for it, or by chronos refresh <folder> --tenant <value>. Refused for MySQL and MongoDB: --lazy-tenant works with a Postgres source only for now |
| --fields <a,b,...> | MongoDB | top-level fields kept as columns of their own, beside _id and doc (a tenant’s id, say) |
| --yes | all | go ahead above 1,000,000 rows (the source’s estimate), where attach otherwise asks for it: it holds one read open on the source while it copies |
| --source-file <file> | all | the file that holds the connection string, instead of CHRONOS_SOURCE_URL. Sets CHRONOS_SOURCE_FILE |
- The connection string is read from
CHRONOS_SOURCE_URL, or from the fileCHRONOS_SOURCE_FILEnames. It is never a command argument and is written nowhere in the folder. A file others can read is refused:chmod 600it, as it holds a password. - The URL chooses the source:
postgres://,mysql://ormariadb://,mongodb://ormongodb+srv://. - Sources: Postgres; MySQL 8.0 or later; MariaDB 10.5 or later; MongoDB 5.0 or later (a replica set), in a build with MongoDB, which the released binaries are.
- One table is made in the source:
chronos.mergesin Postgres (chronos_mergesin MySQL), a row per merge written. If the role cannot make it, attach prints the statements an administrator runs. - Each table needs a primary key (in Postgres, or a unique index on NOT NULL columns).
- If attach fails, nothing is left behind: the folder is removed again (exit 1).
- Wrong usage prints attach’s own help (exit 2).
--tablesand--yeswith any other command:chronos: --tables and --yes are for chronos attach(exit 2).
What comes over, how a merge is written and what is not there yet: Beside Postgres, Beside MySQL and MariaDB, Beside MongoDB.
refresh
chronos refresh <attached folder> makes main take the source’s rows as they are now. It reads every attached table whole, in one snapshot, and main takes the differences in one change. It needs the connection string, as attach does.
chronos refresh ./crm # once, on a folder no server has openchronos refresh ./crm --tenant 42 # load one tenant's rows, in a folder attached with --lazy-tenantchronos refresh ./crm --unfollow # drop serve --follow's replication slotchronos refresh ./crm --check # compare main with Postgres, take nothing (exit 1 if they differ; from 0.6.2)column added in Postgres, taken: <table.column type>changed in Postgres, taken: <what changed>enum label added in Postgres, taken: <label><table>: <n> inserted, <n> updated, <n> deletedleft as it was: <table and why>The lines name the database the folder is attached to: column added in MySQL, taken: ... beside MySQL, and so on for MariaDB and MongoDB. Before 0.5.2 they said Postgres beside every database. chronos --help and chronos attach’s help cover MySQL, MariaDB and MongoDB too.
| Flag | Effect | Prints |
|---|---|---|
| (none) | a whole refresh | a line per column, label and table, as above |
| --tenant <value> | main takes that tenant’s rows now, in a folder attached with --lazy-tenant | tenant 42: main took <n> rows from Postgres, or tenant 42: main has its rows already |
| --unfollow | beside Postgres: drops the replication slot serve --follow made, so Postgres keeps no WAL for the folder. Beside MongoDB: forgets the change stream’s place, so the next follow begins with a refresh | dropped replication slot <slot>: Postgres keeps no WAL for this folder now, or no replication slot to drop; for MongoDB forgot the change stream’s place: the next follow begins with a refresh |
- A folder a server has open is refused: refresh it with
POST /v1/refreshand the admin token, or run the server with--refresh-every. --unfollowwith any other command:chronos: --unfollow is for chronos refresh on an attached folder(exit 2).- On a timer or as changes happen:
chronos serve --refresh-every 5mandchronos serve --follow. Both are refused with any command butserve.
import
Import moves data into Chronos, where attach works beside the source. There are two forms.
A whole Postgres database
chronos import mydb postgres://user:not-a-real-password@host:5432/app --dry-run # the report, nothing writtenchronos import mydb postgres://user:not-a-real-password@host:5432/app # the importchronos -b staging import mydb postgres://user:not-a-real-password@host:5432/app # into world stagingIt brings over schemas, types (enums, domains, composite types, ranges), sequences, functions, tables (partitioned and inheriting ones too) and their rows, keys, foreign keys, indexes, views, triggers, rules and comments. Anything it cannot bring over, or only in part, is listed at the end.
| Flag | Effect |
|---|---|
| --dry-run | read Postgres and try every definition on an empty in-memory database: the report, and nothing written |
| -b <world> | import into that world instead of main |
| --allow-plaintext-password | send the password to a source that asks for it in the clear or as MD5, over a connection that is not TLS with the server’s certificate checked for its name. Refused otherwise |
- TLS follows the URL’s
sslmode:preferby default;require;verify-fullwithsslrootcertor the system’s CAs. - The password can also come from
PGPASSWORD. SCRAM-SHA-256, Postgres’s default, never sends the password, so it goes over any connection. - Timeouts:
connect_timeout=<seconds>in the URL (default 30) bounds connecting. A source silent for 10 minutes is dropped. - A folder something has open is refused for this form: stop what has it open, or import into a new folder.
--dry-runand--allow-plaintext-passwordwith any other command are refused (exit 2).
One table from CSV
psql -c "\copy TABLE to 'data.csv' csv header"chronos import mydb users data.csv --schema schema.csv--schema <schema.csv> gives the table’s columns and is required. chronos import without the right arguments prints the psql query that makes schema.csv from Postgres (exit 2). This form joins a process that already has the folder open.
backup, restore and verify
chronos mydb backup /backups/mydb-1 # copy the database into a new folderchronos restore /backups/mydb-1 mydb2 # start a database from a backup, and verify itchronos mydb verify # read every page and log record, checking eachrestored /backups/mydb-1 into mydb2, and verified it- While a server runs, back up with
BACKUP DATABASE TO '/backups/db-1'in SQL or thebackupHTTP op.chronos mydb backup <folder>is for when nothing else has the folder open. - A backup is a database folder, consistent as of the moment it started, with worlds and history. Each backup is a full copy.
- It goes into a new or empty folder and is renamed into place at the end, so a failed backup never looks like one.
chronos restoretakes exactly two arguments. The backup is only read. Any closed database folder works as a backup too.- An encrypted backup needs the key:
CHRONOS_KEY=<key> chronos restore /backups/db-1 newdb. - With an anchor, open the restored folder once with
--anchor-reset.
What a backup holds and where to keep it: Operate and secure.
migrate
chronos mydb migrate migrations/ # apply new .sql files in name orderchronos -b staging mydb migrate migrations/ # try them on world staging only, then merge- Whole or not at all: each file runs in one transaction. A file that fails rolls back completely, and the ones before it stay applied. Files must not contain
BEGIN,COMMITorROLLBACK. - Once each: the same transaction records the file and its checksum, so the next run skips it. A file edited after it was applied is refused: add a new one instead.
- Two runs at once cannot both apply a file. The second one’s commit conflicts and rolls back.
keygen and encryption
chronos keygen # prints a new key: 64 hex digitsCHRONOS_KEY=<key> chronos mydb # a new folder is encrypted from its first byteCHRONOS_KEY_FILE=/run/secrets/chronos chronos serve mydbchronos keygen prints the key on stdout and this on stderr: chronos: keep this key safe: without it the database can’t be read. Use it with CHRONOS_KEY=<key> (or CHRONOS_KEY_FILE).
- The key is never a flag, which would show in the process list. It comes from
CHRONOS_KEY, or the fileCHRONOS_KEY_FILEnames whenCHRONOS_KEYis unset or empty. - The key is never stored. The folder keeps only a check value, so a wrong key or a missing one is refused on open. Lose the key and the data is gone.
- Chosen at creation. An existing unencrypted folder cannot be opened with a key. There is no key rotation yet.
--remote and --anchor
export AWS_ACCESS_KEY_ID=… AWS_SECRET_ACCESS_KEY=… AWS_REGION=…export AWS_ENDPOINT=https://<account>.r2.cloudflarestorage.com # R2, MinIO, B2; omit for AWSchronos --remote s3://bucket/prefix mydbchronos --anchor /var/lib/chronos-anchors/mydb serve mydb # or CHRONOS_ANCHOR=/var/lib/chronos-anchors/mydbchronos restore /backups/db-1 mydbchronos --anchor /var/lib/chronos-anchors/mydb --anchor-reset mydb checkpoint # accept a restored folder once| Flag | Effect |
|---|---|
| --remote <url> | back the folder with object storage: s3://bucket/prefix (needs a build with --features s3) or file:///dir. One writer per remote, enforced by a lease |
| --takeover | with --remote: replace a dead owner’s lease on the prefix. The old writer is fenced off |
| --anchor <file> | refuse the folder if its files were rolled back to an older copy. A folder behind its anchor fails with database folder is older than its anchor: rolled back? (code XX0A1). A brand-new folder creates its anchor |
| --anchor-reset | accept the folder as it is and rewrite the anchor for it: after a restore from a backup, or when starting to use an anchor on an existing database |
Every flag
Flags may go anywhere on the line. A flag that takes a value and has none prints the usage (exit 2). A flag given to a command it is not for is refused (exit 2).
| Flag | Default | Used by | Effect |
|---|---|---|---|
| -b, --branch <name> | main | shell, mcp, import | the world to start on, or import into; it must exist |
| --remote <url> | none | all that open a folder | back the folder with object storage |
| --takeover | off | with --remote | replace a dead owner’s lease on the prefix |
| --anchor <file> | CHRONOS_ANCHOR | all that open a folder | refuse a folder whose files were rolled back |
| --anchor-reset | CHRONOS_ANCHOR_RESET=1 | with --anchor | accept the folder as it is, once |
| --listen <addr> | 127.0.0.1:7070 | serve; studio --login | the HTTP API’s address; for the Studio, where it listens |
| --pg <addr>|off | 127.0.0.1:5433 | serve | the Postgres protocol’s address; off turns it off |
| --token <T> | CHRONOS_TOKEN | serve | the server token: a client that sends it is the guest |
| --admin-token <A> | CHRONOS_ADMIN_TOKEN | serve | the token that is the database’s own user over the network |
| --safe | off | serve | every client but an agent, a role with its password or the admin token is the guest |
| --unsafe | off | serve | the server token is the database’s own user, as before 0.4 |
| --tls-cert <file> | CHRONOS_TLS_CERT | serve; studio --login | PEM certificate chain |
| --tls-key <file> | CHRONOS_TLS_KEY | serve; studio --login | PEM private key |
| --insecure-no-tls | off | serve; studio --login | listen off loopback without TLS, with a warning |
| --studio-api | off | serve | also serve POST /studio/api/<op>, for the admin token only |
| --refresh-every <time> | off | serve on an attached folder | a refresh on a timer: 60s, 5m, 1h |
| --follow | off | serve on an attached folder | take the source’s changes as they happen |
| --source-file <file> | CHRONOS_SOURCE_FILE | attach, refresh, serve | the file that holds the source’s connection string |
| --tables <a,b> | none | attach | the tables or collections to attach |
| --schema <s> | none | attach (Postgres); import (CSV) | for attach, every ordinary table of a schema; for a CSV import, the file of the table’s columns |
| --lazy-tenant <column> | none | attach (Postgres) | load a tenant’s rows the first time a world is forked for it |
| --fields <a,b> | none | attach (MongoDB) | top-level fields kept as columns |
| --yes | off | attach | go ahead above 1,000,000 rows |
| --tenant <value> | none | refresh | load one tenant’s rows now |
| --unfollow | off | refresh | drop the replication slot, or forget the change stream’s place |
| --dry-run | off | import ... postgres:// | the report, and nothing written |
| --allow-plaintext-password | off | import ... postgres:// | allow a password in the clear or as MD5 over an unchecked connection |
| --allow-merge | off | mcp | the MCP session is the database’s own user |
| --agent <name> | none | mcp | the MCP session acts as that agent |
| --unmask | off | mcp | masked columns read as they are |
| --port <n> | a free port | studio | a fixed port on 127.0.0.1 |
| --no-open | off | studio | print the link, do not open a browser |
| --login | off | studio | sign in with a database role |
| --host <name[:port]> | none | studio --login | a name the Studio answers to; repeatable |
| -V, --version | prints chronos <version> | ||
| -h, --help | usage and the shell’s help (exit 2) |
Environment variables
Servers and tokens
| Variable | Default | Effect |
|---|---|---|
| CHRONOS_TOKEN | none | serve’s --token: the guest’s |
| CHRONOS_ADMIN_TOKEN | none | serve’s --admin-token: the database’s own user |
| CHRONOS_TLS_CERT, CHRONOS_TLS_KEY | none | serve’s --tls-cert and --tls-key |
| CHRONOS_PROTECT_MAIN | on for a folder serve makes | off makes a new folder with serve without protect_main |
| CHRONOS_LOGIN_FREE_TRIES | 10 | wrong passwords or tokens an address gets before it must wait |
| CHRONOS_LOGIN_TIMEOUT | 60 | seconds a Postgres login may take |
| CHRONOS_REQUEST_TIMEOUT | 120 | seconds an HTTP request may take to arrive |
| CHRONOS_MAX_CONNECTIONS | 1000 | connections at once, per port; lowered to what the process’s open-file limit holds |
| CHRONOS_COPY_IDLE | 60 | seconds a COPY ... FROM STDIN may send no data before the client is dropped |
| CHRONOS_ALLOW_SERVER_COPY | off | 1 allows COPY to and from the server’s own files, lo_import and lo_export, guarded as Postgres guards them |
Attached folders
| Variable | Default | Effect |
|---|---|---|
| CHRONOS_SOURCE_URL | none | the connection string of the database a folder is attached to. Read by attach, refresh and serve |
| CHRONOS_SOURCE_FILE | none | a file holding that connection string, readable only by its owner (mode 600). --source-file sets it |
| CHRONOS_ATTACH_UNSAFE_SOURCE | unset | From 0.6.2. 1: merge into main even though the source may lose commits it acknowledged (Postgres fsync or synchronous_commit off; MySQL innodb_flush_log_at_trx_commit not 1, or sync_binlog not 1 with the binary log on). Unset, such merges are refused |
| CHRONOS_ATTACH_MAX_ROWS | 50000 | changed rows at most per merge into an attached main; it can be raised to 1,000,000 |
| CHRONOS_UNDO_WINDOW_DAYS | 30 | days a merge written to an attached database can be undone by its id |
| CHRONOS_WRITEBACK_RULES | writeback.json in the folder | the file of write-back rules, read again at every merge into main (Postgres) |
Encryption and storage
| Variable | Default | Effect |
|---|---|---|
| CHRONOS_KEY | none | the database key, 64 hex digits (from chronos keygen). A new folder is encrypted with it; an encrypted one needs it to open. Also needed to restore an encrypted backup |
| CHRONOS_KEY_FILE | none | a file holding the key; used when CHRONOS_KEY is unset or empty |
| CHRONOS_ANCHOR | none | --anchor |
| CHRONOS_ANCHOR_RESET | off | 1 is --anchor-reset |
| CHRONOS_MAX_DISK_BYTES | no cap | the most the folder may hold, in bytes. Past it, writes and forks are refused (53100, HTTP 507); reads, deletes, merges and cleanup keep working |
| CHRONOS_LIMITS | none | a file of ceilings over the database’s own settings (max_worlds, history_retention_ms, world_idle_ttl_ms, statement_timeout_ms), which ALTER SYSTEM cannot raise |
| CHRONOS_WAL_SHIPPING | the setting | overrides the wal_shipping setting (with a remote) |
| CHRONOS_WAL_SHIPPING_DELAY_MS | the setting | overrides wal_shipping_delay |
| CHRONOS_GCS_TOKEN_FILE | none | a gs:// remote reads its token from this file |
| AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION, AWS_ENDPOINT, AWS_ALLOW_HTTP | none | credentials and endpoint for --remote s3://..., read the usual AWS way. AWS_ENDPOINT for R2, MinIO, B2; AWS_ALLOW_HTTP=true for a local MinIO |
| HOSTNAME | this machine | names the owner in a --remote lease, shown to a second folder that is refused |
Memory and queries
| Variable | Default | Effect |
|---|---|---|
| CHRONOS_WORK_MEM | 256MB | memory a query may hold in one grouping or sort before it spills to disk: 512kB, 64MB, 2GB (units b, k/kb, m/mb, g/gb, any case) or plain bytes |
| CHRONOS_QUERY_MEM | a quarter of the machine’s memory | working memory one statement may hold before it fails with 53200; all statements together may hold twice it. 0 for no limit |
| CHRONOS_SPILL_DIR | the system’s temporary folder | where query spill files go |
| CHRONOS_CACHE_MB | 256 | the page cache: megabytes of decoded pages kept in memory, per process |
| CHRONOS_THREADS | the number of cores | threads queries may use together |
| CHRONOS_SCAN_WORDS | 8388608 | how much a vector search compares exactly before it walks an HNSW graph instead: higher for recall, lower for speed |
| CHRONOS_VECTOR | graphs on | flat turns HNSW graphs off (every vector search is exact), to compare |
| MIMALLOC_PURGE_DELAY | lazy | Linux builds: 0 hands memory a query freed back to the system at once |
CHRONOS_WORK_MEM, CHRONOS_CACHE_MB, CHRONOS_THREADS, CHRONOS_SCAN_WORDS and CHRONOS_VECTOR are read once, when first needed. A value that does not parse is ignored and the default applies.
Install script and clients
| Variable | Default | Effect |
|---|---|---|
| CHRONOS_INSTALL_DIR | ~/.local/bin | install script: the folder to install into |
| CHRONOS_VERSION | the release the script came from | install script: a release tag, such as v0.6.2 |
| CHRONOS_VERIFY | off | install script: 1 also checks the build’s signature with cosign |
| CHRONOS_BASE_URL | the release on GitHub | install script: where the files come from |
| PGPASSWORD | none | chronos import ... postgres://: the source’s password |
| CHRONOS_URL | none | the pytest plugin chronos_pytest: the server’s URL; without it the test is skipped. It reads CHRONOS_TOKEN too |
Database and session settings
Settings the database keeps in its folder, across restarts. Setting one needs the database’s own user or an agent with admin, and fails with 25001 inside a transaction. = or TO both work, and SHOW <setting> reads each one.
| Setting | Default | Effect |
|---|---|---|
| statement_timeout | 0 (none) | ALTER SYSTEM SET statement_timeout = 30000 or '30s': the timeout every SQL session starts with |
| max_worlds | 0 (no limit) | live worlds at most, besides main and transactions’ own; a fork past it fails with 53400 |
| world_idle_ttl | 0 (never) | '7 days': the background worker discards worlds unused this long |
| history_retention | 1 hour | '7 days' or '0': how far back time travel, undo and the audit trail reach. A database made before 0.2.0 has 30 days |
| synchronous_commit | full | full, normal or off (on means full): how far a commit pushes the log before it returns |
| protect_main | on in a folder serve makes, else off | main’s rows change only by merging a world, for everyone. Only the shell on the database’s machine turns it off |
| wal_shipping | async (with a remote) | off, async or sync (on means sync): how the log reaches the bucket |
| wal_shipping_delay | 1000 (ms) | in async mode, how long written log may wait before it is shipped |
Session settings last for the session: the Postgres connection, or the shell.
| Statement | Effect |
|---|---|
| SET statement_timeout = 5000 | '5s' | DEFAULT | cancels a statement that runs longer, with 57014. A number is ms; a string may end us, ms, s, min, h or d; 0 is none. An agent’s max_query_ms caps it |
| SET search_path TO a, public | where unqualified names are looked up and created; default "$user", public |
| SET hnsw.ef_search = 100 | DEFAULT | the HNSW graph’s beam for this session’s vector searches, 1 to 1000 |
| any other SET | checked as Postgres 16 checks it and kept for the session, so SHOW reads it back; many change nothing here. A session SET synchronous_commit does not change how commits reach the disk: use ALTER SYSTEM |
Exit codes
| Code | When |
|---|---|
| 0 | success |
| 1 | a command, statement or line of a script failed (a script runs on past a failed line); the database cannot be opened; serve refused to start or could not listen; attach, refresh, import or restore failed; closing the database failed |
| 2 | bad usage, an unknown option, a flag given to the wrong command, or a flag without its value. chronos, chronos -h and chronos --help print the usage and exit 2 too |
| 130 | a shell or command running as a session of another process that has the folder open, stopped by SIGTERM or Ctrl-C |
refresh --check | From 0.6.2. 0: main agrees with the source; 1: they differ; 2: it could not compare (an error, a merge still in doubt) or bad usage |