@gethelio/proxy 0.13.0 → 0.14.0

package/README.md

@@ -31,6 +31,8 @@ Model providers are building governance for their own platforms but your agents
 
 Helio governs what agents **do to the rest of the world** across any MCP-compatible agent, any tool, any platform.
 
+A rule in Helio cannot be forgotten and cannot be weakened silently. It is not in the model's context, so a long session cannot evict it and an injection cannot argue it away, and enforcement is in the path rather than in the prompt: a tool call routed through Helio is decided before it is forwarded, whatever the model has been told. Every attempt to reload the policy file, including one that removes a rule, is an audit record, and every record carries the hash of the config in force when it was written, so a change shows against the decisions made under it. The "cannot be weakened silently" claim has one condition, stated under [Enforcement grades](#enforcement-grades).
+
 ## How It Works
 
 <p align="center">
@@ -46,10 +48,12 @@ Two integration paths:
 
 Helio governs at the strongest grade each path physically allows, and records it per call:
 
-- **Structural** (stdio MCP) — Helio owns the only path to the tool; the agent cannot route around it.
+- **Structural** (stdio MCP) — Helio owns the child process it spawned, so nothing on the MCP path routes around it; a co-located process that can run the same command line is outside this grade (see the note below).
 - **Network** (HTTP MCP) — structural given you control the upstream's egress.
 - **Host-enforced** (hook adapters via the [adapter API](https://github.com/gethelio/helio/blob/main/docs/adapter-api.md), e.g. OpenClaw) — for frameworks that run tools in-process and expose hooks rather than an MCP transport. The framework's hook gate enforces; Helio decides. This is a cooperative, lower grade than the proxy path, and Helio labels it as such rather than overclaiming. Helio's decisions still cannot be evicted from the agent's context or prompt-injected, and any attempt to route around them is visible in the audit trail.
 
+All three grades assume the proxy's config, secret, and audit store are outside the agent's reach. In the default local install they are not: the proxy runs as the same user as the agent. [SECURITY.md](https://github.com/gethelio/helio/blob/main/SECURITY.md#process-and-filesystem-boundaries) states the boundary and the deployments that close it. That install is also the condition on "cannot be weakened silently": a same-user agent can restart the proxy without the config pin and can edit or delete the audit file, so the reload record and the hash on every record are durable only while the agent cannot write the audit file, and the event stream and stderr are the channels that leave the box before that. Run the proxy as its own user or in its own container, as the recipes there do, and the condition falls away.
+
 ## Quick Start (5 minutes)
 
 ### 1. Install
@@ -60,6 +64,8 @@ npx @gethelio/proxy init
 
 This single package includes the built-in dashboard UI bundle.
 
+Running your agent in a container? `npx @gethelio/proxy init --sandbox` writes the sidecar layout instead; see [Running Helio as a Sidecar](https://github.com/gethelio/helio/blob/main/docs/deployment-sidecar.md).
+
 ### 2. Configure
 
 `npx @gethelio/proxy init` already created a `helio.yaml` in your project root. Open it (e.g. `nano helio.yaml`, or in your editor) and point `upstream.url` at your existing MCP server. The singular `upstream:` form stays fully supported; to govern more than one MCP server, declare a named `upstreams:` list in its place (set exactly one of the two). Tool sets are never merged: each named upstream is served at its own `/mcp/<name>` door. See the [Configuration Reference](https://github.com/gethelio/helio/blob/main/docs/configuration.md#upstreams).
@@ -152,7 +158,7 @@ No MCP server to test against? Helio ships a zero-dependency echo server you can
 
 About `dashboard.api_secret`:
 
-- **If you ran `npx @gethelio/proxy init`**, your `helio.yaml` already contains a generated `api_secret` (a literal 32-byte hex value, also printed when you ran `init`). It's set — skip this step.
+- **If you ran `npx @gethelio/proxy init`**, your `helio.yaml` already contains the SHA-256 digest of a generated secret, and `init` printed the secret itself once. Keep the printed value; it is what you log in with. Skip this step.
 - **If you authored `helio.yaml` by hand** using the `${HELIO_DASHBOARD_SECRET}` placeholder shown above, set the variable before `start`:
 
   ```bash
@@ -193,7 +199,7 @@ Either way the call appears in the dashboard with its policy decision. (`get_wea
 http://localhost:3100
 ```
 
-If prompted, log in with the `dashboard.api_secret` that `init` generated (also printed when you ran it).
+If prompted, log in with the dashboard secret that `init` printed (the file holds only its digest).
 
 That's it. Every tool call now passes through Helio with a full audit trail, rate limits, and spend controls.
 
@@ -356,6 +362,8 @@ The full docs live in the [monorepo](https://github.com/gethelio/helio) and are
 - **[Policy Guide](https://github.com/gethelio/helio/blob/main/docs/policies.md)**: How to write rules with examples
 - **[Approval Workflows](https://github.com/gethelio/helio/blob/main/docs/approvals.md)**: Slack, webhook, and dashboard approvals
 - **[Audit Trail](https://github.com/gethelio/helio/blob/main/docs/audit.md)**: What's recorded, how to search, how to export
+- **[Running Helio as a Sidecar](https://github.com/gethelio/helio/blob/main/docs/deployment-sidecar.md)**: Deploy next to a coding agent or dev container with the upstream and the config out of its reach and Helio off its network
+- **[Running Helio as its own user](https://github.com/gethelio/helio/blob/main/docs/deployment-separate-user.md)**: The separate-user tier on Ubuntu 24.04, run end to end
 
 ## Examples