Chronos/DBWaitlist

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

usage
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 | --help
the four you use most
chronos 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 stdio

Commands

CommandDoes
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.txtruns 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 keygenprints a new encryption key
chronos -V, chronos --versionprints chronos <version>
chronos, chronos -h, chronos --helpusage 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 studio or chronos import finds another chronos process holding it, it runs as a session inside that process instead, over a Unix socket. serve and --remote never do: they must own the folder.
  • The socket is chronos-<hash>.sock in $TMPDIR/chronos-<uid>/, a folder only its user can open (mode 0700). Both ends check the other runs as the same OS user. A shell command there is the database’s own user; tokens and --safe do not apply to it.
  • Stopping. serve, mcp, studio and 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 init and chronos cloud belong 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.

three ways to run it
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 line

The 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, \q or Ctrl-D.
CommandDoes
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
tablestables 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
checkpointcompacts 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
verifyreads every page and log record, checking each
gcdeletes pages nothing uses any more (it runs on its own too)
a session
$ 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, scan and find go to it; fork, use, merge and discard fail with a transaction is open: commit; or rollback; first.
  • Tables starting _sonos are the database’s own: get, put, del, scan, ls, find and describe refuse 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:

FlagDefaultEffect
--listen <addr>127.0.0.1:7070the HTTP API’s address
--pg <addr>|off127.0.0.1:5433the Postgres protocol’s address; off turns it off
--token <T>CHRONOS_TOKENthe server token, at least 24 characters: a client that sends it is the guest
--admin-token <A>CHRONOS_ADMIN_TOKENthe token that is the database’s own user over the network, at least 24 characters
--safeoffevery client that is not an agent, a role with its password, or the admin token is the guest, loopback without a token too
--unsafeoffthe 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_KEYHTTPS only, and TLS on the Postgres port; both or neither
--insecure-no-tlsofflisten off loopback without TLS, with a warning
--studio-apioffalso serve POST /studio/api/<op>, for the admin token only
--refresh-every <time>offattached folders: a refresh on a timer (60s, 5m, 1h)
--followoffattached folders: take the source’s changes as they happen
examples
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 folder

mcp

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.

CommandActs asTools listedChanges
chronos mcp mydbsafe mode (the default)27: all but merge, restore, undo_mergeonly worlds forked in this session
chronos mcp mydb --agent botthe agent botthose bot has the rights forwhat bot may change; its forks stay its own across sessions
chronos mcp mydb --allow-mergethe database’s own userall 30everything
FlagEffect
--allow-mergelets 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
--unmaskmasked 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)
add it to a client
claude mcp add chronos -- chronos mcp /path/to/mydbclaude mcp add chronos -- chronos mcp /path/to/mydb --agent bot
any client that starts stdio servers from a JSON config
{  "mcpServers": {    "chronos": { "command": "chronos", "args": ["mcp", "/path/to/mydb"] }  }}
  • Use an absolute folder path: the client picks the working directory.
  • Safe mode without --agent leaves no audit trail. Use --agent to get the audit trail and quotas.
  • Anyone who can run chronos mcp on 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. tools only: no resources, no prompts. Methods: initialize, ping, tools/list, tools/call.
  • Over HTTP instead: chronos serve answers the same tools at POST /mcp for 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.

studio
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
FlagEffect
--port <n>a fixed port on 127.0.0.1. Without it, a free port
--no-openprint the link and do not open a browser
--logina 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-tlswith --login: listen off loopback without TLS, with a warning
  • Without --login the Studio serves 127.0.0.1 only. --listen, --host, --tls-cert and --tls-key are 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.

beside Postgres
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 ./crm
beside MySQL or MariaDB
export CHRONOS_SOURCE_URL='mysql://chronos:not-a-real-password@db.internal:3306/shop?ssl-mode=VERIFY_IDENTITY'chronos attach shop --tables customers,orders
beside MongoDB
export 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
FlagSourcesEffect
--tables <a,b,...>allthe tables to attach, comma-separated. For Postgres, schema.table. For MongoDB, the collections
--schema <schema>Postgresevery ordinary table of a schema. Refused for MySQL and MongoDB: --schema is for Postgres
--lazy-tenant <column>Postgrestables 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,...>MongoDBtop-level fields kept as columns of their own, beside _id and doc (a tenant’s id, say)
--yesallgo 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>allthe 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 file CHRONOS_SOURCE_FILE names. It is never a command argument and is written nowhere in the folder. A file others can read is refused: chmod 600 it, as it holds a password.
  • The URL chooses the source: postgres://, mysql:// or mariadb://, mongodb:// or mongodb+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.merges in Postgres (chronos_merges in 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). --tables and --yes with 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.

refresh
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)
what it prints
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.

