Hosted agents

A “hosted agent” is a Claude Code or Codex instance launched from the dashboard rather than your terminal. Your machine runs a daemon that the tenant talks to over SignalR; the daemon spawns the agent in an isolated git worktree, captures the session, and surfaces a live terminal in the dashboard. Multiple teammates with view access can watch it run and send input.

This page covers daemon setup, launching from the dashboard, and what to expect when more than one person is driving the same session.

Why hosted agents

A hosted agent earns its keep when:

You want to start work from your phone, or from any browser, without opening a terminal.
You want to hand off a session to a teammate mid-run (they take over input from the dashboard).
You want to run several agents in parallel without juggling terminal tabs.
You want the work to happen in an isolated worktree, so your main checkout stays untouched.

For solo work in a familiar repo, running claude locally is faster. The hosted path adds value once collaboration or remoting is in play.

Run a daemon

kapacitor daemon start                  # foreground, --name defaults to your OS username
kapacitor daemon start -d               # background (daemonize)
kapacitor daemon start --name laptop -d # named — run multiple daemons on the same machine

A running daemon advertises itself to your tenant. The dashboard’s launch dialog shows every daemon you have available, plus which vendors (Claude / Codex) each one can spawn.

kapacitor daemon status                 # list all running daemons
kapacitor daemon status --name laptop
kapacitor daemon stop --name laptop
kapacitor daemon stop --yes             # stop all, no prompt
kapacitor daemon doctor                 # diagnose lock-file state
kapacitor daemon doctor --clean         # also remove stale lock/pid files

Each daemon holds an exclusive flock on ~/.config/kapacitor/daemons/<name>.lock for its entire lifetime, including hard kills. Two daemons with the same name on the same machine collide and the second exits with code 2; two daemons with different names run side-by-side without issue.

Configure agent binaries

The daemon needs to know where the Claude and Codex CLIs live. Defaults resolve claude and codex via PATH; override only if you need a specific binary:

kapacitor config set daemon.claude_path /opt/claude/bin/claude
kapacitor config set daemon.codex_path  /opt/codex/bin/codex

Key	Default	Description
`daemon.claude_path`	`"claude"`	Path to the Claude CLI binary.
`daemon.codex_path`	`"codex"`	Path to the Codex CLI binary.

At startup the daemon probes both paths and advertises only the vendors it can actually spawn. The launch dialog hides whichever isn’t available, so an unconfigured vendor isn’t a tripping hazard — it just doesn’t appear.

You can override either at runtime via environment (takes precedence over the profile):

KAPACITOR_CLAUDE_PATH=/opt/claude/bin/claude kapacitor daemon
KAPACITOR_CODEX_PATH=/opt/codex/bin/codex   kapacitor daemon

Launch from the dashboard

Switch to the Agents tab. Each running daemon gets a Launch button. Click it, pick:

Vendor — Claude or Codex (only available vendors are shown)
Repo — picks from your known repos (see below)
Branch / starting point — defaults to the repo’s default branch
Initial prompt — optional; if blank, the agent opens at a prompt

…and the daemon checks out an isolated worktree, spawns the agent, and streams a terminal back to the dashboard.

Known repos

The launch dialog only lets you pick from repos the daemon has previously seen. Repos are added automatically the first time an agent runs against them; you can also manage them by hand:

kapacitor repos                    # list known repos (sorted by last used)
kapacitor repos add .              # add current directory
kapacitor repos add ~/dev/project
kapacitor repos remove ~/dev/old

The list is persisted to ~/.config/kapacitor/repos.json and reported to the server when the daemon connects.

Multi-user input

Anyone with view access on a hosted agent can send input to it — text, special keys, permission answers, even stop. Input is per-agent FIFO and attributed to the sender, so the session record shows who typed what.

Practically: if you and a teammate are both watching a hosted Claude session, you can both type into the same prompt. The transcript records each message with the sender’s GitHub identity. Useful for pair-debugging or for handing off mid-flight.

Codex hosted agents

Codex hosted agents need the Codex hook surface installed (the setup wizard handles this; if you skipped, run kapacitor plugin install --codex). Once installed, the daemon starts Codex with:

--sandbox workspace-write — Codex can edit files in the agent’s worktree but escalates anything else.
--ask-for-approval on-request — sensitive operations bubble up to the dashboard’s permission bridge.

PR review for hosted Codex agents isn’t supported yet — it works for sessions Codex produced locally with the kapacitor hooks installed, just not for sessions launched from the dashboard’s hosted-agent launcher. The sandbox and approval-mode selectors in the launch dialog are also a planned follow-up; for now the daemon defaults shown above apply to every hosted Codex session.

Graceful shutdown

When the daemon stops — Ctrl-C, a kapacitor daemon stop, a clean reboot — it tries graceful /exit on every active hosted session first, then calls EndAgentSession so the session record reflects an ended state even on SIGTERM, crash, or detach. You shouldn’t see “running forever” zombie sessions from clean daemon shutdowns.

The dashboard — the Agents tab where you launch.
CLI > Configuration & profiles — full key reference for daemon.* settings.