pi-herdsman 0.14.0 → 0.14.1

package/docs/guides/container-deployment.md

@@ -1,178 +1,173 @@
 # Container deployment
 
-[Documentation index](../README.md)
+Run Pi Herdsman as a portable SSH-accessible coding-agent environment with Pi, Herdr, developer tools, and persistent state.
 
-The Pi Herdsman container is a portable, self-hosted execution environment for
-coding agents. It packages Pi, herdr, Pi Herdsman, developer tooling, and
-OpenSSH while keeping mutable user state under `/home/herdsman`.
+## Quick start
 
-Use it locally or as a remote coding-agent machine. OpenSSH is the access
-boundary; connect with your own SSH key and use Pi and herdr normally.
+Start:
 
-Pi sessions automatically receive image-owned environment context from
-`/AGENTS.md`, including persistence boundaries, available tool categories, and
-how to install additional tools. User and project context files continue to
-layer normally through Pi's native context-file discovery.
+```sh
+SSH_AUTHORIZED_KEYS="$(cat ~/.ssh/id_ed25519.pub)" docker compose up -d
+```
 
-## Direct SSH
+Connect:
 
-Start the service with a public key authorized for the `herdsman` account:
+```sh
+ssh -p 2222 herdsman@your-host
+```
+
+Herdr opens automatically. Select a workspace and run:
 
 ```sh
-SSH_AUTHORIZED_KEYS="$(cat ~/.ssh/id_ed25519.pub)" docker compose up -d
+pi
 ```
 
-Connect to the host's configured SSH port (2222 by default):
+That's it.
+
+## Add it to Herdr
 
 ```sh
-ssh -p 2222 herdsman@host
+herdr machine add ssh://herdsman@your-host:2222 --label my-herd
 ```
 
-Start or attach to a Herdr session with:
+With an existing `~/.ssh/config` host:
 
 ```sh
-herdr
+herdr machine add my-herd --label my-herd
 ```
 
-SSH password authentication and root login are disabled. On first start,
-`SSH_AUTHORIZED_KEYS` is required to initialize the account's authorized keys.
-The keys are saved in the persistent home volume; changing the environment
-variable later does not replace an existing authorized-keys file. SSH agent
-forwarding remains available, so `ssh -A` can be used when a session needs
-access to private Git repositories without copying private keys into the
-container.
+The remote machine then appears alongside Local in Herdr.
 
-## Herdr Machines
+## Use Tailscale
 
-After normal SSH access works, save the container as a herdr machine from the
-computer running your local herdr client:
+Start with the Tailscale sidecar:
 
 ```sh
-herdr machine add ssh://herdsman@host:2222 --label 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
 ```
 
-For a host already configured in `~/.ssh/config`:
+Connect:
 
 ```sh
-herdr machine add my-herd --label my-herd
+ssh herdsman@pi-herdsman
+```
+
+Add it to Herdr:
+
+```sh
+herdr machine add ssh://herdsman@pi-herdsman --label my-herd
 ```
 
-Each machine keeps its own herdr server, sessions, and running processes.
-Connected machine workspaces and agents appear alongside Local in the same
-herdr window, and disconnecting the client does not stop the remote work.
+Use another hostname:
 
