Chronos/DBWaitlist

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.

PlatformsmacOS 13 or later and Linux, on x86-64 and arm64. No Windows.
PortsPostgres protocol on 127.0.0.1:5433, HTTP API on 127.0.0.1:7070. Loopback only by default.
ProcessesOne process opens a folder at a time. Later chronos commands on the same folder run through it.
TelemetryNone. 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.

install
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 --version
output
chronos 0.6.2

What the script does, in order:

  1. Picks the build for your OS and CPU from uname. An OS or CPU with no build fails with a message and installs nothing.
  2. Needs curl, and sha256sum or shasum.
  3. Downloads chronos-<target>.tar.gz and the release’s SHA256SUMS, and compares the SHA-256. A mismatch stops with checksum mismatch and nothing is installed.
  4. With CHRONOS_VERIFY=1, also checks the build’s signature with cosign (see Verify the download).
  5. Unpacks the binary and runs chronos --version with it before anything is put in place. A build that does not run on the machine is not installed.
  6. Copies it next to the target and renames it into place, so an interrupted install never leaves a half-written binary.
  7. Prints installed chronos <version> (<target>) to <folder>/chronos, and how to add the folder to your PATH if 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.

VariableDefaultEffect
CHRONOS_INSTALL_DIR~/.local/binthe 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_VERSIONthe release the script came froma release tag, such as v0.6.2
CHRONOS_VERIFYoff1 also checks the build’s signature with cosign
CHRONOS_BASE_URLthe release on GitHubwhere the files come from: a release, a bucket, or file://
a chosen version, verified, into another folder
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" sh

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

TargetForNotes
aarch64-apple-darwinmacOS on Apple siliconmacOS 13 or later
x86_64-apple-darwinmacOS on IntelmacOS 13 or later
x86_64-unknown-linux-muslLinux on x86-64static (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-muslLinux on arm64static (musl)
  • MongoDB is in the released binaries from 0.5.0, so chronos attach works 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.

install with the signature checked
# needs cosign on your PATHcurl -fsSL https://github.com/2090-labs/Chronos-DB/releases/latest/download/install.sh | CHRONOS_VERIFY=1 sh

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

build
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, ...)
FeatureAdds
mongochronos 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)
s3object storage for pages and the log: --remote s3://... and gs://...
  • Without the Studio’s UI built, cargo build still 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.

start a server
chronos serve mydb               # makes the folder mydb if it's new
output
chronos: 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 serve makes. Its rows change only by merging a world, for every token, the server’s included. Tables, views and other definitions still go straight in, and RESTORE and UNDO still work.
  • Any other address needs a token and TLS. chronos serve refuses 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:

turn protect_main off
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 it

Without 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
psql postgres://127.0.0.1:5433/main

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

an application
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_version 16.15, server_encoding and client_encoding UTF8, DateStyle ISO, MDY, TimeZone UTC unless the client asks for another, integer_datetimes on, standard_conforming_strings on.
  • Isolation levels: READ COMMITTED (the default) and REPEATABLE READ. SERIALIZABLE is 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.

a server other machines reach
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:

  1. Make a table and a world

    Definitions go straight into main. Rows go in through a world, because main is 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;
  2. 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;
  3. Read the diff

    DIFF WORLD lists every row the world changed since its fork: table, id, change (insert, update, delete, or a change to the table itself), before, after and columns. 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 change
  4. Dry 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 last blocked row 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;.

  5. Undo it

    UNDO MERGE puts 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 again

    If rows the merge changed have changed again since, the undo names up to 10 of them and does nothing (40001); SKIP CHANGED leaves those and undoes the rest. The merge must be within the history window: 1 hour for a new database. Raise it with alter system set history_retention.

StatementDoes
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 wswitches the session to w (switch world w is the same)
diff world wwhat w changed since its fork
merge world w dry runwhat a merge would do, changing nothing
merge world w at version nmerges only if w is still at the version you reviewed
merge world wapplies w to its parent and drops it
drop world wthrows w away
undo merge of world wputs 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.

five minutes in the shell
$ 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 ada
  • help lists every command.
  • chronos mydb <command> runs one command and exits; chronos mydb < script.txt runs a file.
  • The put users 1 ... lines above write main directly. That works in a folder the shell made, where protect_main is off. In a folder chronos serve made, do the work in a world.
  • In the shell, diff marks + 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
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.

MCP
claude mcp add chronos -- chronos mcp /path/to/mydb

A web UI built around worlds is in the binary too. It works beside a running server on the same folder.

Studio
chronos studio mydb                # opens http://127.0.0.1:<free port>/#t=<session key> in your browser

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

Run Chronos DB yourself · Chronos