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
| What | Needed |
|---|---|
| Machine | Linux 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. |
| Installer | curl, tar, and sha256sum or shasum. For --service: root, systemd and useradd. For CHRONOS_VERIFY=1: cosign. |
| Kubernetes | 1.25 or newer, for the Helm chart. |
| Database | Postgres 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 admin | Once, someone who can create a role and grant rights on the tables, to make the gateway’s own least-privilege role. |
| Disk | Room 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.
| Way | For | Data folder |
|---|---|---|
Installer with --service | A Linux server. Recommended there. | /var/lib/chronos-gateway |
| Installer, binaries only | Your own user, no root. You start it yourself. | gateway-data, or where GATEWAY_DATA says |
| Docker | Any OS that runs Docker. | /data in the container (a named volume) |
| Docker Compose | The same image, hardened, with an https profile for your own domain. | a named volume |
| Helm | Kubernetes: 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.
curl -fsSL https://github.com/2090-labs/chronos-gateway-releases/releases/latest/download/install.sh | sudo sh -s -- --serviceTo read the script before you run it:
curl -fsSLO https://github.com/2090-labs/chronos-gateway-releases/releases/latest/download/install.shless install.shsudo sh install.sh --serviceTo install one exact release, use that release’s own installer. It also names the engine that release was tested with.
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-gatewaywith 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.
curl -fsSL https://github.com/2090-labs/chronos-gateway-releases/releases/latest/download/install.sh | shexport GATEWAY_DATA=$HOME/chronos-gateway-datachronos-gateway # listens on 127.0.0.1:7400; Ctrl-C stops itIf 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
- Downloads the gateway and its engine for your CPU.
- Checks each download against the
SHA256SUMSfile of its release. WithCHRONOS_VERIFY=1it 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. - Runs both binaries once (
--version), so a build that can’t run on this machine is never put in place. - Moves them into place. With
--service, writes the systemd unit and settings, starts the service, and waits until it answers.
| Option or variable | Effect |
|---|---|
| --service | Install as a systemd service (Linux, root). Without it: only the binaries. |
| --uninstall | Remove the service and the binaries. Keeps the data and the settings. |
| CHRONOS_GATEWAY_PREFIX | Where the binaries go. Default /usr/local as root, else ~/.local. |
| CHRONOS_GATEWAY_VERSION | A release tag such as v0.4.4. Default: the release the script came from. |
| CHRONOS_VERIFY=1 | Also check each download’s signature with cosign. The engine it bundles is signed too. |
| CHRONOS_GATEWAY_BASE_URL, CHRONOS_ENGINE_BASE_URL | Download from a mirror instead of GitHub. |
sudo drops environment variables, so pass them through env:
curl -fsSL <installer URL> | sudo env CHRONOS_GATEWAY_PREFIX=/opt/chronos sh -s -- --serviceDocker
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 -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:7400publishes 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:7400by default. Behind your own proxy, set-e GATEWAY_DOMAIN=gateway.example.com(links are thenhttps://gateway.example.com/...) or-e GATEWAY_PUBLIC_URL=<the whole URL>. -v chronos-gateway:/datakeeps 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 to127.0.0.1only. - A database on the same machine is not
localhostinside the container. Usehost.docker.internal(Docker Desktop; on Linux add--add-host=host.docker.internal:host-gatewaytodocker 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.
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/consoleCompose reads settings from .env in the same folder:
| In .env | Meaning |
|---|---|
| GATEWAY_VERSION | The image’s tag. Default latest. |
| GATEWAY_DOMAIN | Your domain, behind HTTPS: sets the gateway’s public address to https://<domain>. The https profile gets its certificate. |
| GATEWAY_PUBLIC_URL | The whole address people and agents reach, when it isn’t https://<GATEWAY_DOMAIN>. |
| GATEWAY_ALLOWED_ORIGINS | Web origins allowed to call the approval endpoints from a browser, comma-separated (https://app.example.com). |
| GATEWAY_TABLES, GATEWAY_TENANT_COLUMN | With 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.
Point DNS at the server
Point the domain’s DNS record (A, or AAAA) at this server, and open ports 80 and 443.
Start both, with the domain in .env
The domain goes in
.envso laterdocker composecommands 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.
| Setting | Default | Meaning |
|---|---|---|
| GATEWAY_LISTEN | 127.0.0.1:7400 (image: 0.0.0.0:7400) | Address and port it listens on. |
| GATEWAY_PUBLIC_URL | https:// + 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_DOMAIN | unset | Its domain, behind HTTPS (gateway.example.com): sets GATEWAY_PUBLIC_URL to https://<domain>. |
| GATEWAY_DATA | gateway-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 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/consoleThe 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:
| Value | What it does |
|---|---|
| ingress.enabled, ingress.host, ingress.className | HTTPS 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>. |
| publicUrl | The 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.tenantColumn | Connect 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. |
| env | Any other GATEWAY_* setting, such as GATEWAY_POLICY_RULES or GATEWAY_HOLD_TTL. |
| networkPolicy.enabled | Off 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.enabled | Several gateways sharing one store, one leading at a time. Needs a Postgres store and a ReadWriteMany volume: see Configure and operate. |
kubectl -n chronos create secret generic chronos-postgres --from-file=postgresUrl=postgres-url.txtRun 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.
Find the code in the gateway’s log
It reads like
K7QF-9MXA-2RTD.Install Where the log is Installer, --servicejournalctl -u chronos-gateway(the installer prints the code too)Installer, binaries only the terminal it runs in Docker docker logs chronos-gatewayDocker Compose docker compose logs gatewayHelm kubectl -n chronos logs statefulset/chronos-gateway | grep -A4 "Set up Chronos Gateway"Open the console and enter it
Enter the code with a name for the key it makes (say
admin).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.
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_ADMINSsign in through your provider and use the whole console; people only onGATEWAY_OIDC_ALLOWcan approve, not change settings. - The console only answers pages opened at
GATEWAY_PUBLIC_URL. Its sign-in is a cookie (HttpOnly,SameSite=Lax, andSecureover https). The page allows only its own scripts and can’t be framed.
| Console sign-in answer | Meaning |
|---|---|
| 401 bad_code | The setup code is wrong. |
| 403 setup_locked | The code stopped after 20 wrong tries. A new one, while no key exists yet: chronos-gateway setup-code. |
| 409 set_up | A key exists already: sign in with it. |
| 401 bad_key | The 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:
| Install | Make a key |
|---|---|
Installer, --service | sudo -u chronos-gateway env GATEWAY_DATA=/var/lib/chronos-gateway /usr/local/bin/chronos-gateway keys create backend |
| Installer, binaries only | chronos-gateway keys create backend, with the same GATEWAY_DATA as the gateway |
| Docker | docker exec chronos-gateway chronos-gateway keys create backend |
| Docker Compose | docker compose exec gateway chronos-gateway keys create backend |
| Helm | kubectl -n chronos exec statefulset/chronos-gateway -- chronos-gateway keys create backend |
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.
curl -fsSL https://github.com/2090-labs/chronos-gateway-releases/releases/latest/download/install.sh | sudo env CHRONOS_VERIFY=1 sh -s -- --serviceThe image
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.comThe 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.
| File | Holds |
|---|---|
| gateway.db | The SQLite store: token hashes, runs, approvals, events, and webhook signing secrets (needed to sign, so kept as they are). Mode 600. |
| secret.key | The key that seals the engine tokens of run agents inside the store. Mode 600. |
| source.url | The database URL, with its password. Mode 600. |
| engine.json | The 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.log | The engine’s output. |
sudo systemctl stop chronos-gatewaysudo tar -C /var/lib -czf chronos-gateway-backup.tar.gz chronos-gatewaysudo systemctl start chronos-gatewayOn the network
- The engine listens on
127.0.0.1only. - The gateway listens on
127.0.0.1:7400unless 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 setGATEWAY_PUBLIC_URLto thehttps://address. - The gateway logs a warning when it listens beyond loopback with an
http://public URL. GET /healthanswers{"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 inGATEWAY_ALLOWED_ORIGINS.
Upgrading
Back up the data folder first. Upgrades keep settings, data and keys.
| Install | Upgrade |
|---|---|
Installer, --service | Run 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 only | Run the same command again, then restart your chronos-gateway. |
| Docker | docker 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 Compose | Set the new GATEWAY_VERSION in .env, then docker compose pull && docker compose up -d. |
| Helm | helm 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:
| Install | Engine version |
|---|---|
Installer, --service | /usr/local/lib/chronos-gateway/chronos --version |
| Installer, binaries only | ~/.local/lib/chronos-gateway/chronos --version |
| Docker | docker exec chronos-gateway chronos --version |
| Helm | kubectl -n chronos exec statefulset/chronos-gateway -- chronos --version |
Uninstalling
curl -fsSL https://github.com/2090-labs/chronos-gateway-releases/releases/latest/download/install.sh | sudo sh -s -- --uninstallThis 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):
sudo rm -rf /var/lib/chronos-gateway /etc/chronos-gateway && sudo userdel chronos-gateway- Binaries only: run the uninstall command with
shinstead ofsudo sh, and delete your data folder yourself. - Docker:
docker rm -f chronos-gateway, anddocker volume rm chronos-gatewayto delete the data. - Helm:
helm uninstall chronos-gateway -n chronoskeeps the volume;kubectl -n chronos delete pvc data-chronos-gateway-0deletes the data. - In your database: the tables you attached stay as they were. The gateway’s role and its own tables (the
chronosschema in Postgres;chronos_mergesandchronos_merge_rowselsewhere) 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 see | Why, 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 signature | A 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 Docker | Expected 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 address | The 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 machine | Inside the container, localhost is the container. Use host.docker.internal. |
| Helm install fails with a sentence | Two settings the chart can’t use together. The sentence says what to set. |
Questions and bug reports: issues. Next: Connect a database.