Difference Between Herdr Monolithic Mode and Server-Client Mode

TLDR: Herdr operates in two distinct execution architectures: a monolithic mode (--no-session) that bundles the UI, API server, and background tasks into a single process, and a server-client mode (default) that spawns a persistent background daemon to which thin clients attach, enabling session persistence and multi-client collaboration.

The ogulcancelik/herdr repository implements these two modes through fundamentally different code paths in src/main.rs and src/server/autodetect.rs. Understanding the difference between Herdr monolithic mode and server-client mode helps you select the appropriate strategy for headless environments, debugging scenarios, or persistent remote workspaces.

Process Architecture and Socket Management

The primary distinction lies in how processes are spawned and how the API socket is handled.

Monolithic Mode (--no-session)

In monolithic mode, the application runs as a single process that owns the UI rendering, the API socket, and all background tasks simultaneously. No separate server daemon is spawned. According to the source code in src/main.rs, when the --no-session flag is present, the application executes a monolithic block that calls api::start_server_with_capabilities directly within the same process. No client socket is created because there is no separate client-server relationship—everything operates within one memory space.

Server-Client Mode (Default)

When running in the default mode, the CLI first checks for an existing server daemon via the auto-detect logic. If none exists, it spawns a detached server process and then attaches a thin client process to it. The server creates a dedicated client socket (client_socket_path) that thin clients connect to. The implementation in src/client/mod.rs handles this connection, rendering frames and forwarding input to the server while the server manages the actual workspace state.

Session Handling and Persistence

Session persistence behavior diverges significantly between the two modes.

In monolithic mode, no persistent session state is saved or restored because there is no long-running server process. When you detach from the application, it simply exits completely, as implemented in src/app/state.rs. This makes the mode suitable for one-off invocations where state persistence is unnecessary.

In server-client mode, the server manages all session state independently of the client processes. A client can detach and re-attach without losing workspace context, and multiple clients can simultaneously connect to the same server to share a workspace. This architecture supports scenarios like remote SSH attachment or multi-terminal collaboration.

Background Updates and Process Lifecycle

The update mechanisms also differ by architecture. In monolithic mode, background update checks still run (unless explicitly disabled), but they execute within the same process as the UI. Consequently, the UI cannot be restarted without exiting the entire application.

In server-client mode, the detached server runs its own background update loop. Because the server persists independently of client connections, it can restart itself to apply updates without terminating attached clients. Clients automatically reconnect to the upgraded server instance.

Launch Logic and Code Pathways

The decision between these modes follows a specific execution flow in the source code:

1. Argument Parsing: src/main.rs parses command-line arguments. If --no-session is present, the boolean no_session becomes true.
2. Auto-Detect Path: If no_session is false, the program calls server::autodetect::auto_detect_launch() in src/server/autodetect.rs. This function checks for an existing server, spawns one if needed, and returns control to the client logic.
3. Monolithic Path: If no_session is true, the monolithic block in src/main.rs executes directly, starting the API server, configuring panic handling, and running the UI loop—all within the same process.

Practical Usage Examples

Run Herdr in monolithic mode for single-process execution without a background daemon:

herdr --no-session

Run Herdr in the default server-client mode, which auto-detects or spawns a server:

herdr

Explicitly start a server daemon for remote attaches or persistent background operation:

herdr server

Attach a thin client to an already running server (automatic with the default herdr command):

herdr

Summary

• Monolithic mode (--no-session) runs as a single process in src/main.rs without spawning a server daemon, suitable for CI environments and debugging.
• Server-client mode (default) uses src/server/autodetect.rs to manage a persistent server and thin clients via src/client/mod.rs.
• Monolithic mode lacks session persistence and exits on detach, while server-client mode supports multiple clients and re-attachment.
• Server-client mode enables background updates that restart the server without killing clients, unlike the single-process monolithic approach.
• Key files defining these behaviors are src/main.rs, src/server/autodetect.rs, and src/client/mod.rs.

Frequently Asked Questions

When should I use Herdr's monolithic mode instead of server-client mode?

Use monolithic mode when you need quick, one-off invocations or when running in environments where background daemons are undesirable, such as CI pipelines, containerized runs, or when debugging the core UI loop. The --no-session flag ensures no persistent processes remain after the application exits, making it ideal for ephemeral environments.

How does Herdr detect whether to spawn a new server or attach to an existing one?

The detection logic resides in src/server/autodetect.rs. When you run herdr without the --no-session flag, the code calls server::autodetect::auto_detect_launch(), which checks for an existing server daemon. If none is found, it automatically spawns a detached server process before returning control to the client attachment logic.

Can I switch from monolithic mode to server-client mode without losing my workspace?

No. Monolithic mode does not persist session state because it lacks a long-running server. When you exit a monolithic instance, the workspace state is lost according to the implementation in src/app/state.rs. To preserve your workspace across sessions, you must use server-client mode from the start, which maintains state in the persistent server process.

Where does the server store client socket information in server-client mode?

The server creates a client socket at a path defined by client_socket_path, which thin clients use to establish connections. The client implementation in src/client/mod.rs connects to this socket to render frames and forward input, while the server manages the actual workspace state independently of the client processes.

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