What to configure first when running a local coding agent with herdr

Short answer: before you wire up multi-agent orchestration, settle four things: (1) the work root (workspace and paths), (2) where model and provider settings live, (3) permissions and deny paths, and (4) how the agent receives tasks. If those are fuzzy, more panes will not make the results more trustworthy.

This post relies only on the official herdr docs as of 2026-09-27. Where I could not confirm an exact option name, I describe the setting conceptually and link the relevant official page instead of guessing.

What does herdr actually do?

One-line answer: herdr is a local runtime that runs coding agents in real terminal panes and rolls their state up into one view.

The official Agents page says herdr is built for running more than one coding agent at a time. Each agent lives in a terminal pane with its shell, logs, and prompts intact. herdr detects which panes contain agents and surfaces states such as working, blocked, done, and idle per tab and workspace in the sidebar. Scripts or other agents can also hand out work through the CLI and local socket API.

One point matters a lot: herdr is not the agent that calls the model. It is the layer that runs and tracks agent CLIs such as claude, codex, or cursor inside panes. So split your setup into “herdr settings” and “agent CLI settings.”

What is on the first-settings checklist?

One-line answer: work root, then tools (which agent), then where the model is configured, then keeping secrets out of rules.

Item	Where it is set	What to decide first
Work root	herdr workspace, `[terminal]` in `config.toml`	One repo = one workspace; which directory new panes open in
Tools	Agent CLIs that herdr detects	Start with a single agent; install its integration if available
Model / provider	The agent CLI’s own settings	Model and endpoint per that agent’s docs
Permissions / deny paths	The agent CLI’s settings or a sandbox wrapper	What it may write, what it must never read
Secrets	Environment variables / credential stores	Never inside rules files (AGENTS.md and the like)

1) Work root. The official Concepts page recommends one workspace per active project. Start by running herdr from the project directory. Where new panes, tabs, and workspaces open is controlled by new_cwd in the [terminal] section of the Configuration page; the default follow inherits the source pane or workspace. The config file lives at ~/.config/herdr/config.toml on Linux and macOS, and you can print the full default config with:

herdr --default-config

After editing, apply changes to the running server with herdr server reload-config. If several agents may touch the same repo, set a checkout location in the [worktrees] section and give each agent its own Git worktree.

2) Tools. The Agents page lists supported agents and how their state is detected. Screen detection works out of the box, but agents with lifecycle hooks report state more accurately once their integration is installed. Follow the official Integrations page for per-agent install details.

3) Model and provider. herdr’s configuration has no model endpoint setting. Model choice, local model server address, and API provider are set in each agent CLI’s own config or launch arguments. herdr’s agent start passes everything after -- unchanged to the agent executable, so if you need a model argument, use the exact form from that agent’s documentation.

4) Secrets. Inject API keys through environment variables or the agent’s supported credential mechanism, and keep them out of rules files, prompts, and task briefs. Rules files are text the agent reads every time and may echo into summaries or logs.

Where do permissions and deny paths go?

One-line answer: in the agent CLI’s permission settings and your sandbox, not in herdr. herdr shows what the agent is doing; it does not fence it.

I did not find a file-access restriction setting in the herdr docs. What the Agents page does cover is running agents inside sandbox wrappers: if a wrapper hides the real agent process, herdr cannot detect it, so you set HERDR_AGENT on the wrapper command to name the agent. The documented example:

HERDR_AGENT=claude fence -- claude

So split the permission design like this:

Write and execute permissions: the agent CLI’s approval and sandbox settings. Option names differ per agent, so use that agent’s official docs.
Deny paths: stack paths like .env*, secrets/, and private keys in the agent’s ignore/deny settings and in .gitignore.
herdr’s role: surfacing an approval request as blocked in the sidebar. The docs note that blocked detection is strict, so a new approval screen may show as idle at first.

How do tasks reach the agent?

One-line answer: type into the pane at first, and script only the repeated flows with agent prompt and agent wait.

The Agent automation page separates three primitives: layout, pane, and agent. An agent can only start in an existing shell pane, and agent start never creates or rearranges layout. The documented commands for handing off work:

Goal	Command
Start a supported agent in an existing pane	`herdr agent start <name> --kind <kind> --pane <pane-id>`
Submit a prompt (optionally wait for it)	`herdr agent prompt <name> "<brief>" --wait`
Wait for a specific state	`herdr agent wait <name> --until blocked`
Read the result	`herdr agent read <name>`

The brief matters more than the command. For each task, state the goal, which paths may be touched, the done condition (for example, tests pass), and when to stop and ask. For long output, the docs suggest having the agent write Markdown to a temporary directory and reply with just the file path.

What are the common first-week mistakes?

One-line answer: filesystem scope that is too broad, no deny paths, and vague task briefs cover most of them.

Using your home directory as the work root. If new_cwd is home or you launch herdr from ~, agents can see files outside the repo. Create workspaces at the repo root.
Starting without deny paths. The herdr sidebar shows state, not access control. If the agent CLI’s deny settings are empty, .env is readable.
“Fix this” briefs. Without a done condition, an agent returning to idle tells you nothing about whether it finished. The docs also note that unknown does not prove successful completion.
Several agents in one checkout. Concurrent edits to the same files conflict. Split with worktrees or by role (implement vs. review).
Secrets in rules files. “The key is abc123” is not a rule; it is a leak.
Building orchestration first. If you add helper agents and scripts before one agent runs reliably, it becomes hard to tell where failures come from.

What does a “good enough” starter setup look like?

One-line answer: one repo, one agent, narrow permissions, and one clear brief, run for a week.

In order, using only commands from the official docs and leaving agent-specific options blank on purpose:

cd to the repo root and run herdr. A workspace opens automatically if none exists.
Review the defaults with herdr --default-config and keep new_cwd in [terminal] at the default follow. If you plan to run several agents, also set directory under [worktrees].
In the one agent CLI you will use, finish model/provider and approval/sandbox settings per that agent’s official docs first. Provide API keys only via environment variables.
Keep .gitignore plus the agent’s ignore/deny settings in the repo, and add one line to your rules file: “Do not read denied paths; if a secret is needed, stop and ask.”
Run the agent directly in a pane and confirm the sidebar shows working → blocked → done correctly. If a state looks wrong, check it with herdr agent explain.
Once that flow is stable for a few days, add one helper, such as a reviewer, with agent start and agent prompt --wait.

FAQ

Question	Answer
Can I set a local model address in herdr?	Not in the configuration docs I checked. Configure model and endpoint in the agent CLI running in the pane.
Can I run an agent that is not on the supported list?	Per the docs, it runs normally as a terminal process, but it may lack rich state unless you add an integration or report state over the socket API.
herdr does not detect my agent inside a sandbox.	Set `HERDR_AGENT=<agent>` on the wrapper command. Setting it only inside a VM or container is invisible to herdr.
Do config changes need a restart?	Most apply with `herdr server reload-config`; startup-only settings still need a restart.

Sources

One-line answer: only official herdr documentation, checked as of 2026-09-27.

Herdr documentation — overview
Agents — supported agents, state detection, sandbox wrappers and HERDR_AGENT, blocked detection
Agent automation — layout/pane/agent primitives, agent start, agent prompt, agent wait
Configuration — config.toml location, --default-config, reload-config, [terminal], [worktrees]
Concepts — workspace, tab, and pane model
Related posts: herdr-workspace-setup (workspace layout), agent-deny-paths (deny paths), agent-secrets-in-rules (rules files and secrets)