-See the [herdr machine documentation](https://herdr.dev/docs/connecting-machines/)
-for machine management and SSH configuration.
+```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
+```
 
-## Updates
+Tailscale provides networking only. SSH remains normal OpenSSH.
 
-Pull the current image and recreate the service:
+## Update
 
 ```sh
 docker compose pull
 docker compose up -d
 ```
 
-The container replaces immutable software while the named volumes preserve
-`/home/herdsman` and the SSH host identity.
+Persistent state survives container replacement.
 
-## Persistent state
+## Use a host bind mount
 
-The default Compose setup persists two volumes:
+The default Docker-managed volume needs no manual permission setup.
 
-- `/home/herdsman` contains Pi authentication, configuration, sessions and
-  extensions; Herdr configuration, sessions and worktrees; mise-installed
-  tools; npm globals; Git, GitHub and user SSH state; and repositories.
-- `/var/lib/herdsman/ssh` contains the SSH server host key, preserving server
-  identity when the container is replaced.
-
-The image uses its built-in `herdsman` UID and GID by default. For Linux or NAS
-bind mounts owned by a different host account, set `PUID` and `PGID` to the
-directory owner's numeric IDs:
+For a Linux or NAS bind mount, prepare the directory for the UID/GID the
+container will use:
 
 ```sh
-PUID="$(id -u docker-user)" \
-PGID="$(id -g docker-user)" \
-SSH_AUTHORIZED_KEYS="$(cat ~/.ssh/id_ed25519.pub)" \
-docker compose up -d
+PUID=1035
+PGID=65537
+
+mkdir -p ./data/herdsman-home
+sudo chown "$PUID:$PGID" ./data/herdsman-home
+sudo chmod go-w ./data/herdsman-home
 ```
 
-You can also set `PUID` and `PGID` in the Compose `.env` file:
+Set the same IDs in `.env`:
 
 ```dotenv
 PUID=1035
 PGID=65537
 ```
 
-The container remaps the `herdsman` account but does not change ownership of
-the mounted home. Prepare the host directory so the configured IDs can write
-it. Existing volumes are not migrated automatically; startup fails if
-`/home/herdsman` is not writable by the resulting account. Repositories can
-live under the persistent home, for example `~/projects`. Host checkouts can
-be mounted explicitly when needed.
+Create `compose.bind-mount.yaml` to replace the home volume with the host
+directory while keeping the SSH server identity in its named volume:
 
-## Additional tools
+```yaml
+services:
+  herdsman:
+    volumes:
+      - ./data/herdsman-home:/home/herdsman
+      - herdsman-ssh:/var/lib/herdsman/ssh
+```
 
-Install tools into the persistent home with mise:
+Start with both Compose files:
 
 ```sh
-mise use -g uv@latest
-uv run ...
+SSH_AUTHORIZED_KEYS="$(cat ~/.ssh/id_ed25519.pub)" \
+docker compose -f compose.yaml -f compose.bind-mount.yaml up -d
 ```
 
-Mise shims and user-installed tools are available in SSH sessions, including
-non-interactive commands.
+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.
 
-## Tailscale
+## Forward your SSH agent
 
-Tailscale is an optional Compose sidecar. It shares the service network
-namespace; it does not run in the Herdsman container. Start both services with:
+For private Git repositories:
 
 ```sh
-TS_AUTHKEY=... \
-SSH_AUTHORIZED_KEYS="$(cat ~/.ssh/id_ed25519.pub)" \
-docker compose \
-  -f compose.yaml \
-  -f compose.tailscale.yaml \
-  up -d
+ssh -A -p 2222 herdsman@your-host
 ```
 
-Connect over the Tailscale hostname using normal OpenSSH:
+## Install another tool
 
 ```sh
-ssh herdsman@pi-herdsman
+mise use -g uv@latest
 ```
 
-Set `TAILSCALE_HOSTNAME` if a different hostname is desired. The overlay uses
-Tailscale networking, not Tailscale SSH.
-
-## Interactive sessions
+Tools installed with mise persist in the home volume.
 
-Interactive SSH logins automatically open Herdr. This also applies when SSH is
-reached through the optional Tailscale sidecar.
+## What persists?
 
-Exit Herdr to return to the normal shell.
+| Path                    | Contents                                                                          |
+| ----------------------- | --------------------------------------------------------------------------------- |
+| `/home/herdsman`        | Pi and Herdr state, repositories, config, credentials, SSH state, installed tools |
+| `/var/lib/herdsman/ssh` | SSH server identity                                                               |
 
-For interactive Docker access as the normal container user, run:
+Running processes do not survive a container restart.
 
-```sh
-docker exec -it --user herdsman <container> bash
-```
-
-or with Compose:
-
-```sh
-docker compose exec --user herdsman herdsman bash
-```
+## Defaults
 
-Bare `docker exec` uses the container's root user and is intended for
-administrative debugging; it does not automatically open Herdr.
+| Setting            | Default       |
+| ------------------ | ------------- |
+| SSH port           | `2222`        |
+| User               | `herdsman`    |
+| Tailscale hostname | `pi-herdsman` |
+| Password login     | disabled      |
+| Root SSH login     | disabled      |
 
-Non-interactive SSH commands are unaffected.
+`SSH_AUTHORIZED_KEYS` is required only on first start. Existing authorized keys are not overwritten.
 
-## Container restart behavior
+Pi sessions automatically receive the container environment context from `/AGENTS.md`.
 
-Herdr detach and reattach keep processes alive while the container itself
-remains alive. Replacing or restarting the Docker container kills its
-processes. Herdr can restore layout and supported Pi conversations, but
-arbitrary processes do not survive a container restart.
+See the [Herdr machine documentation](https://herdr.dev/docs/connecting-machines/) for machine and SSH configuration.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-herdsman",
-  "version": "0.14.0",
+  "version": "0.14.1",
   "type": "module",
   "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",