rebuilderd.conf(5)

💅 rebuilderd.conf — the config file manual (yes bestie, it's a File Formats Manual)

okay so this is the manual page for rebuilderd.conf(5) and honestly it's the glow-up era of config files. It covers both rebuilderd and rebuildctl configuration, so one file, two icons, main character energy. 🎀

---

✨ SYNOPSIS ✨

/etc/rebuilderd.conf

~/.config/rebuilderd.conf

those are the two spots, periodt. 💖

---

🌸 DESCRIPTION 🌸

This file contains configuration for both rebuilderd and rebuildctl. That's it. That's the whole vibe. One file to run the daemon, one file to run the client, and yes they share. 🫶

---

👑 OPTIONS 👑

🌈 [http]

• bind_addr= — the address to bind to. defaults to 127.0.0.1:8484. literally where the daemon sits. 🪑
• real_ip_header= — if you're running a reverse proxy, use this header instead of the actual connecting ip. ⚠️ make sure the reverse proxy has filters in place to prevent spoofing issues, no cap — this is a security thing, not a cute thing. there's no default value, but it's recommended to use "X-Real-IP". 💅
• endpoint= — sets a default endpoint for rebuildctl. this is especially useful for the sync timer. defaults to http://127.0.0.1:8484. slay, defaults. ⭐

🔐 [auth]

• cookie= — a random cookie to authenticate administrators. if this value is not set, rebuilderd is going to generate one on it's own and write it to /var/lib/rebuilderd/auth-cookie. you only need to configure this if you want to administrate remotely. yep, that's the whole caveat. 🍓

🦋 [endpoints."https://rebuilder.example.com"]

• cookie= — this section is usually only configured in ~/.config/rebuilderd.conf. it allows setting cookies for alternative rebuilderd instances with -H. the value passed by -H need to match the section header exactly, so make sure there's no trailing slashes — fr fr, none, not even one. 💀

🧚 [worker]

• authorized_workers= — whitelist public key of rebuilderd-worker instances. see the authentication section in rebuilderd(1) for details. 🔑
• signup_secret= — configure a shared secret that a rebuilderd-worker must provide to be allowed to join. see the authentication section in rebuilderd(1) for details. 🤫

⏰ [schedule]

• retry_delay_base= — configure the delay to automatically retry failed rebuilds, in hours. the default is 24h, and this base is multiplied with the number of rebuilds, so the first retry would happen after 24h, the second retry would happen 48h after the first retry, and the third retry would happen 72h after the second retry. there is no upper limit of retries 😭 — if you can't afford frequent retries it's recommended to set this to a high value like 168 (1 week) or higher. successful rebuilds are not retried. 💜

---

🎀 EXAMPLE 🎀

here's the whole example config, verbatim, because I would never do you dirty like that:

## Configuration for http daemon
#[http]
## The address to bind to. This is 127.0.0.1:8484 by default.
#bind_addr = "0.0.0.0:8484"
## If you use a reverse proxy, use this header instead of the actual connecting ip.
## Make sure the reverse proxy has filters in place to prevent spoofing issues.
#real_ip_header = "X-Real-IP"
## Set a default endpoint for rebuildctl. This is especially useful for the sync timer.
#endpoint = "http://127.0.0.1:8484"

## A random cookie for administration is generated at startup and written to /var/lib/rebuilderd/auth-cookie
## You can set this to a fixed value here. Use `pwgen -1s 32` to generate one.
## rebuildctl is searching for this cookie in ~/.config/rebuilderd.conf, /etc/rebuilderd.conf and
## /var/lib/rebuilderd/auth-cookie in that order.
#[auth]
#cookie = "INSECURE"

## The auth cookie above is only used for the default endpoint.
## You can use different endpoints with `rebuildctl -H https://rebuilder.example.com status`,
## In that case you need to configure a section below if you want to attach a cookie.
#[endpoints."https://rebuilder.example.com"]
#cookie = "INSECURE"

## IMPORTANT: in production, make sure either `authorized_workers` or `signup_secret` is configured.
#[worker]
## If we have a fixed set of workers we can allow-list the keys here.
#authorized_workers = ["key1", "key2"]
## If we want to spawn new workers dynamically we can configure a sign up secret below.
## Use `pwgen -1s 32` to generate one.
#signup_secret = "INSECURE"

#[schedule]
## Configure the delay to automatically retry failed rebuilds in hours. The
## default is 24h, this base is multiplied with the number of rebuilds, so the
## first retry would happen after 24h, the second retry would happen 48h after the
## first retry and the third retry would happen 72h after the second retry. There
## is no upper limit of retries, if you can't afford frequent retries it's
## recommended to set this to a high value like 168 (1 week) or higher.
## Successful rebuilds are not retried.
#retry_delay_base = 24

💀 friendly reminder from the example itself: IMPORTANT: in production, make sure either authorized_workers or signup_secret is configured. don't be that girl with an open worker signup, i'm begging.

---

🔥 SEE ALSO 🔥

rebuilderd(1), rebuildctl(1) — go read those next, iykyk. 📚

---

💖 AUTHORS 💖

rebuilderd was originally written by kpcyrd and is hosted at https://github.com/kpcyrd/rebuilderd — iconic behavior, honestly. 🌟

---

and that's the whole page, bestie! this one's dated 2025-08-29 and it's the rebuilderd.conf(5) page from the File Formats Manual, so yeah — go forth, write your config, and remember: no trailing slashes in that endpoint header. mwah. 💅✨🎀