FlagEffectPrints
(none)a whole refresha line per column, label and table, as above
--tenant <value>main takes that tenant’s rows now, in a folder attached with --lazy-tenanttenant 42: main took <n> rows from Postgres, or tenant 42: main has its rows already
--unfollowbeside 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 refreshdropped 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/refresh and the admin token, or run the server with --refresh-every.
  • --unfollow with 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 5m and chronos serve --follow. Both are refused with any command but serve.

import

Import moves data into Chronos, where attach works beside the source. There are two forms.

A whole Postgres database

import a 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 staging

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

FlagEffect
--dry-runread 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-passwordsend 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: prefer by default; require; verify-full with sslrootcert or 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-run and --allow-plaintext-password with any other command are refused (exit 2).

One table from CSV

import a table
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

backup and restore
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 each
restore prints
restored /backups/mydb-1 into mydb2, and verified it
  • While a server runs, back up with BACKUP DATABASE TO '/backups/db-1' in SQL or the backup HTTP 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 restore takes 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

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, COMMIT or ROLLBACK.
  • 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

an encrypted database
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 mydb

chronos 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 file CHRONOS_KEY_FILE names when CHRONOS_KEY is 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

object storage (a build with --features s3)
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 mydb
rollback detection
chronos --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
FlagEffect
--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
--takeoverwith --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-resetaccept 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).

