CLI & environment

eggrd is one binary with a small, flag-shaped CLI. Everything here is what the shipped binary accepts — if you pass something it does not recognise it exits with an error rather than starting anyway, so a typo cannot quietly produce a running-but-wrong proxy.

The binary is called edgeguard

The crate is eggrd; the executable it installs is edgeguard, an earlier working title kept so existing deployments keep working. Both names refer to the same thing throughout these docs.

# from crates.io
$ cargo install eggrd          # installs the `edgeguard` binary

# or the container, amd64 and arm64
$ docker run -p 8080:8080 mancube/eggrd:0.3.1

Command shape

edgeguard [--wrap "<start command>"] [--config <path>]
edgeguard init [--force]
edgeguard doctor [--config <path>]
edgeguard --hash
edgeguard generate [--target <t>] [--config <path>] [--out <path>]
edgeguard --version
edgeguard --help

--version / -V and --help / -h work on every subcommand. Unknown arguments are rejected everywhere as of 0.3.1; before that they were silently discarded, so --version started a proxy instead of printing a version.

Serving

With no subcommand, eggrd serves. There are two shapes, and which one you want depends on whether the app runs beside it or behind it.

Front proxy

The natural mode for a container. eggrd listens, and forwards to an app that is already running somewhere else. Point UPSTREAM at it, or set server.upstream in the config.

$ UPSTREAM=http://app.internal:3000 edgeguard --config edgeguard.toml

Co-process

eggrd starts your app as a child and supervises it, so a single container runs both. Signal handling covers the whole process group on Unix; on Windows it is best-effort, so prefer front-proxy mode there.

$ edgeguard --wrap "npm start" --config edgeguard.toml

init — scaffold a config

Writes a starter edgeguard.toml and a Dockerfile that wraps your app, rather than handing you a blank file to guess at. It refuses to overwrite an existing config unless you pass --force.

$ edgeguard init
$ edgeguard init --force   # overwrite what is already there

doctor — validate before traffic

Loads the config, validates it, and reports foot-guns as warnings. The point is that a bad setting fails at your terminal rather than in front of real requests.

$ edgeguard doctor
0 error(s), 2 warning(s)   # it tells you what you left open

Warnings are not failures. They are the settings that are legal, and that you probably did not mean — the shipped config's placeholder credential being the usual one.

--hash — hash a password

Reads a password on stdin and prints an Argon2id PHC hash suitable for auth.users. Reading from stdin keeps the plaintext out of your shell history and out of the process list.

$ echo -n 'your-password' | edgeguard --hash

generate — emit static-host config

Renders the [headers] policy as configuration for a host that has no room for a proxy. This is the counterpart to the WASM edge worker: use generate when you only need headers, and the worker when you also want auth at the edge.

$ edgeguard generate --target _headers --out _headers

cf-pages, cloudflare-pages, headers, netlify, edge and middleware are accepted as aliases for the four above.

Environment variables

Environment variables override the config file, which is what makes one image deployable across environments without rebuilding it. Anything marked or file also accepts a _FILE suffixed variable naming a path — for Docker and Kubernetes secrets, which arrive as mounted files rather than as environment values.

Build features

The default build has no optional features. That is deliberate: it keeps the shipped binary the lean proxy, with no ML runtime linked in.

Written by hand and checked against the shipped binary's --help. The configuration reference is generated from the source instead, because it is far too large to keep honest any other way.