Working with hosted agents

Use a hosted agent for the same work you would give a local coding agent: implementing a feature, investigating a bug, writing tests, or exploring a repository. You can start from the web UI or your terminal, then return to the conversation as the work progresses.

You need a connected daemon on a machine with the repository and an installed, authenticated agent vendor.

Start from the web UI

Open Agents in the product sidebar. Use Scope to focus on a repository or project. All, Active, and Ended filter the list; active agents are grouped by daemon where available.

1. Choose New agent in the page header, or the launch control on a daemon. On a narrow screen, use +.
2. Select Target Daemon and Agent.
3. Choose Repository Path from that machine’s known repositories, or enter its absolute path.
4. Choose Model and Effort where supported, then enter the initial Prompt and any file attachments.
5. Set Sharing and the available permission controls, then launch.

For example:

Investigate why checkout retries sometimes create duplicate orders. Explain the cause, implement a fix, and run the relevant tests.

A browser launch creates an isolated git worktree on the daemon host. The selected daemon and vendor determine which launch options are enabled. If the dialog asks for a daemon update, update the CLI on that host.

Guide the work

Open the agent’s card to read its live conversation, send another message, or answer a permission request. Ask it to explain a finding, adjust the scope, or check its work just as you would in a local agent session.

Claude and Codex also offer a terminal surface where supported. Other vendors, including hosted Cursor, use a structured conversation. Check waiting and permission states when progress pauses: an agent may need an answer before it can continue.

You can leave the browser and return to the agent later. Use Stop when you intend to end the running agent. Its captured work remains available in Sessions.

Choose permissions

For hosted Codex, Sandbox & approvals defaults to workspace-write and on-request. A capable daemon also offers a read-only sandbox, broader filesystem access, and other approval policies. Choosing never means permission requests will not appear in the web UI.

Claude offers tool and shell permission controls. Other supported vendors offer permission presets, including an ask-everything default. Choose settings that match how you want to supervise the work; requests requiring an answer appear in the agent view.

Vendor authentication or installation problems need to be resolved on the daemon host.

Work together

Choose the audience in Sharing at launch, or change it from the agent view. Share the agent’s page with a teammate so you can follow the same conversation. People with the required access can send messages and answer permission requests; inputs are attributed to their senders.

For a handoff, ask the agent to summarize what it has changed, what it has tested, and what remains. Your teammate can then read that context and continue in the same agent. Coordinate who is directing the next step so you do not send conflicting instructions or stop work someone else is using.

Visibility & sharing explains the available audiences. For a separate agent with a defined role, such as an independent reviewer, use a flow.

Start from the terminal

On macOS or Linux, run a terminal-attached Claude or Codex agent from your repository:

kcap agent start claude
kcap agent start codex --worktree

For kcap agent start, the daemon starts automatically if needed. The CLI uses your current checkout by default; add --worktree to create an isolated checkout under .capacitor/worktrees/. Launching through Agents → New agent in the web UI always creates an isolated worktree.

By default, the agent registers with the server and appears in Agents, so you can continue from the browser. These commands manage agents on the local daemon host; the web UI lets you choose another connected machine.

To start detached, or pass options to the vendor:

kcap agent start claude -d
kcap agent start claude -- --model opus

Press Ctrl-Q, then d to detach from an attached terminal while the agent keeps running. Use its ID to return or stop it:

kcap agent ls
kcap agent attach <agent-id>
kcap agent stop <agent-id>

Use kcap agent start claude --private when you want a local hosted agent without remote registration. Its permission prompts go to the terminal. This does not disable session recording; use capture controls for that.

The kcap agent command group is not supported on Windows in v1.1.1. See the CLI reference for the full command list.

Make repositories available in the picker

The browser’s repository picker lists paths known to the selected daemon. A successful launch remembers its path. You can also register paths on the host:

kcap repos
kcap repos add .
kcap repos add ~/dev/project
kcap repos remove ~/dev/old

Recording a session does not register its repository for hosted launch. The daemon refreshes known repositories when it reconnects or launches work; you can also choose Enter a path manually… in the launch dialog.