Chronos/DBWaitlist

Gateway

Install and set up

One command on a server, Docker, Compose, Kubernetes or systemd; the setup code, the console, upgrades and uninstall.

Self-hostedChronos Gateway runs on your own servers today. Releases and install script. The engine under it: Chronos DB, self-hosted

Requirements

WhatNeeded
MachineLinux on x86-64 or arm64 for the installer. The x86-64 build needs an x86-64-v2 CPU (POPCNT, SSE4.2): nearly any server CPU from the last decade. Anything that runs Docker for the image (linux/amd64, linux/arm64). There is no macOS build: use Docker there.
Installercurl, tar, and sha256sum or shasum. For --service: root, systemd and useradd. For CHRONOS_VERIFY=1: cosign.
Kubernetes1.25 or newer, for the Helm chart.
DatabasePostgres 12 or newer, MySQL 8.0 or later, MariaDB 10.5 or later, or MongoDB 5.0 or later as a replica set. The gateway’s host must reach it. See Postgres, MySQL, MariaDB, MongoDB.
Database adminOnce, someone who can create a role and grant rights on the tables, to make the gateway’s own least-privilege role.
DiskRoom for a copy of the tables you attach, in the gateway’s data folder.

Pick a way to install

Each way gives you the same two programs (chronos-gateway and its engine, chronos) and the same API on port 7400. On its first start the gateway prints a setup code: open its console at /console, enter the code, and the console walks you through the rest.

WayForData folder
Installer with --serviceA Linux server. Recommended there./var/lib/chronos-gateway
Installer, binaries onlyYour own user, no root. You start it yourself.gateway-data, or where GATEWAY_DATA says
DockerAny OS that runs Docker./data in the container (a named volume)
Docker ComposeThe same image, hardened, with an https profile for your own domain.a named volume
HelmKubernetes: a StatefulSet of one pod.one volume, 20Gi by default

Installer: a systemd service

This installs the binaries in /usr/local, makes a system user chronos-gateway, keeps data in /var/lib/chronos-gateway and settings in /etc/chronos-gateway/gateway.env, starts the service, and prints the console’s address and a setup code.

as a service
curl -fsSL https://github.com/2090-labs/chronos-gateway-releases/releases/latest/download/install.sh | sudo sh -s -- --service

To read the script before you run it:

read first, then run
curl -fsSLO https://github.com/2090-labs/chronos-gateway-releases/releases/latest/download/install.shless install.shsudo sh install.sh --service

To install one exact release, use that release’s own installer. It also names the engine that release was tested with.

one exact release
curl -fsSL https://github.com/2090-labs/chronos-gateway-releases/releases/download/v0.4.4/install.sh | sudo sh -s -- --service
  • Settings are environment variables in /etc/chronos-gateway/gateway.env. After a change: sudo systemctl restart chronos-gateway.
  • Logs: journalctl -u chronos-gateway. The engine writes to /var/lib/chronos-gateway/engine.log.
  • The unit runs as chronos-gateway with a hardened sandbox (ProtectSystem=strict, NoNewPrivileges, write access to the data folder only), and restarts the gateway if it fails (Restart=on-failure). On stop, the gateway stops the engine cleanly before it exits.

Installer: just the binaries

Without --service the installer puts chronos-gateway in ~/.local/bin and the engine in ~/.local/lib/chronos-gateway/. You start it yourself (it prints a setup code), then open http://127.0.0.1:7400/console.

for your own user
curl -fsSL https://github.com/2090-labs/chronos-gateway-releases/releases/latest/download/install.sh | sh
start it
export GATEWAY_DATA=$HOME/chronos-gateway-datachronos-gateway                         # listens on 127.0.0.1:7400; Ctrl-C stops it

If the installer said ~/.local/bin isn’t on your PATH, run export PATH="$HOME/.local/bin:$PATH" first. Use the same GATEWAY_DATA for every chronos-gateway command. chronos-gateway --help lists every setting.

What the installer does, and its options

  1. Downloads the gateway and its engine for your CPU.
  2. Checks each download against the SHA256SUMS file of its release. With CHRONOS_VERIFY=1 it also checks each one’s cosign signature: made by Chronos’s release account, through Google’s sign-in. On a mismatch or a missing signature it stops and installs nothing.
  3. Runs both binaries once (--version), so a build that can’t run on this machine is never put in place.
  4. Moves them into place. With --service, writes the systemd unit and settings, starts the service, and waits until it answers.
