better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/egress/network-isolation.md

@@ -0,0 +1,201 @@
+---
+title: "Network Egress Isolation (Docker)"
+description: "Segment Docker networks so the agent sandbox can only reach allowlisted hosts"
+---
+
+# Network Egress Isolation for Docker Deployments
+
+When running Hermes inside Docker, the default `network_mode: host` gives the
+agent process unrestricted outbound network access. This guide shows how to
+segment traffic so the agent core can only reach the services it needs, while
+blocking arbitrary outbound connections.
+
+This is primarily a defense against prompt injection attacks that attempt to
+exfiltrate data via `curl`, `wget`, or raw HTTP from tool-generated shell
+commands.
+
+## Threat Model
+
+The Hermes [SECURITY.md](https://github.com/NousResearch/hermes-agent/blob/main/SECURITY.md) §2 defines the trust model. The
+terminal backend is the primary execution boundary. However, when running with
+`network_mode: host`, any command the agent executes can reach any endpoint on
+the network, including external ones.
+
+Network egress isolation adds a second layer: even if a malicious command
+executes inside the container, it cannot reach endpoints outside the
+explicitly allowlisted set.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────┐
+│  Docker Network: internal (no internet)     │
+│                                             │
+│   ┌──────────────┐   ┌──────────────────┐   │
+│   │ hermes-agent │   │ hermes-dashboard │   │
+│   └──────┬───────┘   └────────┬─────────┘   │
+│          │                    │              │
+│          ▼                    │              │
+│   ┌──────────────┐            │              │
+│   │ hermes-gtw   │◄───────────┘              │
+│   └──────┬───────┘                           │
+│          │                                   │
+└──────────┼───────────────────────────────────┘
+           │
+┌──────────┼───────────────────────────────────┐
+│  Docker Network: egress (internet-capable)   │
+│          │                                   │
+│          ▼                                   │
+│   ┌─────────────────┐                        │
+│   │ egress-proxy     │──► allowlisted hosts  │
+│   │ (squid / envoy)  │                       │
+│   └─────────────────┘                        │
+└──────────────────────────────────────────────┘
+```
+
+Two Docker networks:
+
+- **`internal`** — no default route, no internet access. The agent, dashboard,
+  and gateway run here.
+- **`egress`** — has internet access. Only services that need to reach external
+  APIs are attached to this network.
+
+The gateway service is dual-homed (attached to both networks) so it can
+receive inbound messages from Telegram/Slack/etc. and forward them to the
+agent on the internal network.
+
+## Compose Configuration
+
+Override the default `docker-compose.yml` with a
+`docker-compose.override.yml`:
+
+```yaml
+# docker-compose.override.yml
+# Network egress isolation for production deployments.
+#
+# Usage:
+#   HERMES_UID=$(id -u) HERMES_GID=$(id -g) docker compose up -d
+#
+# This overrides network_mode: host with isolated Docker networks.
+
+networks:
+  internal:
+    driver: bridge
+    internal: true          # no default route, no internet
+  egress:
+    driver: bridge
+
+services:
+  gateway:
+    network_mode: ""        # clear the host-mode default
+    networks:
+      - internal
+      - egress              # needs outbound for Telegram, LLM APIs
+    ports:
+      - "127.0.0.1:9119:9119"   # dashboard proxy, localhost only
+
+  dashboard:
+    network_mode: ""
+    networks:
+      - internal            # internal only, no egress needed
+```
+
+### With an Egress Proxy (Recommended)
+
+For tighter control, route all outbound traffic through an HTTP proxy with
+an explicit allowlist:
+
+```yaml
+# docker-compose.override.yml (with egress proxy)
+
+networks:
+  internal:
+    driver: bridge
+    internal: true
+  egress:
+    driver: bridge
+
+services:
+  gateway:
+    network_mode: ""
+    networks:
+      - internal
+      - egress
+    environment:
+      - HTTP_PROXY=http://egress-proxy:3128
+      - HTTPS_PROXY=http://egress-proxy:3128
+      - NO_PROXY=hermes,hermes-dashboard,localhost
+
+  dashboard:
+    network_mode: ""
+    networks:
+      - internal
+
+  egress-proxy:
+    image: ubuntu/squid:6.10-24.04_edge
+    networks:
+      - egress
+    volumes:
+      - ./config/squid-allowlist.conf:/etc/squid/conf.d/allowlist.conf:ro
+    restart: unless-stopped
+```
+
+Example `config/squid-allowlist.conf`:
+
+```
+# Only allow HTTPS CONNECT to these hosts
+acl allowed_hosts dstdomain api.openai.com
+acl allowed_hosts dstdomain api.anthropic.com
+acl allowed_hosts dstdomain openrouter.ai
+acl allowed_hosts dstdomain generativelanguage.googleapis.com
+acl allowed_hosts dstdomain api.telegram.org
+acl allowed_hosts dstdomain api.github.com
+acl allowed_hosts dstdomain discord.com
+
+http_access allow CONNECT allowed_hosts
+http_access deny all
+```
+
+Adjust the allowlist to match your LLM provider and messaging platform.
+
+## Validating the Setup
+
+After bringing up the stack, verify isolation:
+
+```bash
+# From the agent container: this should FAIL (no egress)
+docker compose exec gateway \
+  curl -sf --max-time 5 https://example.com && echo "FAIL: egress not blocked" || echo "OK: egress blocked"
+
+# From the agent container: this should SUCCEED (internal network)
+docker compose exec gateway \
+  curl -sf --max-time 5 http://hermes-dashboard:9119/health && echo "OK: internal reachable" || echo "FAIL"
+
+# If using egress proxy: this should SUCCEED (allowlisted)
+docker compose exec gateway \
+  curl -sf --max-time 5 --proxy http://egress-proxy:3128 https://api.openai.com/v1/models && echo "OK" || echo "FAIL"
+```
+
+## Limitations
+
+- **DNS resolution:** The `internal` network can still resolve external DNS
+  names unless you also run a local DNS resolver that blocks external queries.
+  For most threat models this is acceptable since DNS resolution alone does not
+  exfiltrate meaningful data.
+
+- **Not a substitute for sandbox backends:** This guide isolates the agent
+  *container's* network. If you use the default local terminal backend, tool
+  commands execute inside the same container. For stronger isolation, combine
+  network segmentation with a sandboxed terminal backend (Docker, Modal,
+  Daytona).
+
+- **Platform adapters need egress:** The gateway service needs outbound access
+  to reach messaging platform APIs. If you add new platform adapters, add their
+  API endpoints to the proxy allowlist.
+
+## Related
+
+- [SECURITY.md](https://github.com/NousResearch/hermes-agent/blob/main/SECURITY.md) — Hermes trust model and vulnerability reporting
+- [Docker](/user-guide/docker) — running Hermes in a container
+- [Egress proxy](iron-proxy.md) — credential-injection firewall for the sandbox
+- [docker-compose.yml](https://github.com/NousResearch/hermes-agent/blob/main/docker-compose.yml) — default compose configuration

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/features/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Features",
+  "position": 4,
+  "link": {
+    "type": "generated-index",
+    "description": "Explore the powerful features of Hermes Agent."
+  }
+}

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/features/acp.md

@@ -0,0 +1,407 @@
+---
+sidebar_position: 11
+title: "ACP Host Integration"
+description: "Use Hermes Agent inside ACP-compatible editors and collaboration platforms"
+---
+
+# ACP Host Integration
+
+Hermes Agent can run as an ACP server, letting ACP-compatible hosts talk to
+Hermes over stdio. Editors can render:
+
+- chat messages
+- tool activity
+- file diffs
+- terminal commands
+- approval prompts
+- streamed thinking / response chunks
+
+Other hosts can use the same protocol to route collaboration events into
+Hermes. ACP is a good fit when you want Hermes to keep its existing identity,
+provider setup, memory, skills, and tools while another application owns the
+conversation transport.
+
+## What Hermes exposes in ACP mode
+
+Hermes runs with a curated `hermes-acp` toolset designed for editor workflows. It includes:
+
+- file tools: `read_file`, `write_file`, `patch`, `search_files`
+- terminal tools: `terminal`, `process`
+- web/browser tools
+- memory, todo, session search
+- skills
+- execute_code and delegate_task
+- vision
+
+It intentionally excludes things that do not fit typical editor UX, such as messaging delivery and cronjob management.
+
+## Installation
+
+Install Hermes normally, then add the ACP extra from the install checkout:
+
+```bash
+cd ~/.hermes/hermes-agent && uv pip install -e '.[acp]'
+```
+
+This installs the `agent-client-protocol` dependency and enables:
+
+- `hermes acp`
+- `hermes-acp`
+- `python -m acp_adapter`
+
+## Launching the ACP server
+
+Any of the following starts Hermes in ACP mode:
+
+```bash
+hermes acp
+```
+
+```bash
+hermes-acp
+```
+
+```bash
+python -m acp_adapter
+```
+
+Hermes logs to stderr so stdout remains reserved for ACP JSON-RPC traffic.
+
+For non-interactive checks:
+
+```bash
+hermes acp --version
+hermes acp --check
+```
+
+### Browser tools (optional)
+
+Browser tools (`browser_navigate`, `browser_click`, etc.) depend on the
+`agent-browser` npm package and Chromium, which aren't part of the Python
+wheel. Install them with:
+
+```bash
+hermes acp --setup-browser           # interactive (prompts before ~400 MB download)
+hermes acp --setup-browser --yes     # accept the download non-interactively
+```
+
+This is the standalone command. The terminal-auth flow (`hermes acp --setup`) also offers the browser bootstrap as a follow-up question after model selection, so most users never need to run `--setup-browser` directly.
+
+What it does:
+
+- Installs Node.js 26 into `~/.hermes/node/` if missing
+- `npm install -g agent-browser @askjo/camofox-browser` into that prefix (no sudo needed — `npm`'s `--prefix` points at the user-writable Hermes-managed Node)
+- Installs Playwright Chromium, or uses a detected system Chrome/Chromium when available
+
+The bootstrap is idempotent — re-running it is fast and skips work that's already done.
+
+## Host setup
+
+### Buzz channels (relay bridge)
+
+[Buzz](https://github.com/block/buzz) is a Nostr-based collaboration platform
+for people and agents. Its `buzz-acp` harness connects Buzz channels to any ACP
+agent over stdio:
+
+```text
+Buzz relay <-- WebSocket --> buzz-acp <-- ACP over stdio --> Hermes Agent
+```
+
+This is a transport integration, not a second Hermes installation. The
+subprocess launched by `buzz-acp` uses the same Hermes configuration,
+credentials, memory, skills, and state as `hermes` on that host.
+
+(This is distinct from [Buzz Desktop's managed runtime](#buzz-desktop), which
+spawns Hermes locally as a preset harness. The relay bridge is for joining Buzz
+*channels* as an agent identity, typically on a server.)
+
+Prerequisites:
+
+- Complete the ACP installation and `hermes acp --check` above.
+- Build `buzz-acp` and the `buzz` CLI from the
+  [Buzz repository](https://github.com/block/buzz)
+  (`cargo build --release -p buzz-acp`).
+- Mint a dedicated Nostr keypair for Hermes (`buzz-admin generate-key`) and
+  register it as a relay member (`buzz-admin add-member`). Every agent needs
+  its own identity — do not reuse a human keypair.
+- Add that identity to the intended Buzz channels.
+
+Start a bridge with:
+
+```bash
+export BUZZ_RELAY_URL="wss://community.example.com"
+export BUZZ_PRIVATE_KEY="..."
+export BUZZ_API_TOKEN="..."
+export BUZZ_ACP_AGENT_COMMAND="hermes"
+export BUZZ_ACP_AGENT_ARGS="acp"
+
+buzz-acp
+```
+
+`BUZZ_API_TOKEN` is needed only when the relay enforces token authentication.
+Do not commit or paste the private key or API token.
+
+For a persistent server deployment, run `buzz-acp` under a service manager as
+the same operating-system user that owns the intended Hermes home. Setup,
+key generation, channel discovery, and per-agent options are documented in the
+[buzz-acp README](https://github.com/block/buzz/tree/main/crates/buzz-acp).
+
+The bridge discovers every Buzz channel where the Hermes identity is a member
+and automatically subscribes when it is added to another channel. Buzz channel
+membership therefore remains the access boundary; Hermes does not need a
+separate channel list in its own configuration.
+
+To expose Hermes ACP activity in the owner's Buzz Desktop, add:
+
+```bash
+export BUZZ_ACP_RELAY_OBSERVER="true"
+```
+
+This publishes encrypted kind `24200` observer frames addressed to the agent's
+owner (Buzz's NIP-AO). Desktop renders the live lifecycle, tool, response, and
+usage stream in the agent's **Activity log**. The relay treats these frames as
+ephemeral, so Desktop must be online before the turn starts; its local observer
+archive is the durable owner-side history.
+
+Headless bridges answer ACP permission requests themselves because no editor
+is present to show approval dialogs — see
+[Keep Buzz agents owner-only](#keep-buzz-agents-owner-only). Treat the bridge
+as privileged automation: use a dedicated operating-system account, restrict
+which Buzz users can prompt the agent (`buzz-acp` supports an owner-only
+respond gate via `BUZZ_ACP_AGENT_OWNER`), and grant membership only in channels
+where Hermes is expected to work.
+
+### VS Code
+
+Install the [ACP Client](https://marketplace.visualstudio.com/items?itemName=formulahendry.acp-client) extension.
+
+To connect:
+
+1. Open the ACP Client panel from the Activity Bar.
+2. Select **Hermes Agent** from the built-in agent list.
+3. Connect and start chatting.
+
+If you want to define Hermes manually, add it through VS Code settings under `acp.agents`:
+
+```json
+{
+  "acp.agents": {
+    "Hermes Agent": {
+      "command": "hermes",
+      "args": ["acp"]
+    }
+  }
+}
+```
+
+### Zed
+
+Configure Hermes as a custom agent server in Zed settings:
+
+1. Open the Agent Panel.
+2. Add a custom agent server with the following configuration:
+
+```json
+{
+  "agent_servers": {
+    "hermes-agent": {
+      "type": "custom",
+      "command": "hermes",
+      "args": ["acp"]
+    }
+  }
+}
+```
+
+3. Start a new Hermes external-agent thread.
+
+Prerequisites:
+
+- Configure Hermes provider credentials first with `hermes model`, or set them in `~/.hermes/.env` / `~/.hermes/config.yaml`.
+
+### JetBrains
+
+Use an ACP-compatible plugin and point it at `hermes acp` or `hermes-acp`.
+
+### Buzz Desktop
+
+[Buzz](https://github.com/block/buzz) ships Hermes Agent as a preset runtime.
+With Hermes installed the normal way, Buzz discovers it automatically —
+open **Settings → Runtimes** and Hermes appears under your runtimes.
+
+If discovery fails (older installs), make sure the ACP launcher resolves on a
+login-shell PATH:
+
+```bash
+command -v hermes-acp || command -v hermes
+```
+
+Recent installs write both `hermes` and `hermes-acp` launchers into
+`~/.local/bin`; running `hermes update` adds the `hermes-acp` launcher to
+older installs. As a manual fallback, configure Buzz's agent command as
+`hermes` with args `["acp"]`.
+
+#### Model picker
+
+Buzz Desktop (v0.5.1+) renders Hermes' full model menu in the agent's runtime
+settings. The list comes from Hermes itself over ACP: it shows every model
+from providers you have authenticated in Hermes (the same inventory behind
+`hermes model` and the `/model` command), so a model missing from the menu
+means its provider has no credentials configured on the Hermes side.
+
+Entry IDs take the form `provider:model` (e.g. `openrouter:z-ai/glm-5.1`), or
+`custom:<name>:<model>` for custom OpenAI-compatible endpoints defined in
+`config.yaml`. Picking a model applies to that agent's session; it does not
+change your Hermes-wide default — use `hermes model` for that.
+
+#### Keep Buzz agents owner-only
+
+Buzz creates every agent with **Who can talk to this agent** set to `Owner only`.
+Leave it there when the runtime is Hermes.
+
+Two behaviors combine on this path. The `hermes-acp` toolset includes `terminal`
+and `execute_code`, and Buzz's ACP bridge answers Hermes' permission requests
+itself with `allow_once` rather than surfacing them. A Hermes agent in Buzz
+therefore runs shell commands on the host without prompting. I asked one to run
+`rm -rf` against a scratch directory and it deleted it, no prompt anywhere.
+
+Selecting `Anyone` hands that same shell access to every author who can reach
+the channel. Buzz does not warn when you pick it.
+
+Neither of the obvious mitigations works today:
+
+- `approvals.mode: manual` does make Hermes raise the permission request, but
+  Buzz auto-approves it and the command still runs.
+- `platform_toolsets.acp` does not narrow the ACP toolset, so it cannot be used
+  to drop `terminal`.
+
+`!shutdown` from the owner stops the agent in any mode, and Buzz ignores that
+command from everyone else.
+
+## Configuration and credentials
+
+ACP mode uses the same Hermes configuration as the CLI:
+
+- `~/.hermes/.env`
+- `~/.hermes/config.yaml`
+- `~/.hermes/skills/`
+- `~/.hermes/state.db`
+
+Provider resolution uses Hermes' normal runtime resolver, so ACP inherits the currently configured provider and credentials. Hermes also advertises a terminal auth method (`--setup`) for first-run ACP clients; this opens Hermes' interactive model/provider setup.
+
+## Host integration
+
+These variables are set by an **ACP host process** (an editor or another agent
+harness) on the Hermes subprocess it spawns. They are not user configuration —
+do not set them by hand in `.env` or `config.yaml`.
+
+| Variable | Value | Effect |
+|----------|-------|--------|
+| `HERMES_ACP_SKIP_CONFIGURED_MCP` | `1` | Skip starting the **globally configured** MCP servers from `config.yaml` before the ACP JSON-RPC loop begins. |
+
+Hermes normally starts every MCP server configured in `config.yaml` before it
+enters the ACP JSON-RPC loop. A host that owns MCP itself — passing the
+session's servers explicitly through `session/new` — does not need that global
+startup, and an unrelated slow or interactive MCP server would otherwise delay
+`initialize`. Setting the marker to exactly `1` lets such a host skip it.
+
+Only the global `config.yaml` discovery is skipped. **MCP servers supplied by
+the ACP session through `session/new` are still registered**, so a host loses
+no capability it asked for. Any other value (unset, empty, `0`, `false`) keeps
+the default behavior, so an unrelated truthy-looking string cannot silently
+disable MCP.
+
+## Session behavior
+
+ACP sessions are tracked by the ACP adapter's in-memory session manager while the server is running.
+
+Each session stores:
+
+- session ID
+- working directory
+- selected model
+- current conversation history
+- cancel event
+
+Conversations are persisted to Hermes' session database and can be listed, loaded,
+resumed, or forked after the ACP server restarts. Opening a new session without a
+prompt keeps it in memory only: model-discovery probes do not create empty history
+rows. A nonempty fork is persisted immediately, and existing session metadata can
+still be updated even when its current history is empty.
+
+Existing empty rows from older versions are not automatically deleted. An open ACP
+row does not prove its client has disconnected. After closing the relevant editor
+sessions, inspect unwanted rows with `hermes sessions show <id>` and remove only
+confirmed unwanted sessions with `hermes sessions delete <id>`.
+
+## Working directory behavior
+
+ACP sessions bind the editor's cwd to the Hermes task ID so file and terminal tools run relative to the editor workspace, not the server process cwd.
+
+## Approvals
+
+Dangerous terminal commands can be routed back to the editor as approval prompts. ACP approval options are simpler than the CLI flow:
+
+- allow once
+- allow always
+- deny
+
+Whether you actually see a prompt is up to the host. A host is free to answer the
+request programmatically instead of showing it to you, in which case these
+options exist on the wire but never reach a human. Buzz Desktop does this, so
+treat that path as unattended execution regardless of your `approvals` setting.
+
+On timeout or error, the approval bridge denies the request.
+
+### Session-scoped edit auto-approval
+
+ACP exposes a third tier between *allow once* and *allow always*: **Allow for session**. Picking it from the editor's permission prompt records the approval inside the current ACP session only — every subsequent matching command in that session goes through without prompting, but a new ACP session (or restarting the editor) resets the slate and re-prompts the first time.
+
+| Option | Editor label | Scope | Persisted across restarts |
+|---|---|---|---|
+| `allow_once` | Allow once | This one tool call | No |
+| `allow_session` | Allow for session | All matching calls in this ACP session | No — cleared when the session ends |
+| `allow_always` | Allow always | All future sessions | Yes (written to the Hermes permanent allowlist) |
+| `deny` | Deny | This one tool call | No |
+
+`allow_session` is the right default for an editor workflow where you trust an agent for the duration of a task but don't want to grant a long-lived allowlist entry. The safety trade-off is straightforward: the broader the scope, the less the editor will interrupt you, and the more damage a misbehaving agent (or prompt injection) can do before you notice. Start with `allow_once` for unfamiliar commands; promote to `allow_session` once you've seen the agent run the same pattern correctly a few times; reserve `allow_always` for truly idempotent commands you trust forever (e.g. `git status`).
+
+The ACP bridge maps these options onto Hermes' internal approval semantics — `allow_always` writes a permanent allowlist entry the same way the CLI does, while `allow_session` only affects the in-process approval cache for the current ACP session.
+
+## Troubleshooting
+
+### ACP agent does not appear in the editor
+
+Check:
+
+- For manual/local development, verify the host command points to `hermes acp`.
+- Hermes is installed and on your PATH.
+- The ACP extra is installed (`cd ~/.hermes/hermes-agent && uv pip install -e '.[acp]'`).
+
+### ACP starts but immediately errors
+
+Try these checks:
+
+```bash
+hermes acp --version
+hermes acp --check
+hermes doctor
+hermes status
+```
+
+### Missing credentials
+
+ACP mode uses Hermes' existing provider setup. Configure credentials with:
+
+```bash
+hermes model
+```
+
+or by editing `~/.hermes/.env`. The terminal auth flow (`hermes acp --setup`) can also trigger the interactive provider/model setup.
+
+## See also
+
+- [Buzz ACP harness](https://github.com/block/buzz/tree/main/crates/buzz-acp)
+- [ACP Internals](../../developer-guide/acp-internals.md)
+- [Provider Runtime Resolution](../../developer-guide/provider-runtime.md)
+- [Tools Runtime](../../developer-guide/tools-runtime.md)