feat(container): add agent profile abstraction for hermes support

Introduce AgentProfile so container managers (Docker, Apple Container,
tart) stay agent-agnostic. Each profile carries the env file path,
secrets-reload command, and MCP wiring command for one agent runtime.

OpenclawProfile preserves existing behavior (default). HermesProfile
targets nousresearch/hermes-agent: writes phantom tokens to
~/.hermes/.env and patches mcp_servers in ~/.hermes/config.yaml via a
small embedded python+pyyaml script. Hermes has no in-place reload;
ReloadCmd is nil and ReloadSecrets logs a notice.

Selectable via --agent (or SLUICE_AGENT_PROFILE).

Author: nnemirovsky

CLAUDE.md

@@ -116,7 +116,24 @@ Two credential types: `static` (default) for API keys and `oauth` for OAuth acce
 
 `sluice binding update --destination` also updates the paired auto-created allow rule (tagged `binding-add:<credential>` or `cred-add:<credential>`) so the new destination is not orphaned. If no paired rule exists (e.g. because it was manually removed), the binding destination is still updated and a warning is printed. No fallback rule is created so an operator's intentional removal is not silently reverted. `--env-var` on binding update can be used to change or clear the env var name after the initial binding was created.
 
-Runtime flags: `--mcp-base-url` sets the external URL the agent uses to reach sluice's MCP gateway (e.g. `http://sluice:3000`). This is added to `SelfBypass` so sluice does not policy-check its own MCP traffic. Defaults to deriving from `--health-addr`.
+Runtime flags: `--mcp-base-url` sets the external URL the agent uses to reach sluice's MCP gateway (e.g. `http://sluice:3000`). This is added to `SelfBypass` so sluice does not policy-check its own MCP traffic. Defaults to deriving from `--health-addr`. `--agent <profile>` selects an agent profile (`openclaw`, `hermes`); the profile controls the env file path inside the container, the secrets-reload mechanism, and the MCP wiring command. The default is `openclaw`. May also be set via `SLUICE_AGENT_PROFILE`.
+
+## Agent Profiles
+
+Profiles abstract per-agent runtime conventions so sluice's container managers stay agent-agnostic. Each profile carries `EnvFileRelPath` (where to write phantom-token env vars), `ReloadCmd` (argv to exec for in-place secret reload, or nil), and `WireMCPCmd` (argv to register sluice as an MCP server in the agent's config).
+
+| Profile | Env file | Reload | MCP wiring |
+|---------|----------|--------|------------|
+| `openclaw` (default) | `~/.openclaw/.env` | `node -e <gateway_rpc.js> secrets.reload` over the agent's WebSocket gateway | `node -e <gateway_rpc.js> wire-mcp <name> <url>` patches `mcp.servers.<name>` |
+| `hermes` | `~/.hermes/.env` | None — Hermes has no documented in-place reload; new env values take effect on next message / restart | `python3 -c <script> <name> <url>` patches `mcp_servers.<name>.url` in `~/.hermes/config.yaml` (idempotent; relies on PyYAML which Hermes already requires) |
+
+Adding a new profile is a single edit to `internal/container/agent_profile.go`: register a struct in `builtinProfiles`. All three container backends (Docker, Apple Container, tart) consume the profile through `BuildEnvInjectionScriptForProfile`, `profile.ReloadCmd()`, and `profile.WireMCPCmd()`, so backend code does not need to know about specific agents.
+
+Hermes-specific caveats:
+
+- `ReloadCmd` is nil; `ReloadSecrets` logs a notice and returns nil. New phantom tokens take effect on the next Hermes message or `/reload-mcp` slash command.
+- `WireMCPCmd` rewrites `~/.hermes/config.yaml` directly. Hermes picks up the change on its next startup or via `/reload-mcp` from the chat session — sluice cannot trigger that command remotely.
+- Hermes' Modal, Daytona, and Vercel Sandbox terminal backends run code on third-party infrastructure that sluice cannot intercept. The local and Docker Hermes backends are the supported targets for sluice's network-layer governance.
 
 ## MCP Gateway Setup
 
