Configuration

NomadFlowCode reads its configuration from ~/.nomadflowcode/config.toml. All fields are optional — sensible defaults are used when omitted.

On first run, the setup wizard automatically creates this file. Running nomadflow or nomadflow serve without an existing config triggers the wizard, which walks you through setting a password and optionally enabling the public tunnel.

When running nomadflow serve with an empty auth.secret, a random secret is auto-generated for the session and displayed in the terminal output.

Full example

version = 1

[paths]
base_dir = "~/.nomadflowcode"

[api]
port = 8080
host = "0.0.0.0"

[web]
port = 3000

[auth]
secret = "my-secret-token"

[tunnel]
subdomain = "fabien"

Reference

`version`

Key	Type	Default	Description
`version`	integer	`1`	Config file format version. Used for future migrations. Old config files without this field are detected as version `0`.

`[paths]`

Key	Type	Default	Description
`base_dir`	string	`~/.nomadflowcode`	Base directory for repos, worktrees, and config. `~` is expanded to the user's home.

The following subdirectories are created automatically:

{base_dir}/repos/ — symlinks or cloned repositories
{base_dir}/worktrees/ — checked-out worktrees per feature
{base_dir}/sessions/ — agent state tracking data

`[api]`

Key	Type	Default	Description
`port`	integer	`8080`	Port for the HTTP API server.
`host`	string	`0.0.0.0`	Bind address for the API server.

Both can be overridden at runtime with nomadflow serve --port <port> and nomadflow serve --host <host>.

`[web]`

Key	Type	Default	Description
`port`	integer	`3000`	Port for the web dashboard server (`nomadflow web`).

Can be overridden at runtime with nomadflow web --port <port>.

`[auth]`

Key	Type	Default	Description
`secret`	string	`""` (empty)	Shared secret for API and terminal authentication. When empty, auth is disabled (or auto-generated in `serve` mode).

When set, this secret is used as:

Bearer token for API requests (Authorization: Bearer <secret>)
Basic Auth password for API requests (Authorization: Basic base64(user:secret))
Query parameter for WebSocket connection (/ws/panes?token=<secret>)
Subprotocol for WebSocket connection (Sec-WebSocket-Protocol: bearer.<secret>)

`[tunnel]`

Settings for the public tunnel (nomadflow serve --public). See Public Tunnel.

Key	Type	Default	Description
`relay_host`	string	`relay.nomadflowcode.dev`	Hostname of the relay server.
`relay_port`	integer	`7835`	Port of the bore server on the relay.
`relay_secret`	string	(built-in)	Shared secret for relay registration. Pre-configured for the community relay — only change this if you self-host.
`subdomain`	string	`""` (random)	Preferred subdomain for a stable public URL. When set, your tunnel always uses `https://<subdomain>.tunnel.nomadflowcode.dev` instead of a random one. Must be 3–32 characters, alphanumeric and hyphens only.

Stable subdomain

By default, each nomadflow serve --public generates a new random subdomain, which means a new QR code to scan every time. Set subdomain to keep the same URL across restarts:

[tunnel]
subdomain = "fabien"
# → https://fabien.tunnel.nomadflowcode.dev

If your IP already holds the subdomain (e.g. after a server restart), it is re-registered automatically. If another IP holds it, registration fails with 409 Conflict.

On this page