docs: Minimal sandbox guide (session networking broker topology) - #1033
docs: Minimal sandbox guide (session networking broker topology)#1033theoephraim wants to merge 4 commits into
Conversation
![pullfrog[bot]](https://avatars.githubusercontent.com/in/1768019?s=60&v=4){kind=small}
There was a problem hiding this comment.
Important
The hub-session recipe is missing required setup for both the broker and workers, so a fresh setup fails before connecting.
Reviewed changes across the new Minimal session-networking guide and its related sandbox index updates.
- Host broker topology: Documents session access to a host varlock broker through Minimal's host alias, including token handling, strict proxy rules, and installation constraints.
- Hub topology: Adds a named broker-session pattern reached through Minimal's in-session HTTP proxy.
- Network and trust model: Describes default, own-ip, and no-net behavior while distinguishing varlock proxy policy from an enforced egress boundary.
- Discovery updates: Revises the sandbox overview and comparison table for Minimal's session model.
azure/gpt-5.6-sol ｜ 𝕏
| ```bash | ||
| # hub: activate a session for your broker project with a stable name | ||
| # (min session rename <id> varlock also works on an existing session), then inside it: | ||
| min session activate --name varlock --attach |
There was a problem hiding this comment.
A fresh hub project cannot run the next npm command unless Node was added before activation. The guide says at lines 70-72 that session packages must be declared in minimal.toml and committed first, so please include that host-side setup here and make the host/session transition explicit.
| VARLOCK_PROXY_TOKEN=$YOUR_TOKEN varlock proxy start --expose --port 8080 | ||
|
|
||
| # inside each worker session: | ||
| VARLOCK_PROXY_TOKEN=$YOUR_TOKEN \ |
There was a problem hiding this comment.
Each worker invokes varlock, but this topology never installs it in worker sessions or states that it must already be present. The earlier install applies only to the single session in the host-broker recipe, so a newly created worker reaches this line with varlock: command not found; please add the worker installation or make a prebuilt-worker prerequisite explicit.
Deploying with
|
| Status | Name | Latest Commit | Preview URL | Updated (UTC) |
|---|---|---|---|---|
| ✅ Deployment successful! View logs |
varlock-website | 0d90374 | Commit Preview URL Branch Preview URL |
Aug 26 2026, 06:19 PM |
…rball and package corrections (verified on 0.5.3)
There was a problem hiding this comment.
Important
The inherited tunnel token remains visible to the launched agent, so the revised trust model understates credential exposure.
Reviewed changes since the prior Pullfrog review, covering the revised Minimal setup and operational guidance.
- Changed token delivery: Replaced command-local token assignment with
[session.vars]inheritance and documented Minimal's user-policy approval gate. - Corrected session setup: Clarified live package installation, VCS-root uploads, and the
--sync tarballfallback. - Updated verified behavior: Raised the tested version to
min0.5.3 and documented task inheritance and background-process quirks. - Expanded hub guidance: Added inherited secret-zero setup and removed token values from the hub and worker commands.
azure/gpt-5.6-sol ｜ 𝕏
|
|
||
| ```toml title="minimal.toml" | ||
| [session.vars] | ||
| VARLOCK_PROXY_TOKEN = { inherit = true } |
There was a problem hiding this comment.
This makes the bearer token ambient to every process in the session, and proxy run forwards its full ambient environment to the launched agent. A compromised agent can therefore exfiltrate and reuse the token over Minimal's open egress, contradicting the later claim that direct connections carry placeholders at worst and no secrets are at stake.
Technical details
# The agent inherits the tunnel credential
## Affected sites
- `packages/varlock-website/src/content/docs/sandboxes/minimal.mdx:66` - `[session.vars]` puts `VARLOCK_PROXY_TOKEN` in the session environment.
- `packages/varlock/src/cli/commands/proxy.command.ts:1891` - `runRemoteThroughTunnel` reads the token from `process.env`.
- `packages/varlock/src/cli/commands/proxy.command.ts:361-374` - `buildProxiedChildEnv` spreads the complete ambient environment into the child without removing the token.
- `packages/varlock-website/src/content/docs/sandboxes/minimal.mdx:144` - the trust model says direct connections carry placeholders at worst and no secrets are at stake.
## Required outcome
- Ensure the launched agent cannot read the broker token, or explicitly document that the agent holds this reusable bearer credential and scope the trust-model claims accordingly.1 participant
Rewrites the Minimal guide around their session networking surface (pre-release, undocumented) and verifies every recipe live, most recently on min 0.5.3 (macOS arm64, 2026-08-26), incorporating round-1 feedback from the Minimal team.
What the guide now covers:
varlock proxy run --url ws://100.64.255.254:8080needs no port publishing or policy rules. The tunnel token flows in via a[session.vars]inherit entry inminimal.toml(their suggested pattern, verified, including the user-policy approval gate). Verified: placeholder env over the tunnel, wire injection, response scrubbing, strict-egress 403s.ws://<hub>.local.min.internal:<port>through Minimal's in-session proxy viaHTTP_PROXY; our tunnel client passes through it with zero glue. Secret zero for the hub rides[session.vars]too.--ingresswork on the installed release; no in-namespace session proxy yet, so own-ip workers use the host broker. This is where Minimal's egress enforcement will land.npm i -gneeds--prefix ~/.local(read-only store); packages come fromminimal.tomlat activation, with the in-sandboxminhelper for live installs; uploads need a VCS root unless--sync tarball;min session execdrops its first stdout line; task-level env inherit can't carry the token yet.Also updates the overview card/exception note and the sandboxing table row.
The networking surface is deliberately undocumented by Minimal and may change; the guide carries a caution box saying so. Merge timing is a judgment call: we can hold this until Minimal is comfortable with the surface being documented publicly.