Docs
Blog
Sandboxes Overview
These are recipes for running an agent inside a third-party sandbox while varlock holds the real credentials. The sandbox contains the agent; the credential proxy gives it placeholders and swaps in real secrets only on verified connections to hosts you allow.
Read the sandboxing guide first. It covers why the two layers belong together, varlock’s own built-in --sandbox (macOS jail or a container, no third-party install), and the shared setup most local-tool recipes below assume.
Filesystem, process, and network isolation varies by tool, so check each recipe for its actual boundaries. Most don’t broker credentials themselves, so varlock stays the wire injector. Reach for one when you already run that tool, need Windows, or want a different isolation model than the built-in sandbox offers.
Topologies
Section titled “Topologies”There are a handful of ways to combine varlock with sandboxed agents, ordered here by how far real secrets stay from the agent. The provider guides below each bless one path (usually the broker instance) rather than documenting all of them.
- Inject resolved values. Run the orchestrator under
varlock runand pass values through the provider’s env machinery (or install varlock inside the sandbox and let it resolve its own). You get resolution, validation, and log redaction; the sandbox holds real values. Right for workloads you trust with the credentials they use. - Proxy inside the agent’s own sandbox. Running
proxy runon the same host as an untrusted agent is not recommended: the agent and the broker share a machine, so the boundary is a bar-raiser, not a wall (see why sandbox + proxy). Use a broker instance instead. - Broker instance. The proxy runs in one dedicated sandbox holding the real secrets (or a plugin secret-zero); agent sandboxes connect over the built-in tunnel and hold only placeholders. The recommended shape for cloud fleets, and what each provider guide shows.
- Proxy on infrastructure you run. The same broker shape, but on a VM or container platform you already operate, reachable at a URL that carries WebSockets. Useful when one broker should serve fleets across providers, or outlive any one provider’s sandbox lifecycle.
- Proxy on your machine. For the dev loop: secrets, resolver plugins, biometric unlock, and the interactive request log stay local, and sandboxes reach the proxy through a tunnel service (or the platform’s private networking where it exists).
Cloud sandboxes
Section titled “Cloud sandboxes”Cloud sandbox providers run the agent in a remote VM, so the proxy is reached over the built-in tunnel (proxy start --expose + proxy run --url) instead of loopback. Each guide leads with the recommended path for that platform and keeps the rest short.
Local tools
Section titled “Local tools”These run on your own machine. Most reach the proxy over loopback via the shared setup. Docker Sandboxes is the exception: a local microVM with its own egress gateway, so its agent reaches the proxy over the tunnel (like the cloud shapes above), and its guide differs accordingly.
Some tools already broker credentials at their own network boundary (microsandbox, Anthropic srt credential mask, and similar). You can use those on their own; varlock adds schema-driven policy, response scrubbing, your own audit log, and custody in your secret manager on top. Docker Sandboxes is one such tool with a guide here, because its policy can also route the agent through a varlock broker (host or remote), keeping varlock as the injector.