Herdr

Herdr lets you run and watch over several AI coding agents — like Claude Code, Codex, Droid and GitHub Copilot CLI — right on your own servers, from your phone, tablet or Mac. The agents do their work on the server; Caret is your window into them. You can see at a glance which one is waiting on you, which is still working, and which has finished — and step in the moment an agent needs an answer.

This feature is built on herdr, an open-source "agent multiplexer" that runs on your server — think of it as a tmux or zellij that understands agents. herdr runs the agents and keeps track of what each one is doing; Caret connects to it over your normal SSH connection and gives you a touch-friendly view. As always, there is no Caret cloud in between — the app talks straight to your server.

What you can do

  • Run several agents at once, each in its own workspace, tab or pane.
  • See every agent's live state in one list — blocked, working, done or idle — so nothing waits on you unnoticed.
  • Jump straight to the agent that needs you and type your answer or approval.
  • Walk away. The agents keep running on the server even after you close Caret or lose signal. Come back later and pick up exactly where they were.
  • Get notified when an agent becomes blocked or finishes.

Before you start

Because the agents run on your server, a little one-time setup happens there. Caret points you through it:

  1. A server you can reach over SSH. Add it in Caret the usual way — host, port and username — and make sure it connects.

  2. herdr installed on that server. It is a single open-source binary. Sign in to the server — for example from Caret's own terminal — and install it with one command:

    curl -fsSL https://herdr.dev/install.sh | sh

    (Homebrew users can run brew install herdr instead.) You only do this once per server.

  3. At least one coding agent. Install an agent's command-line tool on the server — Claude Code, Codex, Droid, GitHub Copilot CLI and more are supported. Caret helps you get these set up. Each agent signs in to its own provider with your account or key (Anthropic for Claude Code, OpenAI for Codex, and so on) — that part is between you and that provider.

Starting your agents

  1. Connect to the server in Caret and open Herdr.
  2. Caret starts herdr on that server, or reconnects to one already running, and shows your workspaces.
  3. Open a workspace and launch an agent — for example, start Claude Code in a pane and give it a task the way you normally would.
  4. Add as many agents as you like, each in its own pane or workspace. They all run side by side.

Reading the agent list

The list shows each agent's state at a glance:

  • 🔴 Blocked — the agent needs your input or approval.
  • 🟡 Working — it is actively running.
  • 🔵 Done — it finished, and you have not looked yet.
  • 🟢 Idle — finished and seen.

A workspace takes on the most urgent state of the agents inside it, so you can scan the whole list and go straight to whatever is waiting on you:

Workspaces
──────────────────────────────────
▾ api-server              🔴 blocked
    claude code           🔴 blocked
    codex                 🟡 working
▾ web-frontend            🔵 done
    copilot cli           🔵 done
▾ infra                   🟢 idle
    droid                 🟢 idle

(An example layout — yours shows your own servers and agents.)

You always see each agent's real terminal, not a re-rendered copy, so what you read in Caret is exactly what the agent printed.

Your agents keep running when you leave

Because the agents live on the server, they do not stop when you put your phone away or the connection drops. Close Caret and come back later, switch from your phone to your Mac, or even reattach from a plain terminal on your computer with herdr — the agents are right where you left them, still working or still waiting. This is the same session persistence herdr gives any terminal.

Staying in control

The agents are powerful — they run real commands on a real server — so a few habits keep you safe:

  • They run as your logged-in user, over your normal SSH connection. An agent can only do what that account is allowed to do. Connect with a limited account when you want a tighter leash.
  • Read what an agent proposes before you approve it, especially anything that deletes, overwrites, installs or restarts. Most agents stop and ask before risky steps — that is exactly when an agent shows as 🔴 blocked, waiting for you.
  • Try it on a non-critical server first while you get a feel for how it works.
  • Keep a record. Turn on session recording and you will have a full log of a session, saved on your device.

Privacy

  • Caret connects straight to your server over SSH. There is no Caret cloud in between, and nothing about your agents or their work is sent to us.
  • herdr is open-source software running on your own server — not a Caret service.
  • Each coding agent talks to its own AI provider (for example Anthropic for Claude Code, or OpenAI for Codex) using the account or key you set up on the server, under that provider's privacy policy — never through us. Only run agents on work you are comfortable sharing with the provider behind them.

For how Caret itself handles your data, see the Privacy Policy.

When something goes wrong

  • Herdr won't open, or the list is empty — make sure herdr is installed on the server and that you can run herdr there over SSH. If the SSH connection itself is failing, fix that first; see Can't connect to a server.
  • An agent doesn't appear, or its state looks wrong — check that its command-line tool is actually installed and running on the server. herdr recognizes the common agents automatically; a tool it doesn't know still runs, but may not report a state.
  • An agent errors about its key, login or quota — that is between the agent and its provider. Check the agent's own setup on the server and your account standing with that provider.
  • The connection dropped mid-session — no harm done: the agents keep running on the server. Just reopen the server in Caret to reattach.

Still need help?

Tell us your device and its operating system version, the app version (Settings → About), and what you were doing when the problem happened.