pi-herdsman 0.13.2 → 0.14.1

package/README.md

@@ -7,15 +7,21 @@
 [![Platforms](https://img.shields.io/badge/platforms-Linux%20%7C%20macOS%20%7C%20Windows-blue)](https://github.com/boadij/pi-herdsman/actions/workflows/validate.yml)
 [![License](https://img.shields.io/npm/l/pi-herdsman)](LICENSE)
 
-**Asynchronous [Pi](https://github.com/earendil-works/pi) subagents and agent fleet orchestration with nested delegation, parallel execution, and supervision in [herdr](https://github.com/herdrdev/herdr).**
+**Asynchronous [Pi](https://github.com/earendil-works/pi) subagents and agent fleet orchestration for parallel coding agents with nested delegation, background work, and supervision in [herdr](https://github.com/herdrdev/herdr).**
 
 Keep the conversation. Delegate the work.
 
-Pi Herdsman is a Pi extension for asynchronous subagents. Delegate coding
-tasks to managed background agents running in independent Pi sessions while
-the lead conversation stays interactive. Run agents in parallel, nest
-delegation, steer active agents, route questions and results back to their
-owning agent, and supervise multiple leads through one coordinated hierarchy.
+Pi Herdsman is a Pi extension for asynchronous subagents and multi-agent
+coding. Delegate coding tasks to managed background agents running in
+independent Pi sessions while the lead conversation stays interactive. Run
+coding agents in parallel, nest delegation, steer active agents, route
+questions and results back to their owning agent, and supervise multiple leads
+through one coordinated hierarchy.
+
+Use it in an existing Pi/herdr setup or deploy the SSH-ready container as a
+portable remote coding-agent environment. [herdr Machines](https://herdr.dev/docs/connecting-machines/)
+can bring local and remote workspaces and agents into one herdr window over
+normal SSH.
 
 Pi Herdsman calls its managed subagents **agents**.
 
@@ -34,22 +40,14 @@ agents, and a delegation-enabled agent may own permitted agents of its own.
 Agent definitions, models, tools, extensions, and development process remain up
 to you.
 
-Chief supervision is separate from ownership:
-
-```text
-chief
-  ├─ herd A / lead A
-  │  └─ agents...
-  └─ herd B / lead B
-     └─ agents...
-```
-
 ## Demo
 
 ![Pi Herdsman delegating a coding task to an asynchronous subagent while the lead Pi session remains interactive.](docs/assets/demo.gif)
 
 ## Install
 
+### Existing Pi / herdr
+
 ```sh
 pi install npm:pi-herdsman
 herdr integration install pi
@@ -67,6 +65,22 @@ Then run Pi in the Herdr pane:
 pi
 ```
 
+### Docker / remote machine
+
+For a self-contained, SSH-ready remote coding-agent environment, see
+[Container deployment](docs/guides/container-deployment.md).
+
+Once normal SSH access works, the same container can be saved as a herdr
+machine:
+
+```sh
+herdr machine add ssh://herdsman@host:2222 --label my-herd
+```
+
+A host defined in normal SSH configuration can be used directly instead.
+
+## Try it
+
 Ask Pi normally:
 
 ```text
@@ -97,6 +111,16 @@ To supervise independent leads across the current herdr runtime, use:
 /chief
 ```
 
+Chief supervision is separate from ownership:
+
+```text
+chief
+  ├─ herd A / lead A
+  │  └─ agents...
+  └─ herd B / lead B
+     └─ agents...
+```
+
 Leave chief mode with:
 
 ```text
@@ -158,7 +182,8 @@ tools, extensions, skills, and instructions.
 - Pi `>=0.87.0 <0.88.0` (supported)
 - Node `>=22.19.0`
 
-CI validates Node 22.19.0 with the locked dependency set.
+Package CI validates the minimum supported Node 22.19.0 runtime. The container
+separately ships and validates Node 26.
 
 Install or refresh the herdr Pi integration:
 

package/docs/README.md

@@ -33,6 +33,12 @@ Continue with:
 - [Agent-definition schema](reference/agent-definition-schema.md)
 - [Recovery](guides/recovery.md)
 
+### Deploy Pi Herdsman in a container
+
+Use the canonical [container deployment guide](guides/container-deployment.md)
+for the SSH-ready Docker image, persistent state, updates, and optional
+Tailscale networking.
+
 ### Coordinate through agent APIs
 
 Start with [Agent coordination API](agent-api.md).
@@ -71,31 +77,32 @@ before choosing the material relevant to them.
 
 ## Canonical ownership
 
-| Subject                               | Canonical page                                                  |
-| ------------------------------------- | --------------------------------------------------------------- |
-| Human UI first use                    | [Getting started](getting-started.md)                           |
-| Agent/API first use                   | [Agent coordination API](agent-api.md)                          |
-| Asynchronous orchestration            | [Lifecycle](concepts/lifecycle.md)                              |
-| Agent identity                        | [Agents and identity](concepts/agents.md)                       |
-| State transitions                     | [Lifecycle](concepts/lifecycle.md)                              |
-| Delegation model                      | [Delegation](concepts/delegation.md)                            |
-| Creating definitions                  | [Agent definitions](guides/agent-definitions.md)                |
-| Overrides and prompt composition      | [Customizing bundled agents](guides/customizing-agents.md)      |
-| `files`, body references, and results | [Handoffs and files](guides/handoffs.md)                        |
-| Operator recovery                     | [Recovery](guides/recovery.md)                                  |
-| `agent` request contract              | [`agent` API](reference/agent.md)                               |
-| `ask_owner` contract                  | [`ask_owner` API](reference/ask-owner.md)                       |
-| Pi Herdsman supervision concept       | [Supervision](concepts/supervision.md)                          |
-| Chief and staff tools                 | [Supervision reference](reference/supervision.md)               |
-| Frontmatter fields                    | [Agent-definition schema](reference/agent-definition-schema.md) |
-| Public agent states                   | [Agent states](reference/agent-states.md)                       |
-| `/agents` human commands              | [`/agents` commands](reference/commands.md)                     |
-| Settings                              | [Configuration](reference/configuration.md)                     |
-| TUI agent widget                      | [Status widget](reference/status-widget.md)                     |
-| Error categories                      | [Errors](reference/errors.md)                                   |
-| Repository checks                     | [Validation](development/validation.md)                         |
-| Live acceptance                       | [Smoke testing](development/smoke-testing.md)                   |
-| Instruction and interface design     | [Instruction and interface design](development/instruction-interface-design.md) |
+| Subject                               | Canonical page                                                                  |
+| ------------------------------------- | ------------------------------------------------------------------------------- |
+| Human UI first use                    | [Getting started](getting-started.md)                                           |
+| Container deployment                  | [Container deployment](guides/container-deployment.md)                          |
+| Agent/API first use                   | [Agent coordination API](agent-api.md)                                          |
+| Asynchronous orchestration            | [Lifecycle](concepts/lifecycle.md)                                              |
+| Agent identity                        | [Agents and identity](concepts/agents.md)                                       |
+| State transitions                     | [Lifecycle](concepts/lifecycle.md)                                              |
+| Delegation model                      | [Delegation](concepts/delegation.md)                                            |
+| Creating definitions                  | [Agent definitions](guides/agent-definitions.md)                                |
+| Overrides and prompt composition      | [Customizing bundled agents](guides/customizing-agents.md)                      |
+| `files`, body references, and results | [Handoffs and files](guides/handoffs.md)                                        |
+| Operator recovery                     | [Recovery](guides/recovery.md)                                                  |
+| `agent` request contract              | [`agent` API](reference/agent.md)                                               |
+| `ask_owner` contract                  | [`ask_owner` API](reference/ask-owner.md)                                       |
+| Pi Herdsman supervision concept       | [Supervision](concepts/supervision.md)                                          |
+| Chief and staff tools                 | [Supervision reference](reference/supervision.md)                               |
+| Frontmatter fields                    | [Agent-definition schema](reference/agent-definition-schema.md)                 |
+| Public agent states                   | [Agent states](reference/agent-states.md)                                       |
+| `/agents` human commands              | [`/agents` commands](reference/commands.md)                                     |
+| Settings                              | [Configuration](reference/configuration.md)                                     |
+| TUI agent widget                      | [Status widget](reference/status-widget.md)                                     |
+| Error categories                      | [Errors](reference/errors.md)                                                   |
+| Repository checks                     | [Validation](development/validation.md)                                         |
+| Live acceptance                       | [Smoke testing](development/smoke-testing.md)                                   |
+| Instruction and interface design      | [Instruction and interface design](development/instruction-interface-design.md) |
 
 When another page needs one of these subjects, it summarizes only enough to
 establish context and links to the canonical page instead of restating the full

package/docs/getting-started.md

@@ -21,6 +21,9 @@ pi install npm:pi-herdsman
 herdr integration install pi
 ```
 
+For an SSH-ready Docker deployment instead, see the
+[container deployment guide](guides/container-deployment.md).
+
 ## 2. Start Herdr and Pi
 
 Start Herdr in your project:

package/docs/guides/container-deployment.md

@@ -0,0 +1,173 @@
+# Container deployment
+
+Run Pi Herdsman as a portable SSH-accessible coding-agent environment with Pi, Herdr, developer tools, and persistent state.
+
+## Quick start
+
+Start:
+
+```sh
+SSH_AUTHORIZED_KEYS="$(cat ~/.ssh/id_ed25519.pub)" docker compose up -d
+```
+
+Connect:
+
+```sh
+ssh -p 2222 herdsman@your-host
+```
+
+Herdr opens automatically. Select a workspace and run:
+
+```sh
+pi
+```
+
+That's it.
+
+## Add it to Herdr
+
+```sh
+herdr machine add ssh://herdsman@your-host:2222 --label my-herd
+```
+
+With an existing `~/.ssh/config` host:
+
+```sh
+herdr machine add my-herd --label my-herd
+```
+
+The remote machine then appears alongside Local in Herdr.
+
+## Use Tailscale
+
+Start with the Tailscale sidecar:
+
+```sh
+TS_AUTHKEY=tskey-auth-... \
+SSH_AUTHORIZED_KEYS="$(cat ~/.ssh/id_ed25519.pub)" \
+docker compose \
+  -f compose.yaml \
+  -f compose.tailscale.yaml \
+  up -d
+```
+
+Connect:
+
+```sh
+ssh herdsman@pi-herdsman
+```
+
+Add it to Herdr:
+
+```sh
+herdr machine add ssh://herdsman@pi-herdsman --label my-herd
+```
+
+Use another hostname:
+
+```sh
+TAILSCALE_HOSTNAME=my-herd \
+TS_AUTHKEY=tskey-auth-... \
+SSH_AUTHORIZED_KEYS="$(cat ~/.ssh/id_ed25519.pub)" \
+docker compose \
+  -f compose.yaml \
+  -f compose.tailscale.yaml \
+  up -d
+```
+
+Tailscale provides networking only. SSH remains normal OpenSSH.
+
+## Update
+
+```sh
+docker compose pull
+docker compose up -d
+```
+
+Persistent state survives container replacement.
+
+## Use a host bind mount
+
+The default Docker-managed volume needs no manual permission setup.
+
+For a Linux or NAS bind mount, prepare the directory for the UID/GID the
+container will use:
+
+```sh
+PUID=1035
+PGID=65537
+
+mkdir -p ./data/herdsman-home
+sudo chown "$PUID:$PGID" ./data/herdsman-home
+sudo chmod go-w ./data/herdsman-home
+```
+
+Set the same IDs in `.env`:
+
+```dotenv
+PUID=1035
+PGID=65537
+```
+
+Create `compose.bind-mount.yaml` to replace the home volume with the host
+directory while keeping the SSH server identity in its named volume:
+
+```yaml
+services:
+  herdsman:
+    volumes:
+      - ./data/herdsman-home:/home/herdsman
+      - herdsman-ssh:/var/lib/herdsman/ssh
+```
+
+Start with both Compose files:
+
+```sh
+SSH_AUTHORIZED_KEYS="$(cat ~/.ssh/id_ed25519.pub)" \
+docker compose -f compose.yaml -f compose.bind-mount.yaml up -d
+```
+
+OpenSSH requires the home directory to be owned by root or the login user and
+not writable by group or others. The container validates this at startup but
+does not change ownership or permissions of host bind mounts.
+
+## Forward your SSH agent
+
+For private Git repositories:
+
+```sh
+ssh -A -p 2222 herdsman@your-host
+```
+
+## Install another tool
+
+```sh
+mise use -g uv@latest
+```
+
+Tools installed with mise persist in the home volume.
+
+## What persists?
+
+| Path                    | Contents                                                                          |
+| ----------------------- | --------------------------------------------------------------------------------- |
+| `/home/herdsman`        | Pi and Herdr state, repositories, config, credentials, SSH state, installed tools |
+| `/var/lib/herdsman/ssh` | SSH server identity                                                               |
+
+Running processes do not survive a container restart.
+
+## Defaults
+
+| Setting            | Default       |
+| ------------------ | ------------- |
+| SSH port           | `2222`        |
+| User               | `herdsman`    |
+| Tailscale hostname | `pi-herdsman` |
+| Password login     | disabled      |
+| Root SSH login     | disabled      |
+
+`SSH_AUTHORIZED_KEYS` is required only on first start. Existing authorized keys are not overwritten.
+
+Pi sessions automatically receive the container environment context from `/AGENTS.md`.
+
+See the [Herdr machine documentation](https://herdr.dev/docs/connecting-machines/) for machine and SSH configuration.

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "pi-herdsman",
-  "version": "0.13.2",
+  "version": "0.14.1",
   "type": "module",
-  "description": "Asynchronous Pi subagents and agent fleet orchestration with nested delegation, parallel execution, and supervision in herdr.",
+  "description": "Asynchronous Pi subagents and agent fleet orchestration for parallel coding agents with nested delegation, background work, and supervision in herdr.",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -22,10 +22,12 @@
     "agents",
     "ai-agents",
     "coding-agents",
+    "coding-agent-orchestration",
     "multi-agent",
     "multi-agent-coding",
     "agent-fleet",
     "parallel-agents",
+    "parallel-coding-agents",
     "background-agents",
     "nested-agents",
     "agent-orchestration",