Chronos DB, self-hosted
Run Chronos DB yourself
One binary: install it, start a database, connect with psql or any Postgres driver, and fork your first world.
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
What you run
Chronos DB is one binary, chronos. It holds the shell, the servers (the Postgres protocol and an HTTP API), the MCP server for agents, the importers and the Studio web UI. A database is a folder on disk. There is nothing else to install and no service to sign up for.
Agents work in worlds: copy-on-write branches of the whole database. A world shares all data with the world it was forked from and stores only what it changes. A world’s changes reach main by a merge, which you can read row by row first and undo afterwards.
This page describes Chronos DB 0.6.2, released 2026-11-19.
| Platforms | macOS 13 or later and Linux, on x86-64 and arm64. No Windows. |
| Ports | Postgres protocol on 127.0.0.1:5433, HTTP API on 127.0.0.1:7070. Loopback only by default. |
| Processes | One process opens a folder at a time. Later chronos commands on the same folder run through it. |
| Telemetry | None. The binary connects out only when you tell it to (an import, an attach, --remote). |
Install
The install script comes from the public repository, github.com/2090-labs/Chronos-DB. It installs a prebuilt binary for your user, into ~/.local/bin.
curl -fsSL https://github.com/2090-labs/Chronos-DB/releases/latest/download/install.sh | shexport PATH="$HOME/.local/bin:$PATH" # if ~/.local/bin isn't on your PATH yet (a fresh Ubuntu's isn't)chronos --versionchronos 0.6.2What the script does, in order:
- Picks the build for your OS and CPU from
uname. An OS or CPU with no build fails with a message and installs nothing. - Needs
curl, andsha256sumorshasum. - Downloads
chronos-<target>.tar.gzand the release’sSHA256SUMS, and compares the SHA-256. A mismatch stops withchecksum mismatchand nothing is installed. - With
CHRONOS_VERIFY=1, also checks the build’s signature with cosign (see Verify the download). - Unpacks the binary and runs
chronos --versionwith it before anything is put in place. A build that does not run on the machine is not installed. - Copies it next to the target and renames it into place, so an interrupted install never leaves a half-written binary.
- Prints
installed chronos <version> (<target>) to <folder>/chronos, and how to add the folder to yourPATHif it is not there.
The script never runs anything as root. The whole script runs from a function called on its last line, so a download cut off halfway runs nothing.
| Variable | Default | Effect |
|---|---|---|
| CHRONOS_INSTALL_DIR | ~/.local/bin | the folder to install into. It must be one you can write. For /usr/local/bin, download the script and run it with sudo yourself: sudo env CHRONOS_INSTALL_DIR=/usr/local/bin sh install.sh |
| CHRONOS_VERSION | the release the script came from | a release tag, such as v0.6.2 |
| CHRONOS_VERIFY | off | 1 also checks the build’s signature with cosign |
| CHRONOS_BASE_URL | the release on GitHub | where the files come from: a release, a bucket, or file:// |
curl -fsSL https://github.com/2090-labs/Chronos-DB/releases/latest/download/install.sh \ | CHRONOS_VERSION=v0.6.2 CHRONOS_VERIFY=1 CHRONOS_INSTALL_DIR="$HOME/bin" shThe examples on these pages use psql. On a machine without it: sudo apt-get install postgresql-client (Debian, Ubuntu) or brew install libpq (macOS).
Release builds
Every release has four builds, each a chronos-<target>.tar.gz holding the one binary, with the Studio’s UI built in.
| Target | For | Notes |
|---|---|---|
| aarch64-apple-darwin | macOS on Apple silicon | macOS 13 or later |
| x86_64-apple-darwin | macOS on Intel | macOS 13 or later |
| x86_64-unknown-linux-musl | Linux on x86-64 | static (musl), so it runs on any distribution; needs an x86-64-v2 CPU (POPCNT, SSE4.2), which every x86 server CPU since about 2009 has |
| aarch64-unknown-linux-musl | Linux on arm64 | static (musl) |
- MongoDB is in the released binaries from 0.5.0, so
chronos attachworks beside MongoDB without a build of your own. - Object storage is not stated for the released binaries.
--remote s3://...needs a build with--features s3; see Build from source. - No container image is published.
- No Windows build.
Verify the download
The script always checks the SHA-256 of the tarball against the release’s SHA256SUMS. That proves the file is the one the release lists. It does not prove who made the release.
CHRONOS_VERIFY=1 adds that proof. Each tarball is signed with cosign (keyless, Sigstore), and the signature is published beside it as chronos-<target>.tar.gz.sigstore.json. The script accepts a signature from the release builds’ Google service account, and, for releases up to v0.4.1, from the GitHub release workflow that made them. Anything else fails with has no valid signature from Chronos DB's release builds; nothing was installed.
# needs cosign on your PATHcurl -fsSL https://github.com/2090-labs/Chronos-DB/releases/latest/download/install.sh | CHRONOS_VERIFY=1 shHow releases are built and signed, and how to run the same check by hand: Operate and secure.
Build from source
The engine is one Rust crate. You need Rust 1.90 or newer (edition 2024); the release builds use Rust 1.95.0. Node is needed only to build the Studio’s UI into the binary.
git clone https://github.com/2090-labs/Chronos-DB && cd Chronos-DB(cd studio && npm ci && npm run build) # optional: build the Studio's UI into the binarycargo build --release # the binary is target/release/chronoscargo build --release --features mongo # with attach beside MongoDBcargo build --release --features s3 # with object storage (S3, GCS, R2, MinIO, ...)| Feature | Adds |
|---|---|
| mongo | chronos attach with a mongodb:// or mongodb+srv:// source. A build without it refuses such a URL: this chronos was built without MongoDB: use a build with it (cargo build --features mongo) |
| s3 | object storage for pages and the log: --remote s3://... and gs://... |
- Without the Studio’s UI built,
cargo buildstill works: the binary serves a page that says how to build the Studio. - On Linux the binary uses mimalloc as its allocator. macOS keeps the system allocator.
- On x86-64 the build assumes x86-64-v2 (POPCNT, SSE4.2). For an older CPU, build with
RUSTFLAGS="-C target-cpu=x86-64".
A first database
A database is a folder. chronos serve makes it if it is new and serves it until Ctrl-C or SIGTERM, which close the database cleanly.
chronos serve mydb # makes the folder mydb if it's newchronos: a new database: main is protected (protect_main): its rows change only by merging a world, even with the server's token. Work in a world (CREATE WORLD w; USE WORLD w), then MERGE WORLD wchronos: serving on http://127.0.0.1:7070 (POST /v1/<op>; GET /v1/health)chronos: postgres protocol on 127.0.0.1:5433 (psql postgres://127.0.0.1:5433/main)- Loopback only. Both ports listen on 127.0.0.1. The Postgres port is 5433, not 5432, so it does not collide with a Postgres you already run.
- No password on loopback without a token. With no token at all, every client on the machine is the database’s own user. Anyone who reaches the loopback port can log in under any name, as a superuser.
- Main is protected in a database
chronos servemakes. Its rows change only by merging a world, for every token, the server’s included. Tables, views and other definitions still go straight in, andRESTOREandUNDOstill work. - Any other address needs a token and TLS.
chronos serverefuses to start on an address that is not loopback without them. See Serve.
An application that writes main itself needs protect_main off. No client of the server, and no agent, can turn it off. Run the shell on the database’s machine (it joins the running server) and set it there, or make the folder without it:
chronos mydb "alter system set protect_main = off;" # on the database's machineCHRONOS_PROTECT_MAIN=off chronos serve newdb # or: a new folder made without itWithout a server
chronos mydb opens the same kind of folder as an interactive shell, with no ports. A folder made by the shell, the library or chronos import starts with protect_main off. See the shell below and The chronos command.
Beside a database you already run
chronos attach copies the tables you name from Postgres, MySQL, MariaDB or MongoDB into a folder. Agents fork worlds of the copy, and a merge into main is written to your database first, in one checked transaction. See Beside Postgres, Beside MySQL and MariaDB and Beside MongoDB.
Connect with psql and drivers
psql postgres://127.0.0.1:5433/mainThe database name in the URL is the world. main is the database itself, and every world you fork is another name. A world’s ID works too, and so does name@when to read a world as it was.
export DATABASE_URL="postgres://app@127.0.0.1:5433/main"- Drivers and ORMs connect as they do to Postgres. Whether everything they send works depends on the SQL they send.
- What a client sees at connect:
server_version16.15,server_encodingandclient_encodingUTF8,DateStyleISO, MDY,TimeZoneUTC unless the client asks for another,integer_datetimeson,standard_conforming_stringson. - Isolation levels:
READ COMMITTED(the default) andREPEATABLE READ.SERIALIZABLEis refused (0A000). - The world is connection state. Behind a connection pooler without a reset query, a connection handed to another client is still on the world the last one switched to.
- Agents holding connections: an agent on a Postgres driver holds its connection, and any open transaction, while its model thinks. Point agents at HTTP or MCP where you can.
For a server other machines reach, set two tokens in the environment and give it a certificate. The server token lets a client in as the guest: it reads, forks and changes only its own worlds. The admin token is the database’s own user.
export CHRONOS_TOKEN=$(openssl rand -hex 24) # the guest's: read from the environment, not a flag ps showsexport CHRONOS_ADMIN_TOKEN=$(openssl rand -hex 24) # the database's own user: keep it away from agentschronos serve mydb --pg 0.0.0.0:5433 --tls-cert cert.pem --tls-key key.pem# your application, with the admin token as the passwordexport DATABASE_URL="postgres://app:${CHRONOS_ADMIN_TOKEN}@db-host:5433/main?sslmode=require"# a client with the server token: the guestpsql "postgres://agent:${CHRONOS_TOKEN}@db-host:5433/main?sslmode=require"Every flag, who each token makes a client, and TLS: Serve.
A first world
Fork a world, change it, read what it changed, merge it. In psql, on the server started above:
Make a table and a world
Definitions go straight into
main. Rows go in through a world, becausemainis protected.psql create table todos (id bigserial primary key, title text not null, done boolean not null default false);create world first; -- main's rows change by merging a world: do the work in oneuse world first;Change it
Writes in a world never change another world’s rows, main’s included.
psql insert into todos (title) values ('try chronos'), ('read the docs');update todos set done = true where id = 1;Read the diff
DIFF WORLDlists every row the world changed since its fork:table,id,change(insert,update,delete, or a change to the table itself),before,afterandcolumns. Deleted rows come first.psql diff world first; -- what it changed, row by rowdiff world first summary; -- counted per table, without reading the rowsdiff world first as sql; -- the statements that make the same changeDry run, then merge
A dry run changes nothing. It lists each row the merge would touch with its
outcome(apply,conflict, and the rest), and a lastblockedrow if constraints would refuse the merge.psql use world main;merge world first dry run; -- what a merge would do, and any conflictsmerge world first; -- the tag is MERGE n, n the rows appliedselect * from todos order by id;output id | title | done----+---------------+------ 1 | try chronos | t 2 | read the docs | f(2 rows)A whole merge into the parent drops the world. A merge is three-way, row by row: a row both sides changed since the fork is a conflict, nothing is merged, and the rows come back as data. To throw the work away instead:
drop world first;.Undo it
UNDO MERGEputs back every row the world’s latest merge changed, as an ordinary write. The world is gone, and its name still works here.psql undo merge of world first; -- the tag is UNDO MERGE nselect count(*) from todos; -- 0 againIf rows the merge changed have changed again since, the undo names up to 10 of them and does nothing (
40001);SKIP CHANGEDleaves those and undoes the rest. The merge must be within the history window: 1 hour for a new database. Raise it withalter system set history_retention.
| Statement | Does |
|---|---|
| create world w [from source] [with (owner = 'claude')] | a new world forked from the session’s world, or from source; the session stays where it is |
| use world w | switches the session to w (switch world w is the same) |
| diff world w | what w changed since its fork |
| merge world w dry run | what a merge would do, changing nothing |
| merge world w at version n | merges only if w is still at the version you reviewed |
| merge world w | applies w to its parent and drops it |
| drop world w | throws w away |
| undo merge of world w | puts back what w’s latest merge changed |
| restore world main to '-10 minutes' | the whole world as it was, as an ordinary write |
Every world statement: Worlds. Reading and settling conflicts: Diff and merge.
The same in the shell
chronos mydb is an interactive shell on the folder. It runs SQL and its own short commands. If a server has the folder open, the shell joins it and acts as the database’s own user.
$ 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> undo agent-7 # puts back the rows that merge changedchronos:main> find users where role = admin match adahelplists every command.chronos mydb <command>runs one command and exits;chronos mydb < script.txtruns a file.- The
put users 1 ...lines above writemaindirectly. That works in a folder the shell made, whereprotect_mainis off. In a folderchronos servemade, do the work in a world. - In the shell,
diffmarks+added,-deleted and~changed, by field.
Every shell command and flag: The chronos command.
HTTP, MCP and Studio
The same fork, change and merge over the HTTP API, with chronos serve mydb running on loopback without a token:
curl -s -H 'Content-Type: application/json' localhost:7070/v1/fork -d '{"name":"agent-7"}'curl -s -H 'Content-Type: application/json' localhost:7070/v1/put -d '{"branch":"agent-7","table":"users","id":"1","record":{"name":"Ada L."}}'# {"ok":true,"version":1}curl -s -H 'Content-Type: application/json' localhost:7070/v1/merge -d '{"branch":"agent-7","version":1}'# {"merged":1}An agent in Claude Code, or any MCP client, gets the database as tools. By default it changes only worlds it forked, and a person merges.
claude mcp add chronos -- chronos mcp /path/to/mydbA web UI built around worlds is in the binary too. It works beside a running server on the same folder.
chronos studio mydb # opens http://127.0.0.1:<free port>/#t=<session key> in your browserWhere to go next
Licence
The engine and the chronos binaries are under the Business Source License 1.1: production use is allowed, except offering Chronos DB to third parties as a hosted or managed database service, and each version becomes Apache 2.0 four years after it is published; the Studio, the clients and the docs are MIT.