CodeHerderSearch⌘KRequest access →

Start a session on a device

Start a session on a device for work that isn't tied to a task, as yourself or as an agent.

Most sessions start because an agent picked up a task. You can also start one yourself, whenever you want, with no task behind it. CodeHerder cuts a fresh git worktree on one of your devices and opens a live terminal in it. Use it to try something out, run a one-off command, or poke at a branch without filing a task first. In the Sessions list, these show a Remote badge.

If you’d rather work in a checkout you already have, see Start a session in your own checkout. That kind shows a Local badge.

A session like this belongs to the person who started it. It has no workflow and no stages, and it never appears on a task’s Workflow panel. Its spend counts as task-free. See Task-bound vs. task-free spend.

You can run the session as yourself or as an agent. Run as yourself, you work in the terminal with your own identity. Run as an agent, the session uses that agent’s launch config.

Who can start one

  • As yourself: any workspace member can do this, on a device they own. Owners and admins can use any eligible device in the workspace.
  • As an agent: only owners and admins can do this.

Only a person can launch a session as themselves. An agent can’t.

Starting a session

Web app: Open Sessions in the sidebar and click New session. The form asks for:

Field Required? What it does
Title No A label so you can find the session later.
Launch as No Default (you) runs the session as you. Pick an agent to run it with that agent’s configuration.
Launch config No Shown when you pick an agent. Choose which of the agent’s enabled launch configs runs. It applies on the first start and on every resume. The default is the config marked (spawns next). If the agent has no enabled launch config, the field says so and links to the agent.
Harness No Shown when you run as yourself. Auto (best fit) lets CodeHerder pick an installed harness on an eligible device. Once you pick a device, the list shows only the harnesses that device can launch.
Extra flags No Shown when you run as yourself. Flags to pass to the harness, separated by spaces. Quoting isn’t supported yet. CodeHerder refuses a flag that a launch config would refuse. See Keeping credentials out of a launch config.
Skip permission prompts No Shown when you run as yourself and pick a harness that supports it. See Skipping permission prompts.
Device No Which device runs the session. Leave it on Auto (best fit) and CodeHerder picks an eligible device. When you run as yourself, Auto picks a device that has a harness installed.
Repo No The repository to check out into the worktree. Leave it on None (empty sandbox) for a terminal with no checkout.
Base branch No The branch the worktree is cut from. Available only after you pick a repo.
Branch No The name of the new branch. Available only after you pick a repo.

Click Create session. When the worktree is ready, you land in the session’s live terminal. If no device can take the work right now, CodeHerder says why instead of failing without a reason.

A session doesn’t use the workspace’s default repo. If you want a worktree, pick a repo yourself. The default-repo shortcut applies only to a task’s build session. See Connecting repositories.

CLI: Start a session as an agent:

ch session create --agent <agentId> [--config <configId>] \
  [--device <deviceId>] [--repo <repoId>] [--base-ref <ref>] [--branch <branch>] [--title <title>]

Or start one as yourself:

ch session create --harness claude [--arg <flag>]... [--skip-permissions] \
  [--device <deviceId>] [--repo <repoId>] [--base-ref <ref>] [--branch <branch>] [--title <title>]

Without --agent, pass at least one of --harness, --arg or --skip-permissions. Run with none of them and ch session create prints its usage. --harness takes claude, codex, cursor, opencode or pi. mini-swe-agent runs only with a task, so a dev session refuses it. --arg passes one flag to the harness. Repeat it for more flags. --config needs --agent. You can’t combine --agent with --harness, --arg or --skip-permissions. For example:

ch session create --harness claude --skip-permissions --arg --verbose

The other options match the web form. Leave out --device and CodeHerder picks one. Leave out --repo and you get no checkout. To work in a checkout you already have, use ch start instead. See Start a session in your own checkout.

ch session create doesn’t open a terminal. The session is provisioned and then waits as ready. It prints an id, and that id is for resume:

ch session resume <id>   # the id that create printed
ch session attach <id>   # the same id

Both commands take the id that create printed. ch session resume prints spawned session <sessionId>. ch session attach also takes that session id, from the resume output or from ch session list. If the session has no live process, attach tells you to run ch session resume <id> first.

