# When to Use Herdr Headless Server Mode: 5 Key Scenarios

> Discover when to use Herdr headless server mode for background sessions, remote access, and API automation. Optimize your Herdr deployments with these 5 key scenarios.

- Repository: [Can Celik/herdr](https://github.com/ogulcancelik/herdr)
- Tags: how-to-guide
- Published: 2026-05-31

---

**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`](https://github.com/ogulcancelik/herdr/blob/main/src/main.rs), where the application checks for the `server` argument:

```rust
// 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`](https://github.com/ogulcancelik/herdr/blob/main/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`](https://github.com/ogulcancelik/herdr/blob/main/src/server/client_transport.rs).

The core structure is defined as:

```rust
//! 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`](https://github.com/ogulcancelik/herdr/blob/main/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`](https://github.com/ogulcancelik/herdr/blob/main/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`](https://github.com/ogulcancelik/herdr/blob/main/src/cli/server.rs):

```bash

# 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:

```bash

# 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`](https://github.com/ogulcancelik/herdr/blob/main/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`](https://github.com/ogulcancelik/herdr/blob/main/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`](https://github.com/ogulcancelik/herdr/blob/main/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`](https://github.com/ogulcancelik/herdr/blob/main/src/cli/server.rs).