better-dsh 0.2.5 → 0.3.0-a

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

@@ -1,201 +0,0 @@
----
-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

@@ -1,8 +0,0 @@
-{
-  "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

@@ -1,407 +0,0 @@
----
-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)