Documentation

Guides, tutorials, and frequently asked questions

Run a Coding Agent on Your Server from Your Phone | YoloShell

Frequently asked questions

Where do the coding agents actually run?
On the remote machine running Herdr. They must be installed there — YoloShell is the iOS client that drives them, not the runtime, and it does not include any AI service subscription of its own.
What do I need before I can start one?
SSH access to a remote machine with Herdr running, plus the agent CLI already installed on that machine. Start it in a pane that is sitting at a shell prompt; any first-run setup or approval happens in that terminal.
Can I watch an agent work without interfering?
Yes, and that is the default posture. The panel attaches read-only, and typing is refused until you explicitly take control. Taking control asks for confirmation and warns that another controller is disconnected — the remote task itself keeps running either way.
How many agents can I start?
One per pane. The New agent form only offers panes that do not already have an agent detected in them, so create a new pane first if every pane in that workspace is busy. Twenty-four agent types are listed, from Claude and Codex through Gemini, Cursor and Copilot.
What happens when the connection drops while an agent is working?
The agent keeps running on the server. YoloShell retries the connection every few seconds, and on reconnect it restores which pane you were in, whether you were observing or controlling it, and which agent completions you had already seen.
Does YoloShell also work without Herdr?
Yes. SSH, Mosh, tmux and VNC all work independently — Herdr adds the workspace and agent layer on top of a client that stands on its own.

The short answer

The premise is worth stating first because it is easy to misread: the agent runs on the remote machine, not on your phone. Your phone is the control surface.

YoloShell connects over SSH to a machine running Herdr and puts the whole remote session in one panel — workspaces, tabs, panes and agents, switchable in a compact list. From there you can create a workspace, split off a pane, or start a supported agent such as Claude Code or Codex in a pane sitting at a shell prompt. You see each agent's real status, read its output without touching it, and take control only when you mean to.

The prerequisites are not a formality: SSH access, Herdr running server-side, and the agent CLI already installed there. YoloShell is on the App Store, iOS 17 or later.

Why you are looking for this

The real problem is not "I want a terminal on my phone." You have five of those. It is that a coding agent is a process you can no longer see, and on a phone-sized screen a hidden process looks exactly like a hung one.

You have three or four agents across a few workspaces on a build box: one refactoring, one blocked on a permission prompt, one finished ten minutes ago while you were on the train. The shell you happen to be attached to shows you exactly one of them. So the questions that matter are: which is working, which is stuck asking for input, which already finished, and can I look without disturbing it? A generic SSH client answers none of those — it gives you a stream of characters and leaves you to remember which pane you were in.

What the panel actually is

The button beside the session title opens a switcher with two modes: Agents and Workspaces.

  • Agents mode lists only panes Herdr has detected an agent in, grouped under their workspace, each row showing the title, the agent kind, and its status.
  • Workspaces mode gives you the full shape — workspaces, the tabs inside them as collapsible groups, and the panes inside those.
  • A Needs attention toggle in Agents mode filters to the two statuses that want you: Needs input and Done — the view that answers "what happened while I was away" in one tap.

Search matches pane title, pane name, agent kind and workspace name, so refactor worker narrows across all four at once.

Statuses map to five values — Working, Needs input, Done, Idle, Unknown — plus a Starting… state for an agent launched but not yet reporting in. A pane with no agent in it reads Terminal.

One detail matters more than it sounds: a finished agent keeps reading Done until you have actually looked at it. The "seen" state is tracked per terminal and persisted, so relaunching the app does not re-mark yesterday's completions as unread — and a completion you did not read is not silently lost.

Observe first, control on purpose

Attaching to a terminal is not the same as being handed the keyboard, and YoloShell treats them as different modes.

Read-only is the default. You get the rendered stream — the agent's output as it scrolls — and your keystrokes are refused. The status line reads Read-only so you know why the keyboard is inert.

Taking control is deliberate, behind a confirmation: "Take control of this terminal? Another controller will be disconnected; the remote task will keep running." That wording is the design in one sentence — your takeover costs another client its seat, and costs the agent nothing.

Three follow-on behaviours make that mode real rather than cosmetic:

  • Handing back is one action ("Switch to read-only"), which releases the attachment cleanly instead of leaving a dead controller attached.
  • If the remote closes the stream because another client attached or took over, you are dropped back to read-only automatically rather than shown a dead terminal.
  • Resize is mode-aware. While you are controlling, the pane is resized in place; while observing, there is no input channel to carry the resize, so the read-only stream re-attaches at the new size.

