Skip to content
Cadder logo Cadder

Real Caddy resolution

Cadder never embeds Caddy. For normal use, configure [caddy].real_command in cadder.toml next to the Cadder binaries. Use a project-local cadder.toml when a project needs its own real Caddy path. Use CLI flags, environment variables, and PATH fallback as advanced or temporary overrides.

Actual resolver precedence

Section titled “Actual resolver precedence”

The resolver uses this exact order:

  1. CLI override: --real-caddy-command for cadderd and cadder-tui daemon launch, or --cadder-real-caddy-command for the shim.
  2. [caddy].real_command in cadder.toml in the current working directory.
  3. [caddy].real_command in cadder.toml next to the executable.
  4. Environment variables, including CADDER_CADDY_REAL_COMMAND and CADDER_CADDY__REAL_COMMAND.
  5. A safe real caddy executable on PATH.

This differs from the recommended setup order because explicit per-command and per-project overrides must win at runtime.

TOML schema

Section titled “TOML schema”
[caddy]
real_command = "/absolute/path/to/caddy"

The configured command can be:

  • an absolute path, such as /opt/caddy/caddy or C:\Tools\Caddy\caddy.exe;
  • a relative path with a path separator, such as ./tools/caddy, resolved relative to the cadder.toml file that contains it;
  • a plain command, such as caddy, resolved through PATH.

caddy-real is not a built-in default. It works only when you configure it explicitly through CLI, cadder.toml, or an environment variable.

Environment aliases

Section titled “Environment aliases”

Both environment variable names set the same value:

Terminal window
CADDER_CADDY_REAL_COMMAND=/absolute/path/to/caddy
CADDER_CADDY__REAL_COMMAND=/absolute/path/to/caddy

If both are present, CADDER_CADDY_REAL_COMMAND has precedence. Prefer cadder.toml for stable user setups and reserve environment variables for scripts or temporary overrides.

Recursion safety

Section titled “Recursion safety”

PATH fallback excludes the current executable and the known shim path from CADDER_CADDY_SHIM_PATH. When the shim starts the daemon, it passes its own path through that environment variable so the daemon does not select the shim as real Caddy.

If no safe binary can be found, Cadder prints resolution help and asks you to configure the real Caddy command through one of the precedence layers above.