Option or variableEffect
--serviceInstall as a systemd service (Linux, root). Without it: only the binaries.
--uninstallRemove the service and the binaries. Keeps the data and the settings.
CHRONOS_GATEWAY_PREFIXWhere the binaries go. Default /usr/local as root, else ~/.local.
CHRONOS_GATEWAY_VERSIONA release tag such as v0.4.4. Default: the release the script came from.
CHRONOS_VERIFY=1Also check each download’s signature with cosign. The engine it bundles is signed too.
CHRONOS_GATEWAY_BASE_URL, CHRONOS_ENGINE_BASE_URLDownload from a mirror instead of GitHub.

sudo drops environment variables, so pass them through env:

a variable through sudo
curl -fsSL <installer URL> | sudo env CHRONOS_GATEWAY_PREFIX=/opt/chronos sh -s -- --service

Docker

The image is ghcr.io/abhishekxdg/chronos-gateway, tagged by version (0.4.4) and latest, each for linux/amd64 and linux/arm64. It holds both programs on a distroless base (no shell), runs as user 65532, and keeps its data in /data.

docker run
docker run -d --name chronos-gateway --restart unless-stopped \  -p 127.0.0.1:7400:7400 \  -v chronos-gateway:/data \  ghcr.io/abhishekxdg/chronos-gateway:0.4.4docker logs chronos-gateway     # the setup code; then open http://localhost:7400/console
  • -p 127.0.0.1:7400:7400 publishes the API on this machine only. Put TLS in front before anything else calls it.
  • The links the gateway hands out, and the console’s own address, are http://localhost:7400 by default. Behind your own proxy, set -e GATEWAY_DOMAIN=gateway.example.com (links are then https://gateway.example.com/...) or -e GATEWAY_PUBLIC_URL=<the whole URL>.
  • -v chronos-gateway:/data keeps the data in a named volume. If you mount a host folder instead, make it owned by uid 65532.
  • Inside the container the gateway listens on 0.0.0.0:7400, and logs a warning that it listens over plain HTTP. That is expected, and fine while the port is published to 127.0.0.1 only.
  • A database on the same machine is not localhost inside the container. Use host.docker.internal (Docker Desktop; on Linux add --add-host=host.docker.internal:host-gateway to docker run).
  • Commands run in the container: docker exec chronos-gateway chronos-gateway keys create backend.

Docker Compose

The releases repository’s compose.yaml runs the same image with a read-only root filesystem, no Linux capabilities, and the port on this machine only.

Compose, on this machine only
mkdir chronos-gateway && cd chronos-gatewaycurl -fsSLO https://raw.githubusercontent.com/2090-labs/chronos-gateway-releases/main/compose.yamlecho 'GATEWAY_VERSION=0.4.4' > .envdocker compose up -ddocker compose logs gateway     # the setup code; then open http://localhost:7400/console

Compose reads settings from .env in the same folder:

