When to Use Herdr Headless Server Mode: 5 Key Scenarios

Use Herdr's headless server mode when you need persistent background sessions, remote thin-client access, or API-driven automation without a controlling terminal.

Herdr is an open-source terminal workspace manager (ogulcancelik/herdr) that supports two distinct execution models. While the default foreground mode launches an interactive TUI that captures your terminal, the headless server mode decouples the application state from the display, enabling robust background operation and network-transparent client connections.

How Herdr Modes Compare

Herdr operates fundamentally differently depending on how you invoke it:

• Foreground mode (default): Starts a full-screen TUI, enters raw terminal mode, reads directly from stdin, and renders to stdout. Best for interactive local editing and quick one-off sessions.
• Headless server mode: Launches the event loop without a real terminal, creates Unix domain sockets (herdr.sock for JSON API and herdr-client.sock for binary protocol), and streams rendered frames to connected thin clients.

The dispatch logic resides in src/main.rs, where the application checks for the server argument:

// src/main.rs – entry point
if args.get(1).map(|s| s.as_str()) == Some("server") {
    return server::headless::run_server();
}

How Headless Server Mode Works Internally

When you invoke herdr server, the application bypasses terminal initialization entirely. According to the source code in src/server/headless.rs, the HeadlessServer struct initializes an AppState (either from session restore or fresh), then enters a main loop that:

1. Drains events from the internal event bus.
2. Processes JSON API requests arriving on herdr.sock.
3. Renders UI updates into an in-memory ratatui Buffer rather than the physical terminal.
4. Streams frames to every attached client via herdr-client.sock using the blocking transport layer defined in src/server/client_transport.rs.

The core structure is defined as:

//! Headless server mode — runs the herdr event loop without a real terminal.
//! …
pub struct HeadlessServer {
    app: app::App,
    client_listener: UnixListener,
    // …
}

Because the server never enters raw mode or reads stdin directly, it can run in environments without a TTY, such as Docker containers or systemd services. Integration tests verifying this behavior reside in tests/server_headless.rs.

When to Use Herdr Headless Server Mode

Choose headless mode for these five specific scenarios:

1. Persistent Background Sessions

Run herdr server as a daemon to keep your workspace alive after closing your terminal. This prevents long-running builds or background agents from terminating when your SSH session disconnects.

2. Thin-Client Usage

Attach lightweight clients that only display the rendered view without processing logic. Use herdr client locally or herdr --remote user@host to connect from another machine, reducing bandwidth and eliminating the need for interactive SSH shells.

3. Automation and Scripting

Interact with the JSON API socket (herdr.sock) to programmatically create panes, execute commands, or query workspace state. This enables CI pipelines to control Herdr without a UI, leveraging the command implementations in src/cli/server.rs.

4. Remote Development

Deploy the server on a remote VM or container while running only the thin client locally. The architecture supports live hand-off between server instances during updates, ensuring zero-downtime deployments.

5. CI and Containerized Environments

Execute Herdr in Docker containers or headless VMs where no real terminal exists. The server restores or creates AppState automatically, making it suitable for integration tests that require terminal UI capabilities without an actual TTY.

Starting and Managing the Headless Server

Start a persistent background session and manage it via CLI commands implemented in src/cli/server.rs:

# Start the headless server in the background

herdr server &

# Attach a local thin client

herdr client

# Connect to a remote server (auto-starts if needed)

herdr --remote user@host.example.com

# Gracefully stop the server

herdr server stop

# Reload configuration without restart

herdr server reload-config

Access the JSON API directly for automation:

# List all panes via the JSON API socket

curl --unix-socket /tmp/herdr.sock -X POST \
  -d '{"jsonrpc":"2.0","method":"PaneList","id":"example"}' \
  http://localhost

Summary

• Headless mode decouples the Herdr event loop from the terminal, creating socket-based APIs in src/server/headless.rs.
• Use it for persistent sessions, remote thin clients, automation scripts, remote development, and CI/container workflows.
• The server creates herdr.sock (JSON API) and herdr-client.sock (binary stream) to communicate with clients.
• Manage the server via herdr server stop, herdr server reload-config, and herdr server live-handoff as implemented in src/cli/server.rs.

Frequently Asked Questions

How does Herdr render a UI without a terminal?

The headless server renders into an in-memory ratatui Buffer rather than stdout. After each frame update, it serializes the buffer contents and streams them over herdr-client.sock to any connected thin clients, which handle the actual display rendering.

Can multiple thin clients connect to one headless server simultaneously?

Yes. The HeadlessServer struct in src/server/headless.rs maintains a client listener that accepts multiple concurrent connections. Each attached client receives the same frame stream, allowing team members to view the same workspace session from different locations.

How do I automate workspace actions without starting the TUI?

Send JSON-RPC requests to the herdr.sock Unix domain socket. The server processes these requests in its event loop, allowing scripts to create panes, run commands, or query state without any user interface interaction.

Is it possible to update the server without killing active sessions?

Yes. Herdr supports live hand-off between server instances. Start a new server process that takes over the existing sockets and AppState, then gracefully shut down the old instance. Use herdr server live-handoff or manually coordinate via the CLI commands defined in src/cli/server.rs.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}