Creating things: workspace, pane, agent

The + menu offers three operations, and the forms are stricter than they look — a good thing, because each request is validated before it leaves the phone.

New workspace takes an optional label and working directory. A directory must be absolute — starting with / — or blank, which uses Herdr's own default.

New pane splits the selected pane right or down, beside it, in the same tab, with the same directory rules.

New agent asks for two things: a name and a type. The name must begin with a lowercase letter and use only lowercase letters, digits, underscores and hyphens, up to 32 characters. The type is one of 24 agents — Claude, Codex, Gemini, Cursor, Copilot, OpenCode, Cline, Devin, Amp, Qwen, Kimi, Kiro, Droid, Grok, Hermes, Kilo, Letta, Qoder CLI, Mastra Code, Muse, Maki, OMP, AGY and Pi. These are the agents Herdr can start; YoloShell ships none of them.

The pane picker is subtler than it looks: it only offers panes with no agent already in them, so you are never asked to stack two agents on one terminal.

And the honest part. If the remote says the agent is not ready, or the start times out, the app does not declare failure — it says the agent may need setup or approval and offers to open the pane, because that is usually what happened: the CLI printed a first-run prompt or a trust confirmation. If the connection dropped mid-request, it tells you the operation may have completed and to check before retrying, rather than inviting a duplicate.

What happens when the connection breaks

Worth knowing precisely: an unattended agent is exactly when a dropped connection causes damage.

Nothing on the phone would stop. The agent keeps working on the server through a disconnect — see keeping a session alive when Wi-Fi drops for the network layer.

The panel side: YoloShell subscribes to Herdr's event stream for workspace, tab and pane changes — created, closed, renamed, moved, exited — plus agent status changes per pane, and separately re-reads the full snapshot on a health interval. If the event stream is lost or the pane set has changed, it resubscribes and re-reads from scratch rather than drifting. A failed request retries after a few seconds, and every request is bounded by a timeout, so a black-holed connection surfaces as a failure rather than an endless spinner. A changed SSH host key gets its own warning and no auto-retry — the right behaviour for anything that could mean a new machine.

On reconnect, saved state is scoped to the endpoint — host, port, user, session name and Herdr executable — and restored only if all of those still match: which pane was selected, whether you were observing or controlling it, and which completions you had already seen. Change the session name in the profile and the app discards the stale state rather than attaching you to the wrong terminal.

What YoloShell does differently

Most remote-terminal apps treat a coding agent as "a program you happen to be running." YoloShell's Herdr panel treats it as an inventory with states:

  • One list for everything — every workspace, tab, pane and agent switchable from a phone-sized panel, with a Needs-attention filter for the statuses worth interrupting your day for.
  • Observation as the default and control as a confirmed action, because an agent mid-edit does not want your stray keystrokes and another controller may be watching it.
  • Done-until-acknowledged status, so a completion cannot disappear behind a reconnect.
  • Honest failure copy. An empty session, a pane that vanished, a stream that closed, a changed host key and an unconfirmed creation each get their own message rather than a generic "something went wrong."

The limits, stated plainly:

  • Herdr must already be running on the server, and the agent CLI installed there. YoloShell includes no AI service subscription — you are driving tools you already pay for, on a machine you already own.
  • The panel needs a remote machine reachable by SSH — a server-side feature, not a local one.
  • Herdr integration was verified against Herdr 0.9.3. Per-profile executable and session name fields let you point at a non-default binary or a named session, but a substantially different Herdr release is not something the app can promise.
  • The free tier limits what you can point it at: one concurrent session on any device, three hosts and two SSH keys. Pro lifts those and adds iPad multi-tab, tmux control mode and extra palettes. The Herdr panel is not itself a Pro gate, but a second simultaneous agent session is.

The decision

You need this if you run coding agents on a server you own and want to know what they are doing from a phone. You do not need it — and will not enjoy it — if your agents run on your laptop, or if there is no Herdr session yet to attach to.

If it does apply: verify Herdr is running on the server, install the agent CLI, create a Herdr profile with the session and executable your setup uses, then open the panel and turn on Needs attention.