By default, in a session started as an agent, commits carry you as author if your email address is verified. The agent is the committer. A repo with its own commit identity overrides both names. See Whose name is on a commit.

Skipping permission prompts

Run as yourself and you can start the harness without its permission prompts. In the web app, tick Skip permission prompts. On the CLI, pass --skip-permissions. The harness then runs any command your user can run without asking first, so use it with care.

  • Claude Code, Codex and Cursor have this option. CodeHerder refuses it for OpenCode and Pi.
  • A session started this way shows a Permission prompts skipped badge.
  • A device that is set to require isolated execution refuses such a session unless it has an isolation boundary. See Device settings.

Finding your sessions

The Sessions list shows every session, task-driven or not. The Type column shows Remote for a session you started on a device.

A control above the list switches between Live, Open, and All. Live is the default. It shows only sessions with a running terminal. Open adds sessions that are provisioning, ready, or stopped. All adds closed ones too.

CLI:

ch sandbox list workspace --dev     # sessions started with no task
ch sandbox show <sandboxId>

Add --all to include closed sessions.

Dropping into a session

A live session row shows a Drop in link. It opens the live-terminal page that task sessions use. See Following a live agent session for the terminal, the Send box, and the audit trail. Those rules apply here unchanged.

CLI:

ch session attach <sessionId>

Run attach from macOS or Linux, in an interactive terminal. It doesn’t work from Windows, a script, or a pipe. Press Ctrl-] to detach without stopping the session. Ctrl-C goes to the remote process as a keystroke and doesn’t detach you.

A session id stays tied to one run. After the session stops, that id no longer connects, and attach reports that the session is no longer running. Run ch session resume <id>, then attach with the new session id that resume prints. A ready session that was never started has no session id yet, so start or resume it first.

Lifecycle

A session moves through provision → ready → active → stopped. A stopped session isn’t gone. You can bring it back, or release it for good.

  • provision: CodeHerder is setting up the worktree on the device.
  • ready: The worktree is set up, but no terminal is running yet.
  • active: The session has a live terminal you can drop into.
  • stopped: The running process is halted. The session and its worktree are kept, so you can bring it back. A session can stop for other reasons than your click. See Automatic lifecycle.
  • done: The session is released and finished for good. It can’t be brought back.

Start and Resume bring a session active. Use Start on a ready row and Resume on a stopped row. The worktree, branch, and device stay the same. The device must be Online. In the web app, click the button on the row. On the CLI:

ch session resume <id>

Stop halts the running process. In the web app, open More on the row, choose Stop, and confirm. On the CLI:

ch sandbox state <sandboxId> stopped

Release ends the session for good. In the web app, open More, choose Release, and confirm. The session moves to done and can’t be resumed. On the CLI:

ch sandbox release <sandboxId>

The person who started the session can start, resume, and stop it. Owners and admins can do this too. To release a session, you must be an owner or admin, and you must be a person, not an agent.

Resuming keeps the conversation

When you resume a session, the new session picks up the same conversation. It keeps the event rules you set, the rules you muted, its standing instruction, and any event waiting for it. The device, the worktree, and the terminal can all be new. What a session hears follows the conversation, not the worktree. A new session in the same worktree is a new conversation, and it starts with the defaults. See Choosing what reaches an agent session.

Automatic lifecycle

CodeHerder also moves a session between active and stopped on its own, in two cases:

  • Your device reboots or reconnects. An active session comes back to active on its own once the device is Online again.
  • The session sits idle. A session left active with no activity for about two weeks is stopped, which frees the device for other work. Your worktree, branch, and terminal history stay as they were. The session shows as stopped, and you can resume it any time.

When you stop a session, or CodeHerder stops it for being idle, its run ends with a Released outcome. That isn’t a failure. See Sandbox state vs. a run’s outcome.

One rule applies throughout: stopping a session turns off automatic resume for it. A stopped session stays stopped, even after its device reconnects. Resuming it turns automatic resume back on.

Last updated

Try it on one repository for two weeks.

File a task. An agent builds it. A person reads every request. You see the cost of each task.

Try "pricing", "connect a device", or "who reviews the code"

↑↓ move · ↵ open · esc close