Server Overview

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

Launch modes

Startup sequence

When the server starts, it:

1. Loads configuration from ~/.nomadflowcode/config.toml (falls back to defaults).
2. Creates directories — ~/.nomadflowcode/repos/ and ~/.nomadflowcode/worktrees/.
3. Ensures a tmux session exists (creates one if needed).
4. Starts ttyd — spawns a ttyd subprocess attached to the tmux session on the configured port (default 7681).
5. Binds the HTTP server on the configured host and port (default 0.0.0.0:8080).

Graceful shutdown

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

1. The HTTP server stops accepting new connections.
2. In-flight requests are allowed to complete.
3. The ttyd subprocess is stopped — no orphan processes left behind.
4. 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 and feature management (Bearer token auth)
• GET /terminal/ws — WebSocket proxy to ttyd (token query param 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

Ensure the container has tmux and ttyd installed, and that the tmux session can be created inside the container.