# Configuration

> Every durable-server flag, grouped by what it bounds — storage, the engine, the HTTP edge — with the defaults the binary ships.

Source: https://docs.durable-runner.404human.dev/self-hosting/configuration/

`durable-server` is configured entirely by flags; there is no config file. `durable-server --help`
is the same list in the binary. Defaults shown are what the flag carries.

## The required two, and the directory that matters

| Flag | Default | What it sets |
|---|---|---|
| `--journal <dir>` | `data/journal` | the append-only journal — the runner's only state. Local disk, one writer ever; see [deployment](https://docs.durable-runner.404human.dev/self-hosting/deployment/) |
| `--listen <addr>` | `127.0.0.1:58300` | bind address. Loopback is the default; bind wider only behind a real key and a proxy plan |
| `--handler name=URL` | — | repeatable: the allowlist a step may name. Unregistered names are refused at submit (`409 unregistered_handler`) |

Plus the environment: `DURABLE_API_KEY` (required at startup, ≥ 32 chars) and `DURABLE_READ_KEY`
(optional, ≥ 32 chars, must differ). [Authentication](https://docs.durable-runner.404human.dev/api/authentication/) covers what each opens.

## Engine bounds

| Flag | Default | Bound |
|---|---|---|
| `--step-timeout-ms` | `20000` | per-attempt deadline on a handler call (the domain caps it at 30 s) |
| `--reply-timeout-ms` | `10000` | how long an API call waits on the engine before `503 timeout` — a stuck disk must not hang every request |
| `--max-live-runs` | `100000` | non-terminal runs admitted; past it, submits are `503 at_capacity` |
| `--max-index-bytes` | ~512 MiB | approximate bytes of retained runs in memory; same refusal. Sized for a 2 GB host |
| `--max-in-flight` | `32` | handler calls (attempts + probes) concurrently in flight |
| `--max-dispatch-per-tick` | `64` | dispatches per 50 ms scheduler tick — the first-step dispatch rate is at most ~1280/s |

## HTTP edge

| Flag | Default | Bound |
|---|---|---|
| `--max-connections` | `512` | connections served at once; extras wait in the accept queue. Keep below `ulimit -n` minus 64 |
| `--header-timeout-ms` | `10000` | a request head must arrive within this |
| `--body-deadline-ms` | `30000` | a request body must finish within this (`408` otherwise) |
| `--write-stall-ms` | `10000` | a response write that stalls this long drops the connection |
| `--max-connection-secs` | `600` | a keep-alive connection's maximum age |
| `--max-requests-per-connection` | `100` | the Nth answer carries `Connection: close` |
| `--drain-timeout-secs` | `30` | SIGTERM/SIGINT: finish in-flight requests, then let the engine make its decisions durable, before exiting |

## Storage and maintenance

| Flag | Default | Bound |
|---|---|---|
| `--reserve-bytes` | `67108864` (64 MiB) | free space that must stay on the journal filesystem; below it submits are `503 no_space`, `/ready` is false, compaction and backup refuse what won't fit |
| `--backup-root <dir>` | — | enables `POST /admin/backup`; without it, `403 backups_disabled` |
| `--compact-every-secs` | `0` | automatic compaction period; `0` means only on request (`POST /admin/compact`) |
| `--max-snapshot-bytes` | `2147483648` (2 GiB) | a compaction whose snapshot would exceed this is refused `409 snapshot_over_budget` |
| `--journal-format` | — | print the highest journal record version this binary can read, then exit — the deploy kit's format guard compares it to the journal's before an upgrade or rollback |

## Per-client limits

One address shouldn't be able to hold every connection or spend every request: these flags bound
per-client pressure at the edge. All on by default — `0` disables any of them.

| Flag | Default | Bound |
|---|---|---|
| `--rate-limit-per-addr` | `100` per second | requests one client address may start; a token bucket with a one-second burst, the address table itself bounded. Over it, `429 rate_limited` with `Retry-After` |
| `--rate-limit-v6-prefix` | `64` | prefix bits an IPv6 client is keyed by — a /64 holds 2⁶⁴ addresses, so keying the full address would let one client mint unlimited buckets |
| `--max-conns-per-addr` | `64` | connections one untrusted address may hold at once; past it the socket is closed at accept |
| `--max-conns-per-proxy` | `4096` | connections one peer *inside* the trusted ranges may hold — a proxy's edge legitimately carries many real clients at once (the global `--max-connections` still bounds everything) |
| `--trusted-proxy <CIDR>` | — | repeatable: the proxy ranges the server believes. A client's address comes from `CF-Connecting-IP` **only** when the peer is inside a trusted range — anyone can set that header, so it is believed from no one else |

Inside a `/48` the per-address IPv6 buckets also share a `/48` aggregate at 10× the rate, so a
host hopping addresses inside its own prefix stays one client and a whole /48 can't hide a flood;
IPv4-mapped IPv6 addresses count as IPv4. `429 rate_limited` is retryable — back off by
`Retry-After`, resubmit with the same `op_key`.

A second instance with a low rate shows the shape — five requests a second per address, a ten-
request burst, then the honest refusal:

```sh
./target/release/durable-server --journal journal-limits --listen 127.0.0.1:58301 \
  --rate-limit-per-addr 5 --trusted-proxy 10.0.0.0/8 >limits-server.log 2>&1 &
LIMITED=$!
for _ in $(seq 1 100); do curl -sf http://127.0.0.1:58301/health >/dev/null && break; sleep 0.1; done
for i in $(seq 1 10); do
  curl -s -o /dev/null -w '%{http_code} ' -H "Authorization: Bearer $DURABLE_API_KEY" http://127.0.0.1:58301/jobs
done; echo
curl -si -H "Authorization: Bearer $DURABLE_API_KEY" http://127.0.0.1:58301/jobs | sed -n '1p;/retry-after/Ip;/rate_limited/p'
kill $LIMITED 2>/dev/null; wait $LIMITED 2>/dev/null || true; rm -rf journal-limits limits-server.log
```

```text match=lines
200 200 200 200 429 429 429 429 429 429 
HTTP/1.1 429 Too Many Requests
retry-after: 1
{"error":"rate limited","code":"rate_limited"}
```

## The UI and the loophole

| Flag | Default | Bound |
|---|---|---|
| `--ui-dir <dir>` | — | serve the built Inspector assets at `/inspector` |
| `--open-reads` | off | serve `GET /jobs*` without a key — **loopback listen only** (refused at startup otherwise), and never behind a proxy; [authentication](https://docs.durable-runner.404human.dev/api/authentication/) explains why |

## A production-shaped start

```sh not-
DURABLE_API_KEY="$(openssl rand -hex 32)" \
DURABLE_READ_KEY="$(openssl rand -hex 32)" \
durable-server --journal /var/lib/durable/journal --listen 127.0.0.1:58300 \
  --handler invoices=http://127.0.0.1:58320/invoices \
  --handler reports=http://127.0.0.1:58321/reports \
  --backup-root /var/lib/durable/backups --compact-every-secs 3600
```

The loopback listen is deliberate: TLS terminates at the proxy in front, and the read surface
still wants the keys. [Security](https://docs.durable-runner.404human.dev/self-hosting/security/) is the checklist this start assumes.