FlagDefaultUsed byEffect
-b, --branch <name>mainshell, mcp, importthe world to start on, or import into; it must exist
--remote <url>noneall that open a folderback the folder with object storage
--takeoveroffwith --remotereplace a dead owner’s lease on the prefix
--anchor <file>CHRONOS_ANCHORall that open a folderrefuse a folder whose files were rolled back
--anchor-resetCHRONOS_ANCHOR_RESET=1with --anchoraccept the folder as it is, once
--listen <addr>127.0.0.1:7070serve; studio --loginthe HTTP API’s address; for the Studio, where it listens
--pg <addr>|off127.0.0.1:5433servethe Postgres protocol’s address; off turns it off
--token <T>CHRONOS_TOKENservethe server token: a client that sends it is the guest
--admin-token <A>CHRONOS_ADMIN_TOKENservethe token that is the database’s own user over the network
--safeoffserveevery client but an agent, a role with its password or the admin token is the guest
--unsafeoffservethe server token is the database’s own user, as before 0.4
--tls-cert <file>CHRONOS_TLS_CERTserve; studio --loginPEM certificate chain
--tls-key <file>CHRONOS_TLS_KEYserve; studio --loginPEM private key
--insecure-no-tlsoffserve; studio --loginlisten off loopback without TLS, with a warning
--studio-apioffservealso serve POST /studio/api/<op>, for the admin token only
--refresh-every <time>offserve on an attached foldera refresh on a timer: 60s, 5m, 1h
--followoffserve on an attached foldertake the source’s changes as they happen
--source-file <file>CHRONOS_SOURCE_FILEattach, refresh, servethe file that holds the source’s connection string
--tables <a,b>noneattachthe tables or collections to attach
--schema <s>noneattach (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>noneattach (Postgres)load a tenant’s rows the first time a world is forked for it
--fields <a,b>noneattach (MongoDB)top-level fields kept as columns
--yesoffattachgo ahead above 1,000,000 rows
--tenant <value>nonerefreshload one tenant’s rows now
--unfollowoffrefreshdrop the replication slot, or forget the change stream’s place
--dry-runoffimport ... postgres://the report, and nothing written
--allow-plaintext-passwordoffimport ... postgres://allow a password in the clear or as MD5 over an unchecked connection
--allow-mergeoffmcpthe MCP session is the database’s own user
--agent <name>nonemcpthe MCP session acts as that agent
--unmaskoffmcpmasked columns read as they are
--port <n>a free portstudioa fixed port on 127.0.0.1
--no-openoffstudioprint the link, do not open a browser
--loginoffstudiosign in with a database role
--host <name[:port]>nonestudio --logina name the Studio answers to; repeatable
-V, --versionprints chronos <version>
-h, --helpusage and the shell’s help (exit 2)

Environment variables

Servers and tokens

VariableDefaultEffect
CHRONOS_TOKENnoneserve’s --token: the guest’s
CHRONOS_ADMIN_TOKENnoneserve’s --admin-token: the database’s own user
CHRONOS_TLS_CERT, CHRONOS_TLS_KEYnoneserve’s --tls-cert and --tls-key
CHRONOS_PROTECT_MAINon for a folder serve makesoff makes a new folder with serve without protect_main
CHRONOS_LOGIN_FREE_TRIES10wrong passwords or tokens an address gets before it must wait
CHRONOS_LOGIN_TIMEOUT60seconds a Postgres login may take
CHRONOS_REQUEST_TIMEOUT120seconds an HTTP request may take to arrive
CHRONOS_MAX_CONNECTIONS1000connections at once, per port; lowered to what the process’s open-file limit holds
CHRONOS_COPY_IDLE60seconds a COPY ... FROM STDIN may send no data before the client is dropped
CHRONOS_ALLOW_SERVER_COPYoff1 allows COPY to and from the server’s own files, lo_import and lo_export, guarded as Postgres guards them

Attached folders

VariableDefaultEffect
CHRONOS_SOURCE_URLnonethe connection string of the database a folder is attached to. Read by attach, refresh and serve
CHRONOS_SOURCE_FILEnonea file holding that connection string, readable only by its owner (mode 600). --source-file sets it
CHRONOS_ATTACH_UNSAFE_SOURCEunsetFrom 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_ROWS50000changed rows at most per merge into an attached main; it can be raised to 1,000,000
CHRONOS_UNDO_WINDOW_DAYS30days a merge written to an attached database can be undone by its id
CHRONOS_WRITEBACK_RULESwriteback.json in the folderthe file of write-back rules, read again at every merge into main (Postgres)

Encryption and storage

VariableDefaultEffect
CHRONOS_KEYnonethe 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_FILEnonea file holding the key; used when CHRONOS_KEY is unset or empty
CHRONOS_ANCHORnone--anchor
CHRONOS_ANCHOR_RESEToff1 is --anchor-reset
CHRONOS_MAX_DISK_BYTESno capthe 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_LIMITSnonea 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_SHIPPINGthe settingoverrides the wal_shipping setting (with a remote)
CHRONOS_WAL_SHIPPING_DELAY_MSthe settingoverrides wal_shipping_delay
CHRONOS_GCS_TOKEN_FILEnonea gs:// remote reads its token from this file
AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION, AWS_ENDPOINT, AWS_ALLOW_HTTPnonecredentials and endpoint for --remote s3://..., read the usual AWS way. AWS_ENDPOINT for R2, MinIO, B2; AWS_ALLOW_HTTP=true for a local MinIO
HOSTNAMEthis machinenames the owner in a --remote lease, shown to a second folder that is refused

Memory and queries

VariableDefaultEffect
CHRONOS_WORK_MEM256MBmemory 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_MEMa quarter of the machine’s memoryworking memory one statement may hold before it fails with 53200; all statements together may hold twice it. 0 for no limit
CHRONOS_SPILL_DIRthe system’s temporary folderwhere query spill files go
CHRONOS_CACHE_MB256the page cache: megabytes of decoded pages kept in memory, per process
CHRONOS_THREADSthe number of coresthreads queries may use together
CHRONOS_SCAN_WORDS8388608how much a vector search compares exactly before it walks an HNSW graph instead: higher for recall, lower for speed
CHRONOS_VECTORgraphs onflat turns HNSW graphs off (every vector search is exact), to compare
MIMALLOC_PURGE_DELAYlazyLinux 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

VariableDefaultEffect
CHRONOS_INSTALL_DIR~/.local/bininstall script: the folder to install into
CHRONOS_VERSIONthe release the script came frominstall script: a release tag, such as v0.6.2
CHRONOS_VERIFYoffinstall script: 1 also checks the build’s signature with cosign
CHRONOS_BASE_URLthe release on GitHubinstall script: where the files come from
PGPASSWORDnonechronos import ... postgres://: the source’s password
CHRONOS_URLnonethe 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.

SettingDefaultEffect
statement_timeout0 (none)ALTER SYSTEM SET statement_timeout = 30000 or '30s': the timeout every SQL session starts with
max_worlds0 (no limit)live worlds at most, besides main and transactions’ own; a fork past it fails with 53400
world_idle_ttl0 (never)'7 days': the background worker discards worlds unused this long
history_retention1 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_commitfullfull, normal or off (on means full): how far a commit pushes the log before it returns
protect_mainon in a folder serve makes, else offmain’s rows change only by merging a world, for everyone. Only the shell on the database’s machine turns it off
wal_shippingasync (with a remote)off, async or sync (on means sync): how the log reaches the bucket
wal_shipping_delay1000 (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.

StatementEffect
SET statement_timeout = 5000 | '5s' | DEFAULTcancels 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, publicwhere unqualified names are looked up and created; default "$user", public
SET hnsw.ef_search = 100 | DEFAULTthe HNSW graph’s beam for this session’s vector searches, 1 to 1000
any other SETchecked 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

CodeWhen
0success
1a 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
2bad 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
130a shell or command running as a session of another process that has the folder open, stopped by SIGTERM or Ctrl-C
refresh --checkFrom 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
The chronos command · Chronos