calabinet/calabi-coord repository overview

⁠Docker Hub page — calabinet/calabi-coord

⁠Short description

Calabi coordinator — the heart of your own Calabi server: devices, addresses, ACLs, invites.

⁠Overview

⁠Calabi Coordinator

The Calabi coordinator is the heart of a Calabi server you run yourself, together with calabinet/calabi-edge⁠. It registers your devices, gives each a stable 100.64.x.x address on a private WireGuard mesh, keeps the ACLs that decide which devices reach which, and makes invites — a link or QR code a device joins with. A device that joins has public tunnels and the mesh: the coordinator tells it where the edge is and signs the grant the edge accepts.

It never has a private key and never sees your traffic. Open source (Apache-2.0), no account needed: https://github.com/calabinet/calabi⁠

⁠Quick start

On a Linux machine with a public address and Docker Compose (or podman compose):

mkdir calabi && cd calabi
curl -fsSLO https://raw.githubusercontent.com/calabinet/calabi/main/deploy/server/docker-compose.yml
curl -fsSL -o .env https://raw.githubusercontent.com/calabinet/calabi/main/deploy/server/.env.example
# edit .env: CALABI_PUBLIC_HOST, CALABI_ADMIN_TOKEN, and CALABI_TUNNEL_DOMAIN for HTTP tunnels
docker compose up -d

That starts this image and the edge. Open 7012/tcp and 7443/tcp (devices), 80/tcp and 443/tcp (HTTP tunnels), 20000–20999 tcp and udp (TCP and UDP tunnels), 3340/tcp and 3478/udp (the mesh relay).

Then an invite for each device:

docker compose exec coord calabi-coord invite --note laptop

It prints a calabi://join link and a QR code. By default an invite admits one device within 24 hours (--uses 5, --reusable, --expires 72h, --no-expiry, --tag tag:phone). On a computer: calabi join "<link>", or the client's console at http://127.0.0.1:7400 → Connect to a self-hosted server. On a phone: Calabi → Connect to a self-hosted server → scan it.

Devices:

docker compose exec coord calabi-coord device list
docker compose exec coord calabi-coord device disable 3   # or enable, delete, approve

A disabled or deleted device leaves the mesh at once, and its tunnels stop within the hour, when the grant it holds runs out.

The bundle's README: https://github.com/calabinet/calabi/tree/main/deploy/server⁠

⁠What is in /data

The working directory and a volume — back it up:

• coord.db — devices, ACLs and invites (SQLite; the image sets CALABI_COORD_DB_DSN=sqlite:/data/coord.db). For Postgres, set CALABI_COORD_DB_DSN=postgres://….
• coord-grant.key — the key the coordinator signs devices' grants with. The edge checks grants with its public half, which the coordinator writes to /export/coord.pub when CALABI_COORD_GRANT_PUBKEY_FILE says so (the bundle shares /export with the edge, read-only).
• coord-tls/ — the coordinator's self-signed certificate; docker compose exec coord calabi-coord fingerprint prints its fingerprint. Devices pin it, so keep it: a new one has to be confirmed on every device. For your own certificate, mount it and set CALABI_COORD_TLS_CERT_FILE and CALABI_COORD_TLS_KEY_FILE.

⁠More settings

Every setting is an environment variable. Running the coordinator and the edge on different machines, ACLs, subnet routes, exit devices and the full list are in the self-hosting guide: https://github.com/calabinet/calabi/blob/main/docs/self-hosting.md⁠

⁠Tags

• latest — most recent release
• x.y.z — pinned version, from 1.13.0

Both are multi-arch (linux/amd64 + linux/arm64). The binary inside is the released calabi-coord-linux-<arch> one, byte for byte; the release's build-manifest.json says how to rebuild it from source and compare.

Use the same version of calabinet/calabi-edge, and clients from 1.13 or later.

⁠Links

• The server bundle — https://github.com/calabinet/calabi/tree/main/deploy/server⁠
• Self-hosting guide — https://github.com/calabinet/calabi/blob/main/docs/self-hosting.md⁠
• Source (Apache-2.0) — https://github.com/calabinet/calabi⁠
• Edge image — https://hub.docker.com/r/calabinet/calabi-edge⁠