In .envMeaning
GATEWAY_VERSIONThe image’s tag. Default latest.
GATEWAY_DOMAINYour domain, behind HTTPS: sets the gateway’s public address to https://<domain>. The https profile gets its certificate.
GATEWAY_PUBLIC_URLThe whole address people and agents reach, when it isn’t https://<GATEWAY_DOMAIN>.
GATEWAY_ALLOWED_ORIGINSWeb origins allowed to call the approval endpoints from a browser, comma-separated (https://app.example.com).
GATEWAY_TABLES, GATEWAY_TENANT_COLUMNWith the database URL passed as a secret file: the tables to attach at the first start, and the tenant column. See Connect at start.

The file also has commented lines for passing the database URL as a secret file (GATEWAY_SOURCE_FILE). Commands run in the service: docker compose exec gateway chronos-gateway keys create backend.

On your own domain, over HTTPS

The Compose file has an https profile: Caddy in front of the gateway, getting and renewing a Let’s Encrypt certificate for your domain by itself.

  1. Point DNS at the server

    Point the domain’s DNS record (A, or AAAA) at this server, and open ports 80 and 443.

  2. Start both, with the domain in .env

    The domain goes in .env so later docker compose commands use it too.

    Compose with HTTPS
    echo 'GATEWAY_DOMAIN=gateway.example.com' >> .envdocker compose --profile https up -ddocker compose logs gateway     # the setup code; then open https://gateway.example.com/console

The gateway itself still listens on this machine only; Caddy is what the network reaches. Leave out the domain and --profile https to run it on this machine only.

With the installer or plain Docker, put your own TLS proxy (Caddy, nginx, a load balancer) in front of port 7400 and set GATEWAY_DOMAIN (or GATEWAY_PUBLIC_URL) to the address people use.

SettingDefaultMeaning
GATEWAY_LISTEN127.0.0.1:7400 (image: 0.0.0.0:7400)Address and port it listens on.
GATEWAY_PUBLIC_URLhttps:// + GATEWAY_DOMAIN, else http:// + GATEWAY_LISTEN (http://localhost:7400 when it listens on all addresses)How clients and browsers reach it. Used in sql_url, mcp_url, approval links, and the console (which only answers pages opened at this address). Use https:// anywhere but this machine.
GATEWAY_DOMAINunsetIts domain, behind HTTPS (gateway.example.com): sets GATEWAY_PUBLIC_URL to https://<domain>.
GATEWAY_DATAgateway-data (service: /var/lib/chronos-gateway, image: /data)Its data folder.

Kubernetes (Helm)

The Helm chart runs the same image as a StatefulSet: one pod, its data on one volume (20Gi by default), as uid 65532 with a read-only root filesystem and no Linux capabilities, reachable inside the cluster only until you give it an address. No password is shipped in the chart.

helm install
helm install chronos-gateway \  https://github.com/2090-labs/chronos-gateway-releases/releases/download/v0.4.4/chronos-gateway-0.4.4.tgz \  --namespace chronos --create-namespacekubectl -n chronos logs statefulset/chronos-gateway | grep -A4 'Set up Chronos Gateway'   # the setup codekubectl -n chronos port-forward svc/chronos-gateway 7400:7400   # then open http://localhost:7400/console

The install prints these commands too. Settings go in a values file (helm install ... -f values.yaml); the chart’s values.yaml explains each one. The ones most installs set:

ValueWhat it does
ingress.enabled, ingress.host, ingress.classNameHTTPS on your own domain through your ingress controller. TLS ends there; the certificate’s Secret is <release>-tls unless ingress.tls.secretName names one, or cert-manager makes it from ingress.annotations. Sets GATEWAY_PUBLIC_URL to https://<host>.
publicUrlThe whole address people and agents reach, when it isn’t the ingress’s (an internal load balancer, say). Without it or the ingress, the gateway’s links say http://localhost:7400, which only works through port-forward.
postgres.existingSecret, postgres.tables, postgres.tenantColumnConnect at start: a Secret of yours with the URL under the key postgresUrl, mounted as a file, never an environment value.
sso.*Single sign-on for approvers and the console: issuer, clientId, existingSecret (the client secret under the key clientSecret), allow, admins. Needs an https:// address.
envAny other GATEWAY_* setting, such as GATEWAY_POLICY_RULES or GATEWAY_HOLD_TTL.
networkPolicy.enabledOff by default. On, the pod takes calls on 7400 from its own namespace (networkPolicy.ingressFrom) and reaches only your database (networkPolicy.postgres.cidrs, which it then needs), DNS, and port 443 on networkPolicy.https.cidrs (your sign-on provider, webhook targets).
ha.enabledSeveral gateways sharing one store, one leading at a time. Needs a Postgres store and a ReadWriteMany volume: see Configure and operate.
the database URL as a Secret
kubectl -n chronos create secret generic chronos-postgres --from-file=postgresUrl=postgres-url.txt

Run commands in the pod: kubectl -n chronos exec statefulset/chronos-gateway -- chronos-gateway keys create backend. Settings the chart can’t use together (tables without a database URL, sign-on without an https:// address) fail the install with a sentence saying what to set.

The setup code and first sign-in

The console is the gateway’s own admin page, at /console on its address (http://localhost:7400/console, or https://<GATEWAY_DOMAIN>/console). On a new gateway it asks for the setup code.

  1. Find the code in the gateway’s log

    It reads like K7QF-9MXA-2RTD.

    InstallWhere the log is
    Installer, --servicejournalctl -u chronos-gateway (the installer prints the code too)
    Installer, binaries onlythe terminal it runs in
    Dockerdocker logs chronos-gateway
    Docker Composedocker compose logs gateway
    Helmkubectl -n chronos logs statefulset/chronos-gateway | grep -A4 "Set up Chronos Gateway"
  2. Open the console and enter it

    Enter the code with a name for the key it makes (say admin).

  3. Keep the key it shows

    The console shows that key once, then signs you in. Keep the key: it signs you in next time, and your backend can use it too. The gateway keeps only its hash.

  4. Follow Get started

    Get started lists what’s left: connect your database, look at the rules, add a webhook, and send a first run.

  • The code works once, for 7 days, and stops after 20 wrong tries. It is kept as its hash.
  • A new one, while no key exists yet: chronos-gateway setup-code, on the same data folder, as the same user (docker compose exec gateway chronos-gateway setup-code).
  • Once a key exists, no code is needed or made.
  • A key’s sign-in to the console ends when the key is revoked, or after 12 hours.
  • With single sign-on set up, people on GATEWAY_OIDC_ADMINS sign in through your provider and use the whole console; people only on GATEWAY_OIDC_ALLOW can approve, not change settings.
  • The console only answers pages opened at GATEWAY_PUBLIC_URL. Its sign-in is a cookie (HttpOnly, SameSite=Lax, and Secure over https). The page allows only its own scripts and can’t be framed.
Console sign-in answerMeaning
401 bad_codeThe setup code is wrong.
403 setup_lockedThe code stopped after 20 wrong tries. A new one, while no key exists yet: chronos-gateway setup-code.
409 set_upA key exists already: sign in with it.
401 bad_keyThe developer key is wrong or revoked.

Developer keys

Your backend calls the gateway with a developer key (it starts with cgk_). A key is shown once, when it is made. Setting up in the console makes your first key, and Keys makes more: one per backend, so each can be revoked alone. Or from the command line, on the gateway’s data folder:

InstallMake a key
Installer, --servicesudo -u chronos-gateway env GATEWAY_DATA=/var/lib/chronos-gateway /usr/local/bin/chronos-gateway keys create backend
Installer, binaries onlychronos-gateway keys create backend, with the same GATEWAY_DATA as the gateway
Dockerdocker exec chronos-gateway chronos-gateway keys create backend
Docker Composedocker compose exec gateway chronos-gateway keys create backend
Helmkubectl -n chronos exec statefulset/chronos-gateway -- chronos-gateway keys create backend
check the key works
export KEY=cgk_...      # the key you just madecurl -s localhost:7400/v1/status -H "Authorization: Bearer $KEY"

/v1/status answers with the engine’s state ("configured": false until you connect a database), the merge policy, and run counts. To list or revoke keys: chronos-gateway keys list and chronos-gateway keys revoke <id>, with the same data folder (and user). GATEWAY_API_KEY sets one more developer key to accept; it can’t be revoked with keys revoke: remove it and restart.

Verify signatures

Each binary and the image are signed with cosign (keyless, Sigstore) by Chronos’s release account. Every install also checks each download against its release’s SHA256SUMS.

The installer’s downloads

CHRONOS_VERIFY=1 makes the installer check the signatures of both the gateway and its engine. It needs cosign on the machine. On a mismatch or a missing signature it stops and installs nothing.

install, signatures checked
curl -fsSL https://github.com/2090-labs/chronos-gateway-releases/releases/latest/download/install.sh | sudo env CHRONOS_VERIFY=1 sh -s -- --service

The image

cosign verify
cosign verify ghcr.io/abhishekxdg/chronos-gateway:0.4.4 \  --certificate-identity chronos-release@project-7a947b34-cb98-4716-8f2.iam.gserviceaccount.com \  --certificate-oidc-issuer https://accounts.google.com

The image is also pushed with build provenance and an SBOM.

Where data lives

Everything the gateway keeps is in its data folder (GATEWAY_DATA): /var/lib/chronos-gateway with the service, /data in the image, gateway-data otherwise. The folder is readable by the gateway’s user only (the service makes it mode 700). Settings for the service are in /etc/chronos-gateway/gateway.env.

FileHolds
gateway.dbThe SQLite store: token hashes, runs, approvals, events, and webhook signing secrets (needed to sign, so kept as they are). Mode 600.
secret.keyThe key that seals the engine tokens of run agents inside the store. Mode 600.
source.urlThe database URL, with its password. Mode 600.
engine.jsonThe engine’s local port and admin token. Mode 600.
db/The engine’s folder: the copy of the attached tables and the runs’ worlds.
sources/<name>/The same for each further database connected under a name.
engine.logThe engine’s output.
a consistent backup (service)
sudo systemctl stop chronos-gatewaysudo tar -C /var/lib -czf chronos-gateway-backup.tar.gz chronos-gatewaysudo systemctl start chronos-gateway

On the network

  • The engine listens on 127.0.0.1 only.
  • The gateway listens on 127.0.0.1:7400 unless you change it, over plain HTTP. Tokens travel in headers, so put TLS in front (nginx, Caddy, your load balancer) before anything on another machine calls it, and set GATEWAY_PUBLIC_URL to the https:// address.
  • The gateway logs a warning when it listens beyond loopback with an http:// public URL.
  • GET /health answers {"ok": true} without a token, for load balancers. GET /v1/status (with a key) also says whether the engine is healthy.
  • For the approval widget on your own site, the user’s browser must reach the gateway at GATEWAY_PUBLIC_URL, and your site’s origin must be in GATEWAY_ALLOWED_ORIGINS.

Upgrading

Back up the data folder first. Upgrades keep settings, data and keys.

InstallUpgrade
Installer, --serviceRun the same command again: curl -fsSL https://github.com/2090-labs/chronos-gateway-releases/releases/latest/download/install.sh | sudo sh -s -- --service. It replaces both binaries and restarts the service.
Installer, binaries onlyRun the same command again, then restart your chronos-gateway.
Dockerdocker pull ghcr.io/abhishekxdg/chronos-gateway:<version>, then docker rm -f chronos-gateway and run the same docker run command with the new tag. The volume carries over.
Docker ComposeSet the new GATEWAY_VERSION in .env, then docker compose pull && docker compose up -d.
Helmhelm upgrade chronos-gateway <the new release’s chart URL> -n chronos --reuse-values. The volume carries over.

Check the result with chronos-gateway --version (Docker: docker exec chronos-gateway chronos-gateway --version). The bundled engine answers --version too:

InstallEngine version
Installer, --service/usr/local/lib/chronos-gateway/chronos --version
Installer, binaries only~/.local/lib/chronos-gateway/chronos --version
Dockerdocker exec chronos-gateway chronos --version
Helmkubectl -n chronos exec statefulset/chronos-gateway -- chronos --version

Uninstalling

remove the service and both binaries
curl -fsSL https://github.com/2090-labs/chronos-gateway-releases/releases/latest/download/install.sh | sudo sh -s -- --uninstall

This keeps the data folder and the settings. To remove those too (the store, the keys and the engine’s folder; this can’t be undone):

remove the data and settings too
sudo rm -rf /var/lib/chronos-gateway /etc/chronos-gateway && sudo userdel chronos-gateway
  • Binaries only: run the uninstall command with sh instead of sudo sh, and delete your data folder yourself.
  • Docker: docker rm -f chronos-gateway, and docker volume rm chronos-gateway to delete the data.
  • Helm: helm uninstall chronos-gateway -n chronos keeps the volume; kubectl -n chronos delete pvc data-chronos-gateway-0 deletes the data.
  • In your database: the tables you attached stay as they were. The gateway’s role and its own tables (the chronos schema in Postgres; chronos_merges and chronos_merge_rows elsewhere) stay until you drop them.
  • Following Postgres (GATEWAY_FOLLOW): drop the replication slot first, with the gateway stopped (chronos refresh <data>/db --unfollow). A slot left behind keeps Postgres’s WAL.

When install goes wrong

What you seeWhy, and what to do
Installer: “doesn’t run on this machine; nothing was installed”The x86-64 build needs an x86-64-v2 CPU. Use the Docker image on another host.
Installer: “no macOS build of the gateway yet”Use Docker on macOS.
Installer stops on a mismatch or a missing signatureA download didn’t match SHA256SUMS, or with CHRONOS_VERIFY=1 its cosign signature. Nothing was installed.
Log warning “listening on 0.0.0.0:7400 over plain HTTP” in DockerExpected inside the container. It is fine while the port is published to 127.0.0.1 only. Put TLS in front and set an https:// GATEWAY_PUBLIC_URL before exposing it.
The console doesn’t open at an addressThe console only answers pages opened at GATEWAY_PUBLIC_URL. Set GATEWAY_DOMAIN or GATEWAY_PUBLIC_URL to the address people use.
401 with “send a developer key”The Authorization: Bearer cgk_... header is missing, or the token is a run or approval token.
“the engine didn’t start within 30 s”Read engine.log in the data folder.
POST /v1/connect in Docker can’t reach a database on the same machineInside the container, localhost is the container. Use host.docker.internal.
Helm install fails with a sentenceTwo settings the chart can’t use together. The sentence says what to set.

Questions and bug reports: issues. Next: Connect a database.

Install and set up Chronos Gateway · Chronos