Server Overview

The NomadFlowCode server is an Axum HTTP server that provides the API for managing repos, features, and terminal access.

Launch modes

Command	Behavior
`nomadflow`	Starts the server in the background, then launches the TUI wizard. On first run, the setup wizard creates `config.toml`. Server stops gracefully when TUI exits.
`nomadflow serve`	Server-only mode in foreground with full tracing/logging. If no config exists, runs the setup wizard first. Ideal for headless or Docker deployments. Handles Ctrl+C and SIGTERM gracefully.
`nomadflow serve --port 9090`	Same as `serve`, with the API port overridden (default from config: `8080`).
`nomadflow serve --public`	Same as `serve`, but also opens a public tunnel via `*.tunnel.nomadflowcode.dev`. Displays a QR code for instant mobile connection. See Public Tunnel.
`nomadflow web`	Starts a lightweight dashboard server and opens it in the browser (default port from config: `3000`).
`nomadflow start`	Starts the server as a background daemon. PID file: `~/.nomadflowcode/nomadflow.pid`, logs: `~/.nomadflowcode/nomadflow.log`.
`nomadflow stop`	Stops the background daemon via SIGTERM (graceful shutdown).

Startup sequence

When the server starts, it:

Runs setup wizard (if no ~/.nomadflowcode/config.toml exists) — choose a password, optionally enable tunnel.
Loads configuration from ~/.nomadflowcode/config.toml (falls back to defaults).
Creates directories — ~/.nomadflowcode/repos/, ~/.nomadflowcode/worktrees/, and ~/.nomadflowcode/sessions/.
Initializes PaneManager — the central registry for native PTY panes.
Starts AgentStateService — installs and initializes agent tracking hooks.
Binds the HTTP server on the configured host and port (default 0.0.0.0:8080).
Starts Unix socket listener — listens on ~/.nomadflowcode/nomadflow.sock for local CLI attach.

Graceful shutdown

The server supports graceful shutdown via CancellationToken. When a shutdown signal is received (Ctrl+C, SIGTERM, or programmatic cancellation):

The HTTP server stops accepting new connections.
In-flight requests are allowed to complete.
All managed PTY processes are stopped cleanly.
The server exits cleanly.

This applies to all modes: serve (foreground), start/stop (daemon), and the default TUI mode.

Routes

GET /health — health check (no auth)
POST /api/* — repo, feature, session, file, and pane management (Bearer or Basic auth)
GET /ws/panes — multiplexed WebSocket for terminal access (token query param or subprotocol auth)

See API Reference for full details.

Deployment

Bare metal (foreground)

nomadflow serve

Set RUST_LOG=nomadflow_server=debug for verbose logging.

Bare metal (daemon)

# Start
nomadflow start

# Check status
nomadflow --status

# Stop
nomadflow stop

Systemd

[Unit]
Description=NomadFlowCode Server
After=network.target

[Service]
ExecStart=/usr/local/bin/nomadflow serve
Restart=on-failure
Environment=RUST_LOG=nomadflow_server=info

[Install]
WantedBy=multi-user.target

Docker

No external terminal dependencies (like tmux or ttyd) are required. NomadFlowCode uses an integrated Rust-native PTY multiplexer to handle all terminal sessions.

On this page