Install Kimo Bridge

Install kimo-bridge with Docker, Helm or the static binary, enroll it with a one-time token, and verify it with kimo-bridge doctor.

Updated Oct 9, 20267 min readEdit on GitHub

This page is the short reference. For a fully explained walkthrough with Compose, secrets and troubleshooting, follow the Docker guide or the Kubernetes guide.

Requirements

Requirement	Minimum
Host	Linux x86_64 or arm64, 1 vCPU, 1 GB RAM
Runtime	Docker Engine, Kubernetes 1.27+ with Helm 3.8+, or systemd
Egress	TCP 443 to `bridge.eu.getkimo.com` or `bridge.us.getkimo.com`, plus DNS
Database	Network path from the host; a read replica is recommended
Inbound rules	None

1. Create a read-only role

PostgreSQL, as an administrator

1CREATE ROLE kimo_bridge LOGIN PASSWORD 'use-a-generated-secret';2ALTER ROLE kimo_bridge SET default_transaction_read_only = on;3ALTER ROLE kimo_bridge SET statement_timeout = '30s';4GRANT USAGE ON SCHEMA analytics TO kimo_bridge;5GRANT SELECT ON ALL TABLES IN SCHEMA analytics TO kimo_bridge;

2. Get an enrollment token

In the Bridge console, choose Add a bridge, name it after where it runs (for example fra-prod-01) and copy the token. Tokens start with kbt_, work once and expire after 24 hours.

3. Install

1docker run -d --name kimo-bridge \2  --restart unless-stopped --read-only --cap-drop ALL \3  --security-opt no-new-privileges --user 10001:10001 \4  -e KIMO_BRIDGE_TOKEN_FILE=/run/secrets/token \5  -e KIMO_BRIDGE_CONFIG=/etc/kimo-bridge/kimo-bridge.yaml \6  -v /opt/kimo-bridge/kimo-bridge.yaml:/etc/kimo-bridge/kimo-bridge.yaml:ro \7  -v /opt/kimo-bridge/secrets:/run/secrets:ro \8  -v kimo-bridge-data:/var/lib/kimo-bridge \9  -p 127.0.0.1:8080:8080 \10  ghcr.io/getkimo/bridge:1.4.2

4. Verify

Expected output

1$ kimo-bridge doctor2ok  dns        bridge.eu.getkimo.com resolved3ok  egress     443/tcp reachable (proxy: none)4ok  identity   certificate valid, renews in 21h5ok  tunnel     connected, TLS 1.3, mutual auth6ok  source     crm_pg postgres 16.4, role read-only7ok  policy     2 tables, 11 columns allowed, default deny

Then confirm the bridge shows Connected in the Bridge console. With Docker, prefix commands with docker exec kimo-bridge.

Day-two commands

Command	Effect
`kimo-bridge reload`	Applies policy changes without dropping the tunnel
`kimo-bridge pause` / `resume`	Closes the tunnel and cancels in-flight queries, then reconnects
`kimo-bridge policy check`	Validates `kimo-bridge.yaml` before a reload
`kimo-bridge test-source <id> --sql "…"`	Runs a query locally through the full policy path
`kimo-bridge doctor --bundle`	Writes a redacted diagnostics archive for support