The web service and the board
odu web is the one service behind everything: it runs CI, serves the board, answers the CLI and agents, and serves the cache. The CLI and agents start it when it is not running. Start it yourself to keep it in a terminal, replace it, or change how it is reached.
Commands are written with the odu shorthand.
Start the service
odu web # serve in this terminal
odu web --background # explicitly start or reuse a daemon
odu web --upgrade # replace the existing service, serve here
The default address is http://127.0.0.1:18440.
- If a service is already running, a bare
odu webrefuses. Open its URL, or replace it with--upgrade. - Ctrl + C stops a service in the foreground, not its CI runs.
- A service in the foreground prints the cache’s operational lines (migration, the
CA:pass, NARs served, refusals) and keeps its other logging quiet. Operate the cache lists them.
Use the board
The board lists runs across repositories. Open a run to inspect its nodes, follow logs, pick an earlier attempt, retry a failure or cancel work. The CLI and agents use the same run IDs and see the same state.
The board does everything the CLI does, and more:
| On the board | What you do there |
|---|---|
| Runs, New run, a run’s page | start, watch, retry and cancel runs |
| Machines | probe the machines, and hold one |
| Maintenance | import and prune history, and require odu’s checks on a branch (an admin) |
| Cache, a bucket’s page | read every bucket. An admin also creates a bucket, mints and revokes cache tokens, sets retention, pins and unpins, reads the dry run and runs garbage collection. |
| People | see who is in, and grant or change a role (an owner) |
| Tunnel | see the Cloudflare tunnel and its names |
Anything the board does, odu surface <row> <verb> --input '{…}' --json does from a shell. The CLI reference maps each control to its API verb.
The board shows a control only to a role that may use it, and the service checks the role again on its own, so a hidden button is never the only check. A required field left empty is refused when you click, with the reason.
Access through Tailscale or a proxy
Set up the forwarding yourself. odu can keep listening on loopback, and it answers to whatever name it is reached by. An SSH forward, a Tailscale name, or a proxy that passes the Host header through needs no odu configuration.
Without sign-in, anyone who can reach the forwarded address can control CI. Configure Server mode, and they meet a sign-in page instead.
A proxy that rewrites Host sends a browser Origin that does not match the new Host. Admit that origin when you start the service:
ODU_WEB_ALLOWED_ORIGINS=https://box.tailnet.ts.net \
nix run github:juspay/odu -- web --upgrade
This replaces the running service with one in the foreground. The setting is read when the service starts, and takes several origins separated by commas. On NixOS it is services.odu.allowedOrigins.
| Variable | What it sets |
|---|---|
ODU_WEB_ALLOWED_ORIGINS |
browser origins the service accepts besides its own |
ODU_WEB_ORIGIN |
the address the service listens on, which is also its identity |
ODU_PUBLIC_ORIGIN |
the address a bucket is published under when a proxy stands in front. See Self-host on NixOS. |