Agent Harnesses

A harness is the agent runtime that answers when you chat with CommandLane. The built-in CommandLane agent is always available, and you can also install external harnesses — such as Hermes Agent or OpenClaw — directly from CommandLane. You pick a harness from a catalog and CommandLane downloads, installs, launches, supervises, and connects it for you. No terminal, no manual host/port entry.

Once a harness is installed, you create one or more agents on top of it. An agent is a saved profile — a name, working directory, model, system prompt, and tool permissions — layered on the same installed runtime. Switching agents changes how the harness behaves without reinstalling anything.

Whichever agent is active, the chat experience stays the same: streaming responses, tool call cards, approval prompts, and cancellation all work through CommandLane's common event protocol.

Two levels: runtimes and agents

CommandLane separates what you install from how you use it:

• Runtime — the installed harness binary: its type (Hermes, OpenClaw, …), version, install location, and the port it listens on. You install a runtime once.
• Agent — a named profile on a runtime: working directory, model, system prompt, and tool permissions. You can create several agents on one runtime and switch between them instantly.

This means you can run, for example, a "Docs writer" agent and a "Codebase refactor" agent on the same Hermes install, each with its own working directory and system prompt.

Opening the Harnesses page

1. Open the dashboard (Ctrl+Shift+D by default)
2. Click the Harnesses tab

The page has three sections:

• Available — harnesses you can install, shown as catalog cards with a one-click Install button.
• Installed — runtimes already on your machine, with their status (running / stopped) and controls to start, stop, update, or uninstall.
• Agents — the profiles on each installed runtime, where you create, edit, and switch agents.

The built-in CommandLane agent always appears and is marked Built-in; it needs no install. The agent currently answering in chat is marked Active.

Installing a harness

In the Available section, click Install on a harness card. CommandLane then:

1. Checks prerequisites. Some harnesses need a runtime already present — for example, OpenClaw requires Node.js (v22.22+, v24.15+, or v25.9+). If a prerequisite is missing, CommandLane shows a guided message telling you what to install and where to get it, instead of failing mid-install.
2. Shows a consent screen. Because harness installers run code on your machine (an official install script or an npm package), CommandLane discloses exactly what will run and where it lands before anything executes. You approve before install begins.
3. Installs. Progress is shown live (stage and percentage) as the harness downloads and installs.
4. Configures. CommandLane writes the harness-side configuration it needs before first launch. For Hermes this generates an API-server key and enables its local OpenAI-compatible API server in ~/.hermes/.env; for OpenClaw it writes a local gateway token to ~/.openclaw/openclaw.json. This is done for you; there is nothing to edit by hand, and the generated key/token is stored in your OS keychain, not in the config file.
5. Launches and connects. CommandLane starts the harness on an automatically chosen free port, waits for its health check to pass, and connects. When the card moves to Installed / Running, you are ready to create an agent.

Where harnesses are installed

Some harnesses install into their own fixed location rather than inside CommandLane's data folder. Hermes installs to %LOCALAPPDATA%\hermes on Windows (and ~/.hermes on macOS/Linux) via its official install script; OpenClaw installs as a global npm package. CommandLane records the install location so it can launch, update, and uninstall the harness cleanly.

If a harness is already running

If you already run a harness yourself (for example, an OpenClaw daemon you installed manually), CommandLane detects it on its port and offers to connect to that running instance instead of installing or spawning a second copy. Your existing setup is never overwritten.

Creating and switching agents

Once a runtime is installed and running, open its Agents section and click Create agent:

Field	Notes
Name	How the agent appears in the switcher
Working directory	The folder the agent operates in
Model	Which model the agent uses (if the harness supports per-agent models)
System prompt	Instructions that shape the agent's behavior
Permissions	Which tool actions the agent may take

Fields a particular harness cannot honor are marked as unsupported in the editor rather than silently ignored — so you always know what a profile actually controls. In practice Hermes honors a per-agent model (and gives each agent its own isolated session), while OpenClaw currently isolates only the session — its gateway does not accept a per-agent working directory, model, system prompt, or permission set, so those fields show as unsupported on an OpenClaw agent.

To switch the active agent, click Set active on any agent card, or use the harness dropdown in the capture window chat header (Ctrl+Shift+H). From that point, chat messages go to the selected agent. Your selection persists across restarts.

Starting, stopping, and updating a runtime

In the Installed section, each runtime card shows whether it is running and offers:

• Start / Stop — CommandLane launches the harness as a supervised child process and stops it on request. If the harness crashes, CommandLane restarts it automatically with backoff. When you quit CommandLane, all harness processes are stopped — no orphans left behind.
• Update — installs a newer version via the same recipe path the harness was installed with. Harness updates are independent of CommandLane's own auto-update.
• Uninstall — removes the runtime. Because some harnesses install outside CommandLane's data folder, uninstall follows the harness's own removal steps. If agents still reference the runtime, CommandLane prompts before removing them.

Cancellation and approvals

These work the same regardless of the active agent:

• Cancel — Stop a response mid-turn from the chat window. The harness is told to stop, and the turn ends as cancelled.
• Approvals — When a harness wants to run a sensitive action, an approval prompt appears inline in the conversation with a risk indicator. Approve or deny it there; your answer is routed back to the harness that asked.

Hermes and risky tools

Hermes runs tools on its own server, so CommandLane can only warn about risky tools after they execute — it cannot block them. When you connect a Hermes agent, CommandLane surfaces this explicitly and asks you to acknowledge it. If you decline, CommandLane refuses to connect rather than accept that risk. Any tool the agent runs then appears in the conversation as an advisory notice after the fact, not as a blocking approval prompt.

Advanced: connect to an existing server

If you run a harness yourself and prefer to manage its lifecycle by hand, open Advanced → Connect to existing server on the Harnesses page. This is the classic manual form:

Field	Notes
Type	Hermes Agent (SSE) or OpenClaw (WebSocket)
Host	Defaults to 127.0.0.1
Port	Defaults to 8642 (Hermes) or 18789 (OpenClaw)
Auth token	Optional; stored securely in the OS keychain, never in config files

CommandLane connects to the server as-is and does not download, launch, or supervise it. This path is unchanged from earlier versions, so existing manual setups keep working.