@@ -126,9 +143,11 @@ OpenClaw connects to sluice's MCP gateway via Streamable HTTP. This is a one-tim
 docker exec openclaw openclaw mcp set sluice '{"url":"http://sluice:3000/mcp"}'
 ```
 
-For the hostname `sluice` to resolve inside OpenClaw, the compose file pins sluice's IP on the internal network (172.30.0.2) and adds an `extra_hosts` entry on tun2proxy (which OpenClaw shares). Docker's embedded DNS (127.0.0.11) is not reachable from OpenClaw because its DNS is routed through the TUN device. The `/etc/hosts` entry bypasses DNS entirely.
+For Hermes, the equivalent runs once at sluice startup via `WireMCPGateway` and writes `mcp_servers.sluice.url` into `~/.hermes/config.yaml`. Trigger Hermes' `/reload-mcp` slash command (or restart Hermes) once after first wire-up so it picks up the new server.
+
+For the hostname `sluice` to resolve inside the agent container, the compose file pins sluice's IP on the internal network (172.30.0.2) and adds an `extra_hosts` entry on tun2proxy (which the agent shares). Docker's embedded DNS (127.0.0.11) is not reachable from the agent because its DNS is routed through the TUN device. The `/etc/hosts` entry bypasses DNS entirely.
 
-MCP upstreams can be managed via `sluice mcp add|list|remove`, the REST API (`/api/mcp/upstreams`), or the Telegram bot (`/mcp add|list|remove`). All three paths write to the same SQLite store. After any addition or removal, restart sluice so the gateway re-reads the upstream set. OpenClaw does not need to be restarted: its connection to `sluice:3000/mcp` is registered once at sluice startup (via `WireMCPGateway`, which patches `mcp.servers.sluice = {url: ...}` in the agent's openclaw.json) and stays valid across sluice restarts. The agent re-queries the tool list on subsequent agent runs.
+MCP upstreams can be managed via `sluice mcp add|list|remove`, the REST API (`/api/mcp/upstreams`), or the Telegram bot (`/mcp add|list|remove`). All three paths write to the same SQLite store. After any addition or removal, restart sluice so the gateway re-reads the upstream set. The agent does not need to be restarted: its connection to `sluice:3000/mcp` is registered once at sluice startup (via `WireMCPGateway`) and stays valid across sluice restarts. The agent re-queries the tool list on subsequent runs.
 
 The Telegram `/mcp add` path auto-deletes the chat message because `--env KEY=VAL` pairs may contain secrets (use `KEY=vault:name` to keep the plaintext out of the SQLite store and `/mcp list` output entirely).
 

README.md

@@ -1,4 +1,4 @@
-# :shield: Sluice — Credential Governance Proxy for OpenClaw
+# :shield: Sluice — Credential Governance Proxy for AI Agents
 
 [![Tests](https://github.com/nnemirovsky/sluice/actions/workflows/test.yml/badge.svg)](https://github.com/nnemirovsky/sluice/actions/workflows/test.yml)
 [![E2E](https://github.com/nnemirovsky/sluice/actions/workflows/e2e-linux.yml/badge.svg)](https://github.com/nnemirovsky/sluice/actions/workflows/e2e-linux.yml)
@@ -13,18 +13,18 @@ Keeps real secrets out of the agent, enforces per-request policy on every connec
 
 AI agents need credentials to be useful. Giving them real credentials is dangerous.
 
-**The problem:** OpenClaw makes API calls, opens network connections, and invokes MCP tools. Without governance, it can leak secrets in tool outputs, connect to unexpected endpoints, or make destructive API calls. No existing tool combines credential isolation, human approval, all-protocol interception, and MCP-level governance in one place.
+**The problem:** Agents like [OpenClaw](https://openclaw.ai) and [Hermes](https://github.com/NousResearch/hermes-agent) make API calls, open network connections, and invoke MCP tools. Without governance, they can leak secrets in tool outputs, connect to unexpected endpoints, or make destructive API calls. No existing tool combines credential isolation, human approval, all-protocol interception, and MCP-level governance in one place.
 
-**The solution:** Sluice intercepts everything at two layers and never gives OpenClaw real credentials.
+**The solution:** Sluice intercepts everything at two layers and never gives the agent real credentials.
 
 | Layer | What it sees | What it governs |
 |-------|-------------|-----------------|
 | **MCP Gateway** | Tool names, arguments, responses | File writes, exec, deletions, any MCP tool call |
 | **SOCKS5 Proxy** | Every TCP and UDP connection | HTTP, HTTPS, WebSocket, gRPC, SSH, IMAP, SMTP, DNS, QUIC/HTTP3 |
 
-**Phantom token swap:** OpenClaw gets phantom tokens that look like real API keys, injected as environment variables via `docker exec` (no shared volume needed). Sluice's MITM proxy swaps them for real credentials in-flight. If a phantom token leaks, it is useless outside the proxy. OAuth credentials are handled bidirectionally: sluice intercepts token endpoint responses, captures real tokens, and returns phantom tokens to the agent. The entire OAuth lifecycle (initial auth, token refresh, token rotation) is transparent.
+**Phantom token swap:** the agent gets phantom tokens that look like real API keys, injected as environment variables via `docker exec` (no shared volume needed). Sluice's MITM proxy swaps them for real credentials in-flight. If a phantom token leaks, it is useless outside the proxy. OAuth credentials are handled bidirectionally: sluice intercepts token endpoint responses, captures real tokens, and returns phantom tokens to the agent. The entire OAuth lifecycle (initial auth, token refresh, token rotation) is transparent.
 
-**Human approval:** Connections and tool calls matching "ask" policy rules trigger a notification via Telegram or HTTP webhook. OpenClaw blocks until a human responds with Allow or Deny.
+**Human approval:** Connections and tool calls matching "ask" policy rules trigger a notification via Telegram or HTTP webhook. The agent blocks until a human responds with Allow or Deny.
 
 **Credential isolation:** Real secrets live in an encrypted vault (age, HashiCorp Vault, 1Password, Bitwarden, KeePass, or gopass). They are decrypted into zeroed memory only at injection time and never exposed to the agent process.
 
@@ -69,6 +69,22 @@ flowchart LR
 
 ## Quick Start
 
+### Choosing an agent profile
+
+Sluice ships with profiles for the agents it knows about. The profile controls where credentials are written inside the container, how secret reload is signalled, and how sluice's MCP gateway is registered in the agent's config.
+
+| Profile | Env file | In-place reload | MCP wiring |
+|---------|----------|-----------------|------------|
+| `openclaw` (default) | `~/.openclaw/.env` | Gateway WebSocket RPC (`secrets.reload`) | Patches `mcp.servers.<name>` via gateway RPC |
+| `hermes` | `~/.hermes/.env` | None — picked up on next agent run | Patches `mcp_servers.<name>.url` in `~/.hermes/config.yaml` (requires `python3` + `pyyaml` in the container, both shipped with Hermes) |
+
+Select with `--agent <name>` (or `SLUICE_AGENT_PROFILE=<name>`). The default is `openclaw` so existing setups need no changes.
+
+For Hermes specifically, two follow-up notes:
+
+- Sluice cannot trigger Hermes' `/reload-mcp` slash command after wiring; either restart Hermes once after `sluice` first writes the config, or invoke `/reload-mcp` from your Hermes chat session.
+- Hermes' Modal/Daytona/Vercel Sandbox terminal backends run code on third-party infrastructure that sluice cannot intercept. Use the `local` or `docker` Hermes backend if you want sluice's network governance to apply.
+
 ### Docker (Linux)
 
 The recommended setup for Linux. Three containers share a network namespace: sluice (proxy), tun2proxy (routes all traffic through SOCKS5), and OpenClaw.

cmd/sluice/main.go

@@ -88,6 +88,7 @@ func main() {
 	certDir := flag.String("cert-dir", "", "shared volume path for CA certificate (enables MITM trust injection into guest)")
 	dnsResolver := flag.String("dns-resolver", "", "upstream DNS resolver address for DNS interception (default: 8.8.8.8:53)")
 	mcpBaseURL := flag.String("mcp-base-url", "", "external base URL the agent uses to reach sluice's MCP gateway (e.g. http://sluice:3000); added to SelfBypass so sluice does not policy-check its own MCP traffic")
+	agentFlag := flag.String("agent", envDefault("SLUICE_AGENT_PROFILE", "openclaw"), "agent profile: openclaw, hermes (controls env file path, reload mechanism, MCP config wiring)")
 	flag.Parse()
 
 	// Validate --runtime flag early.
@@ -106,6 +107,14 @@ func main() {
 		log.Fatalf("--runtime macos requires --vm-image (e.g. ghcr.io/cirruslabs/macos-sequoia-base:latest)")
 	}
 
+	// Resolve the agent profile early so it can be threaded into every
+	// container manager constructor below.
+	agentProfile, err := container.ProfileFromName(*agentFlag)
+	if err != nil {
+		log.Fatalf("invalid --agent value: %v", err)
+	}
+	log.Printf("agent profile: %s (env file ~/%s)", agentProfile.Name, agentProfile.EnvFileRelPath)
+
 	// Open the SQLite store.
 	db, err := store.New(*dbPath)
 	if err != nil {
@@ -250,7 +259,7 @@ func main() {
 		} else {
 			if fi, statErr := os.Stat(sock); statErr == nil && fi.Mode().Type() == os.ModeSocket {
 				client := container.NewSocketClient(sock)
-				containerMgr = container.NewDockerManager(client, *containerName)
+				containerMgr = container.NewDockerManagerForProfile(client, *containerName, agentProfile)
 				log.Printf("docker manager enabled: socket=%s, container=%s", sock, *containerName)
 			} else if *runtimeFlag == "docker" {
 				log.Fatalf("--runtime docker: socket %q not found or not a socket", sock)
@@ -269,11 +278,12 @@ func main() {
 			containerMgr = container.NewAppleManager(container.AppleManagerConfig{
 				CLI:           cli,
 				ContainerName: *containerName,
+				Profile:       agentProfile,
 			})
 			log.Printf("apple container manager enabled: container=%s", *containerName)
 		}
 	case "macos":
-		tartMgr, tartRouter, containerMgr, tartVMOwned = startMacOSVM(*vmImage, *containerName, *certDir)
+		tartMgr, tartRouter, containerMgr, tartVMOwned = startMacOSVM(*vmImage, *containerName, *certDir, agentProfile)
 	case "none":
 		log.Printf("standalone mode: no container runtime (configure ALL_PROXY=socks5://%s manually)", *listenAddr)
 	case "":
@@ -1050,13 +1060,13 @@ func seedStoreFromConfig(db *store.Store, configPath string) error {
 // routing. Returns the TartManager, NetworkRouter (for shutdown cleanup),
 // the ContainerManager interface, and a boolean indicating whether sluice
 // started the VM. Calls log.Fatalf on unrecoverable errors.
-func startMacOSVM(vmImage, vmName, certDir string) (*container.TartManager, *container.NetworkRouter, container.ContainerManager, bool) {
+func startMacOSVM(vmImage, vmName, certDir string, profile *container.AgentProfile) (*container.TartManager, *container.NetworkRouter, container.ContainerManager, bool) {
 	cli, cliErr := container.NewTartCLI(nil)
 	if cliErr != nil {
 		log.Fatalf("--runtime macos: tart CLI not available: %v", cliErr)
 	}
 
-	mgr, router, owned, err := setupMacOSVM(cli, vmImage, vmName, certDir)
+	mgr, router, owned, err := setupMacOSVM(cli, vmImage, vmName, certDir, profile)
 	if err != nil {
 		log.Fatalf("--runtime macos: %v", err)
 	}
@@ -1105,7 +1115,7 @@ func waitForVMIP(ctx context.Context, cli *container.TartCLI, vmName string) (st
 // indicates whether sluice started the VM (true) or attached to an
 // already-running VM (false). Only VMs started by sluice should be
 // stopped on shutdown.
-func setupMacOSVM(cli *container.TartCLI, vmImage, vmName, certDir string) (*container.TartManager, *container.NetworkRouter, bool, error) {
+func setupMacOSVM(cli *container.TartCLI, vmImage, vmName, certDir string, profile *container.AgentProfile) (*container.TartManager, *container.NetworkRouter, bool, error) {
 	ctx := context.Background()
 
 	// Check if VM already exists.
@@ -1182,6 +1192,7 @@ func setupMacOSVM(cli *container.TartCLI, vmImage, vmName, certDir string) (*con
 		CLI:       cli,
 		VMName:    vmName,
 		RunConfig: runCfg,
+		Profile:   profile,
 	})
 
 	// Set up pf routing to redirect VM traffic through tun2proxy to SOCKS5.

internal/container/agent_profile.go

@@ -0,0 +1,124 @@
+package container
+
+import (
+	"fmt"
+	"strings"
+)
+
+// AgentProfile abstracts agent-specific runtime conventions so that sluice
+// can manage credential and MCP wiring for more than one agent. Each agent
+// stores its env file in a different location, has a different mechanism
+// for picking up secret changes, and registers MCP servers in a different
+// config format. A profile captures all three so that the container
+// managers (Docker, Apple Container, tart) stay agent-agnostic.
+type AgentProfile struct {
+	// Name is the human-readable profile identifier (e.g. "openclaw").
+	Name string
+
+	// EnvFileRelPath is the path to the agent's secret env file relative
+	// to the in-container HOME directory (e.g. ".openclaw/.env").
+	EnvFileRelPath string
+
+	// ReloadCmd returns the argv to exec inside the agent container in
+	// order to make a freshly-written env file take effect. Returning nil
+	// means the profile has no in-place reload mechanism; the caller
+	// should log a notice and rely on the next agent run / container
+	// restart picking up the new values.
+	ReloadCmd func() []string
+
+	// WireMCPCmd returns the argv to exec for registering sluice's MCP
+	// gateway URL inside the agent's config. It is invoked once per
+	// sluice startup. Returning nil means the profile cannot patch
+	// config in place and the operator must wire the MCP gateway
+	// manually before starting the agent.
+	WireMCPCmd func(name, url string) []string
+}
+
+// OpenclawProfile is the default profile. Openclaw stores secrets at
+// ~/.openclaw/.env and exposes a JSON-RPC gateway (over WebSocket) for
+// reloading secrets and patching config. The embedded gateway_rpc.js
+// script handles the device-signed handshake.
+var OpenclawProfile = &AgentProfile{
+	Name:           "openclaw",
+	EnvFileRelPath: ".openclaw/.env",
+	ReloadCmd: func() []string {
+		return GatewayRPCNodeCommand("secrets.reload")
+	},
+	WireMCPCmd: func(name, url string) []string {
+		return GatewayRPCNodeCommand("wire-mcp", name, url)
+	},
+}
+
+// hermesMCPWireScript is a small Python script that registers an MCP
+// server inside ~/.hermes/config.yaml under the mcp_servers key. Hermes
+// reads MCP servers from this file at startup and on the /reload-mcp
+// slash command. We rely on PyYAML being available because Hermes itself
+// is a Python application that ships with PyYAML as a hard dependency.
+//
+// The script is idempotent: if mcp_servers.<name>.url already matches,
+// the file is not rewritten.
+const hermesMCPWireScript = `
+import os, sys, yaml
+name, url = sys.argv[1], sys.argv[2]
+cfg_path = os.path.expanduser("~/.hermes/config.yaml")
+os.makedirs(os.path.dirname(cfg_path), exist_ok=True)
+data = {}
+if os.path.exists(cfg_path):
+    with open(cfg_path) as fh:
+        data = yaml.safe_load(fh) or {}
+servers = data.setdefault("mcp_servers", {})
+existing = servers.get(name) or {}
+if existing.get("url") == url:
+    sys.exit(0)
+existing["url"] = url
+servers[name] = existing
+with open(cfg_path, "w") as fh:
+    yaml.safe_dump(data, fh, sort_keys=False)
+`
+
+// HermesProfile targets nousresearch/hermes-agent. Hermes stores secrets
+// at ~/.hermes/.env and MCP servers under mcp_servers in
+// ~/.hermes/config.yaml. There is no documented in-process reload for
+// .env, so ReloadCmd is nil and callers fall back to logging a notice;
+// new credentials take effect on the next agent message.
+//
+// MCP wiring patches config.yaml directly. Hermes picks up the change on
+// startup or via the /reload-mcp slash command (which the operator must
+// invoke from the agent UI; sluice cannot trigger it remotely).
+var HermesProfile = &AgentProfile{
+	Name:           "hermes",
+	EnvFileRelPath: ".hermes/.env",
+	ReloadCmd:      nil,
+	WireMCPCmd: func(name, url string) []string {
+		return []string{"python3", "-c", hermesMCPWireScript, name, url}
+	},
+}
+
+// builtinProfiles is the registry consulted by ProfileFromName.
+var builtinProfiles = map[string]*AgentProfile{
+	"openclaw": OpenclawProfile,
+	"hermes":   HermesProfile,
+}
+
+// ProfileFromName returns the built-in profile matching name, or an
+// error listing the known profiles.
+func ProfileFromName(name string) (*AgentProfile, error) {
+	if p, ok := builtinProfiles[name]; ok {
+		return p, nil
+	}
+	known := make([]string, 0, len(builtinProfiles))
+	for k := range builtinProfiles {
+		known = append(known, k)
+	}
+	return nil, fmt.Errorf("unknown agent profile %q (known: %s)", name, strings.Join(known, ", "))
+}
+
+// resolveProfile returns p when non-nil, or OpenclawProfile as the
+// default. This lets existing call sites that do not pass a profile
+// keep their previous behavior.
+func resolveProfile(p *AgentProfile) *AgentProfile {
+	if p == nil {
+		return OpenclawProfile
+	}
+	return p
+}