A domain for a bucket
A bucket is served at https://<your odu>/cache/<bucket>. Give it a domain of its own, and that is the URL people put in nix.conf, and it stays the same when the server moves. odu does the wiring through Cloudflare: you hand it one API token and set the domain.
Commands are written with the odu shorthand.
Create the Cloudflare token
In Cloudflare, My Profile → API Tokens → Create Token → Custom token:
| Field | Value |
|---|---|
| Token name | odu |
| Permissions | Zone → DNS → Edit, Zone → Zone → Read, Account → Cloudflare Tunnel → Edit |
| Zone Resources | Include → Specific zone → example.com (one line per zone you will use) |
| Account Resources | Include → your account |
Give it to odu
| Setting | What it holds |
|---|---|
ODU_CLOUDFLARE_API_TOKEN_FILE |
a file holding the token |
services.odu.cloudflare.apiTokenFile |
the same, on NixOS, as a systemd credential |
odu checks the token at start. A missing or inactive token stops the tunnel part of the service from starting, with Cloudflare’s own sentence.
Set the domain
On the bucket’s page, type the domain under Domain and save it. Or use the API verb:
odu surface cache bucket_domain --origin https://odu.example.com \
--input '{"rootToken":"'"$ODU_ROOT_TOKEN"'","bucket":"main","domain":"cache.example.com"}' --json
odu then:
- creates one Cloudflare tunnel for this server, named after its public origin, the first time any domain is set;
- routes every domain through that tunnel to the cache;
- creates each proxied DNS record;
- starts the
cloudflaredconnector as a child of the service.
Check that it is live
| State | Meaning |
|---|---|
wiring |
odu is setting it up |
live |
https://<name>/nix-cache-info answers |
failed |
Cloudflare refused, with its reason, such as a token without the DNS permission or a zone the token cannot see |
The bucket’s page and the board’s Tunnel page show the state, and odu surface cloudflare status_read --json returns it in a terminal. Tunnel also shows the connector: running, connected, stopped, or failed with the last words cloudflared said.
Once live, the bucket’s Set up block and odu cache use main print the new URL, and the old /cache/main URL keeps working. Pushes are the same: odu cache push main finds the bucket by name.
What the domain serves
- The domain serves only its bucket.
/is the bucket’s public page, and the Nix protocol’s paths (/nix-cache-info,/<hash>.narinfo,/nar/<file>and the push routes) are served. - Everything else on that domain, such as the board,
/mcp,/authand/rpc/ws, returns 404. The tunnel forwards every path, and odu routes byHost. The board stays oncache.domain. - For a public bucket on a store with a public URL, readers are sent to
<publicUrl>/<bucket>, because that address answers when odu does not. The bucket’s own domain still works for writes and themissingquery. See A public URL for a store. - The connector needs outbound HTTPS from the server and nothing inbound. No port is opened on your network, and your server’s address never appears in DNS.
The server’s own address
When the server’s own host is in a zone the token can edit, the same tunnel carries it too: the board, /mcp and the websocket. A Tailscale Funnel is then not needed, and the GitHub App’s callback URL moves to that name, with publicOrigin.
Remove it
Clear the Domain field, or send bucket_domain with no domain ('{"rootToken":"…","bucket":"main"}'). odu removes the route and the DNS record. The tunnel is this server’s and stays, and the connector stops when the last domain goes.
What a domain does not do
A domain is a name, not a lock. A public bucket is read without a cache token at either address. To limit who reads a bucket, make it private: see Private buckets.