proxy: dial the tunnel through an HTTP proxy when the guest requires one

The tunnel client (`proxy run --url`) used the runtime's native WebSocket,
which ignores HTTP(S)_PROXY and always dials direct. In a sandbox whose only
egress is an explicit proxy gateway (e.g. Docker Sandboxes), the broker was
unreachable without an external socat shim.

When a proxy applies to the tunnel URL (HTTP_PROXY/HTTPS_PROXY/ALL_PROXY,
honoring NO_PROXY), the client now establishes an HTTP CONNECT tunnel through
it, optional TLS for wss://, and the WS handshake itself, then speaks RFC 6455
over the socket. This hand-rolled path is runtime-agnostic (net/tls/crypto), so
it behaves identically under Node and the compiled Bun binary; the direct dial
is unchanged. Adds a Docker Sandboxes guide.

Author: theoephraim

.bumpy/tunnel-connect-proxy.md

@@ -0,0 +1,5 @@
+---
+varlock: minor
+---
+
+proxy run --url now dials its tunnel through an HTTP proxy (HTTP(S)_PROXY/NO_PROXY), so a sandboxed agent whose only egress is a proxy gateway (e.g. Docker Sandboxes) can reach a broker

packages/varlock-website/src/content/docs/guides/proxy/running.mdx

@@ -43,6 +43,8 @@ node agent.js                       # now routed through the proxy
 
 The workload does not have to be on the same machine. `proxy start --expose` makes the proxy reachable off-loopback and serves a built-in WebSocket tunnel, gated by a per-session data-plane token, and `proxy run --url wss://<host>` runs a command through that broker from anywhere, self-wiring the placeholder env and CA certs over the tunnel. The token is a credential: pin it with `VARLOCK_PROXY_TOKEN` or read it back with `varlock proxy token`, and prefer passing it to clients as an env var rather than a `--token` argument. This is how cloud sandboxes reach a broker; see the [E2B](/sandboxes/e2b/) and [Fly.io](/sandboxes/flyio/) guides for full recipes and the [proxy CLI reference](/reference/cli/proxy/) for the flags.
 
+When the guest's only egress is an explicit HTTP proxy (a corporate proxy, or a sandbox gateway like [Docker Sandboxes](/sandboxes/docker-sandboxes/)), `proxy run --url` dials the tunnel through it automatically: it honors `HTTP_PROXY` / `HTTPS_PROXY` / `ALL_PROXY` and `NO_PROXY` (a loopback or `NO_PROXY`-matched broker still dials direct). Only HTTP `CONNECT` proxies are supported, not SOCKS. The tunnel carries TLS end to end, so an intermediate proxy that terminates TLS only ever sees the encrypted tunnel.
+
 ## Sessions
 
 Every `varlock proxy` command operates on a **session**: one running proxy with its own short id (printed by `proxy start`, listed by `proxy status`). You target a session in one of two ways:

packages/varlock-website/src/content/docs/sandboxes/docker-sandboxes.mdx

@@ -0,0 +1,104 @@
+---
+title: Docker Sandboxes
+description: Using varlock with Docker Sandboxes (sbx), so an agent in a local microVM routes through the varlock credential proxy and holds only placeholders.
+---
+
+[Docker Sandboxes](https://docs.docker.com/ai/sandboxes/) (the `sbx` CLI) runs agents in local microVMs. Each sandbox gets its own Docker daemon, filesystem, and network, and all egress is forced through a host-side gateway with a deny-by-default domain allowlist (`sbx policy`). That gateway is the seam varlock plugs into: point the agent at a varlock broker, allow the broker in policy, and the agent holds only [placeholders](/guides/proxy/rules/#placeholders) while varlock injects real secrets at the wire.
+
+The recommended shape for local development is a **broker on your own machine**: secrets, resolver [plugins](/guides/plugins/), biometric unlock, and the interactive request log all stay on the host, and the sandbox reaches the broker through the sbx gateway. To share one broker across a fleet, run it on [infrastructure you operate](#remote-broker) and reach it at a public URL instead.
+
+## How sbx egress works
+
+Two facts about the gateway shape the setup:
+
+- **Everything goes through the gateway.** Inside a sandbox, `HTTP_PROXY` / `HTTPS_PROXY` point at `gateway.docker.internal:3128`, the sbx CA is in the trust store, and non-allowed domains do not even resolve. `varlock proxy run --url` [honors those proxy env vars](/guides/proxy/running/#remote-proxy-start---expose--proxy-run---url) and dials its tunnel through the gateway automatically, so no shim is needed.
+- **The gateway can reach a host-local service** when you allow it in policy. This is what makes a host broker reachable from the microVM.
+
+## Broker on your machine
+
+```
+[sbx microVM]                         [your host]
+  varlock proxy run --url             varlock proxy start --expose
+    ws://host.docker.internal:PORT      (real secrets, plugins, request log)
+      │                                     ▲
+      └──▶ gateway.docker.internal:3128 ────┘  (allowed by sbx policy)
+```
+
+### 1. Schema
+
+Mark the secrets your agent uses with [`@proxy(domain=...)`](/reference/item-decorators/#proxy) and give each an explicit [`@placeholder`](/reference/item-decorators/#placeholder):
+
+```env-spec title=".env.schema"
+# @proxy(domain="api.anthropic.com")
+# @placeholder=sk-ant-api03-000000000000000000000000
+ANTHROPIC_API_KEY=
+```
+
+Egress is permissive by default (unmatched hosts pass through untouched, which is fine because the agent holds only placeholders). To make the broker refuse anything without a rule, set [`@proxyConfig={egress="strict"}`](/guides/proxy/rules/#egress-modes) in the schema header.
+
+### 2. Start the broker on the host
+
+`--expose` binds off-loopback and serves the [tunnel](/guides/proxy/running/#remote-proxy-start---expose--proxy-run---url), minting a data-plane token. Pin the token so you can hand the same value to the agent:
+
+```bash
+export VARLOCK_PROXY_TOKEN=$(uuidgen)
+varlock proxy start --expose --port 8080
+```
+
+### 3. Allow the broker in sbx policy
+
+The gateway rewrites `host.docker.internal` to `localhost` before evaluating policy, so the rule that matches is for **`localhost`**, even though the agent connects to `host.docker.internal`:
+
+```bash
+sbx policy allow network "localhost:8080"
+```
+
+:::caution[sbx quirk]
+Allowing `host.docker.internal:8080` does **not** work (and `sbx policy check` will misleadingly say it is allowed). Allow `localhost:8080`. This is a Docker Sandboxes behavior, not a varlock one.
+:::
+
+### 4. Run the agent through the broker
+
+Install varlock in the sandbox, then wrap the agent command with `proxy run --url`. The agent connects to the broker at `host.docker.internal`, and varlock self-wires its placeholder env and CA certs over the tunnel:
+
+```bash
+# in a shell sandbox (sbx create shell . && sbx exec <name> -- ...):
+curl -sSfL https://varlock.dev/install.sh | sh -s
+
+VARLOCK_PROXY_TOKEN=$YOUR_TOKEN \
+  varlock proxy run --url ws://host.docker.internal:8080 -- your-agent-command
+```
+
+That is the whole path: the agent holds placeholders, the broker on your host injects real values only on verified TLS connections to hosts your schema allows, and every request is checked against your [`@proxy` rules](/guides/proxy/rules/#routing-rules) and recorded in the [audit log](/guides/proxy/running/#auditing).
+
+:::note[Installing varlock in the sandbox]
+The install script drops a self-contained binary and works on any template. Templates on Node 22.3+ (the `shell` template is) can instead `npm i -g varlock`, a lighter install. Baking varlock into a [custom template](https://docs.docker.com/ai/sandboxes/customize/) skips the per-sandbox install, which matters for a fleet. Pass the token via the environment (`sbx exec -e` or a template default), not on the command line, so it stays out of process listings.
+:::
+
+## Remote broker
+
+To share one broker across machines or a fleet, run it on infrastructure you operate and expose it at a URL that carries WebSockets. Because sbx allows direct TLS to allowlisted domains, the agent reaches a public `wss://` broker directly (no gateway asymmetry), so you only allow the broker's domain:
+
+```bash
+sbx policy allow network "broker.example.com"
+# in the sandbox:
+VARLOCK_PROXY_TOKEN=$YOUR_TOKEN \
+  varlock proxy run --url wss://broker.example.com -- your-agent-command
+```
+
+The data-plane token gates the tunnel and the tunnel carries TLS end to end, so a public URL is safe and any intermediary only sees ciphertext. See the [topologies overview](/sandboxes/overview/#topologies) and the [E2B](/sandboxes/e2b/) / [Fly.io](/sandboxes/flyio/) guides for the same broker shape on cloud providers.
+
+## varlock proxy vs sbx secrets
+
+Docker Sandboxes ships its own credential injection (`sbx secret`): the gateway substitutes a stored keychain value into request headers for a matching host. It covers the basic case. Route through a varlock broker when you want:
+
+- **Custody in your secret manager.** Secrets come from wherever you already keep them through [plugins](/guides/plugins/) (1Password, Vault, AWS, Doppler, ...) and stay in your custody, instead of being copied into another store.
+- **One schema.** Your `.env.schema` describes every value, its type, and its routing in one declarative layer, legible to people and agents alike.
+- **Response scrubbing.** varlock scans response bodies and redacts injected secret values, so an allowlisted endpoint that echoes a request header cannot hand the real secret back to the agent.
+- **Policy and audit.** Match on path and method, [hot-reload](/guides/proxy/running/#editing-the-schema-while-a-session-is-running) the schema, and keep your own [audit log](/guides/proxy/running/#auditing).
+
+The two compose: sbx provides microVM isolation and deny-by-default egress; the varlock broker provides custody, injection, and scrubbing.
+
+## Trust model
+
+The broker holds real secrets on whatever machine runs it. For a host broker in local development, that is your own machine, the same place the secrets already live. The agent's microVM never holds them: a compromised or prompt-injected agent yields placeholders and only the requests your rules and egress mode allow. Keep sbx policy tight (allow just the broker, plus whatever hosts the agent legitimately needs), and treat the data-plane token like any shared secret (rotate by restarting the broker with a new one).

packages/varlock-website/src/content/docs/sandboxes/overview.mdx

@@ -28,6 +28,7 @@ Cloud sandbox providers run the agent in a remote VM, so the proxy is reached ov
 <CardGrid>
   <LinkCard title="E2B" href="/sandboxes/e2b/" description="Broker sandbox or tunnel to your machine; egress lockdown via network rules" />
   <LinkCard title="Fly.io" href="/sandboxes/flyio/" description="Broker sprite or tunnel to your machine; egress lockdown via network policy" />
+  <LinkCard title="Docker Sandboxes" href="/sandboxes/docker-sandboxes/" description="Local microVMs (sbx); reach a host or remote broker through the gateway" />
 </CardGrid>
 
 ## Local tools
@@ -41,4 +42,4 @@ Cloud sandbox providers run the agent in a remote VM, so the proxy is reached ov
   <LinkCard title="MXC" href="/sandboxes/mxc/" description="Windows AppContainer (processcontainer). Windows 11" />
 </CardGrid>
 
-Tools that already broker credentials at the network boundary (Docker Sandboxes, microsandbox, Anthropic `srt` credential `mask`, and similar) are out of scope here. Use those on their own, or wait for varlock host bridging if you want varlock as the broker inside a microVM that cannot reach host loopback.
+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](/sandboxes/docker-sandboxes/) has such a gateway but also lets its policy reach a varlock broker, so it gets its own guide above (host broker or remote broker, with varlock as the injector).

packages/varlock-website/src/sidebar.ts

@@ -259,6 +259,7 @@ export const sidebar: StarlightUserConfig['sidebar'] = [
             items: [
               { label: 'E2B', slug: 'sandboxes/e2b' },
               { label: 'Fly.io', slug: 'sandboxes/flyio' },
+              { label: 'Docker Sandboxes', slug: 'sandboxes/docker-sandboxes' },
             ],
           },
           {

packages/varlock/src/proxy/tunnel.test.ts

@@ -5,12 +5,63 @@ import { randomBytes } from 'node:crypto';
 import { describe, expect, test } from 'vitest';
 
 import {
-  attachTunnelServer, fetchTunnelBootstrap, startTunnelClientListener, TUNNEL_TOKEN_HEADER, TUNNEL_PATH,
+  attachTunnelServer, fetchTunnelBootstrap, startTunnelClientListener, proxyForTunnelUrl,
+  TUNNEL_TOKEN_HEADER, TUNNEL_PATH,
   type TunnelBootstrap,
 } from './tunnel';
 
 const TOKEN = 'tunnel-test-token';
 
+/** Set env vars for a test, returning a restore fn that puts the prior values back. */
+function withEnvVars(vars: Record<string, string>): () => void {
+  const prev: Record<string, string | undefined> = {};
+  for (const [key, value] of Object.entries(vars)) {
+    prev[key] = process.env[key];
+    process.env[key] = value;
+  }
+  return () => {
+    for (const [key, was] of Object.entries(prev)) {
+      if (was === undefined) {
+        delete process.env[key];
+      } else {
+        process.env[key] = was;
+      }
+    }
+  };
+}
+
+/** A minimal HTTP CONNECT proxy standing in for a sandbox egress gateway. Counts
+ * how many CONNECTs it served so tests can assert traffic actually went through it. */
+function startConnectProxy(): Promise<{ port: number; connects: () => number; close: () => void }> {
+  let connects = 0;
+  return new Promise((resolve) => {
+    const srv = http.createServer();
+    srv.on('connect', (req, clientSock, head) => {
+      connects += 1;
+      const [host, port] = (req.url ?? '').split(':');
+      const upstream = net.connect(Number(port), host, () => {
+        clientSock.write('HTTP/1.1 200 Connection Established\r\n\r\n');
+        if (head?.length) upstream.write(head);
+        upstream.pipe(clientSock);
+        clientSock.pipe(upstream);
+      });
+      const kill = () => {
+        upstream.destroy();
+        clientSock.destroy();
+      };
+      upstream.on('error', kill);
+      clientSock.on('error', kill);
+    });
+    srv.listen(0, '127.0.0.1', () => {
+      resolve({
+        port: (srv.address() as net.AddressInfo).port,
+        connects: () => connects,
+        close: () => srv.close(),
+      });
+    });
+  });
+}
+
 /** An echo TCP server standing in for the broker's proxy loopback port. */
 function startEcho(): Promise<{ port: number; close: () => void }> {
   return new Promise((resolve) => {
@@ -232,6 +283,114 @@ describe('server frame codec (raw client)', () => {
   });
 });
 
+describe('proxy selection', () => {
+  const base = 'ws://broker.internal:8080';
+  test('picks HTTP_PROXY for ws:// and honors NO_PROXY', () => {
+    expect(proxyForTunnelUrl(base, { HTTP_PROXY: 'http://gw:3128' })).toBe('http://gw:3128');
+    expect(proxyForTunnelUrl(base, { HTTP_PROXY: 'http://gw:3128', NO_PROXY: 'broker.internal' })).toBeUndefined();
+    expect(proxyForTunnelUrl(base, { HTTP_PROXY: 'http://gw:3128', NO_PROXY: '*' })).toBeUndefined();
+  });
+  test('picks HTTPS_PROXY for wss:// and falls back to ALL_PROXY', () => {
+    expect(proxyForTunnelUrl('wss://broker.example.com', { HTTPS_PROXY: 'http://gw:3128' })).toBe('http://gw:3128');
+    expect(proxyForTunnelUrl(base, { ALL_PROXY: 'http://gw:3128' })).toBe('http://gw:3128');
+  });
+  test('ignores socks proxies and a missing proxy (direct dial)', () => {
+    expect(proxyForTunnelUrl(base, {})).toBeUndefined();
+    expect(proxyForTunnelUrl(base, { ALL_PROXY: 'socks5://gw:1080' })).toBeUndefined();
+  });
+  test('dot-suffix NO_PROXY matches subdomains', () => {
+    expect(proxyForTunnelUrl('ws://a.corp.example:8080', { HTTP_PROXY: 'http://gw:3128', NO_PROXY: '.example' })).toBeUndefined();
+    expect(proxyForTunnelUrl('ws://a.corp.example:8080', { HTTP_PROXY: 'http://gw:3128', NO_PROXY: 'other.test' })).toBe('http://gw:3128');
+  });
+});
+
+describe('tunnel through a CONNECT proxy', () => {
+  test('fetches the bootstrap via the proxy when HTTP_PROXY is set', async () => {
+    const echo = await startEcho();
+    const broker = await startBroker(echo.port, { payloadJson: '{"env":{"VIA":"proxy"},"omittedKeys":[],"serializedGraph":{"config":{}}}', certs: { 'ca-cert.pem': 'PX' } });
+    const proxy = await startConnectProxy();
+    const restore = withEnvVars({ HTTP_PROXY: `http://127.0.0.1:${proxy.port}` });
+    try {
+      const boot = await fetchTunnelBootstrap(broker.url, TOKEN);
+      expect(JSON.parse(boot.payloadJson).env.VIA).toBe('proxy');
+      expect(boot.certs['ca-cert.pem']).toBe('PX');
+      expect(proxy.connects()).toBeGreaterThan(0);
+    } finally {
+      restore();
+    }
+    proxy.close();
+    broker.close();
+    echo.close();
+  });
+
+  test('bridges the data path through the proxy (large, both directions)', async () => {
+    const echo = await startEcho();
+    const broker = await startBroker(echo.port);
+    const proxy = await startConnectProxy();
+    const restore = withEnvVars({ HTTP_PROXY: `http://127.0.0.1:${proxy.port}` });
+    let listener: Awaited<ReturnType<typeof startTunnelClientListener>> | undefined;
+    try {
+      listener = await startTunnelClientListener({ url: broker.url, token: TOKEN });
+      const payload = randomBytes(100_000);
+      const received = await new Promise<Buffer>((resolve, reject) => {
+        const chunks: Array<Buffer> = [];
+        let total = 0;
+        const c = net.connect(listener!.port, '127.0.0.1', () => c.write(payload));
+        c.on('data', (d: Buffer) => {
+          chunks.push(d);
+          total += d.length;
+          if (total >= payload.length) {
+            c.destroy();
+            resolve(Buffer.concat(chunks));
+          }
+        });
+        c.on('error', reject);
+        setTimeout(() => reject(new Error(`timed out after ${total}`)), 5000);
+      });
+      expect(received.equals(payload)).toBe(true);
+      expect(proxy.connects()).toBeGreaterThan(0);
+    } finally {
+      restore();
+    }
+    listener?.close();
+    proxy.close();
+    broker.close();
+    echo.close();
+  });
+
+  test('surfaces a bad token through the proxy as an error', async () => {
+    const echo = await startEcho();
+    const broker = await startBroker(echo.port);
+    const proxy = await startConnectProxy();
+    const restore = withEnvVars({ HTTP_PROXY: `http://127.0.0.1:${proxy.port}` });
+    try {
+      await expect(fetchTunnelBootstrap(broker.url, 'wrong-token', 3000)).rejects.toThrow();
+    } finally {
+      restore();
+    }
+    proxy.close();
+    broker.close();
+    echo.close();
+  });
+
+  test('NO_PROXY makes a loopback broker dial direct (proxy unused)', async () => {
+    const echo = await startEcho();
+    const broker = await startBroker(echo.port);
+    const proxy = await startConnectProxy();
+    const restore = withEnvVars({ HTTP_PROXY: `http://127.0.0.1:${proxy.port}`, NO_PROXY: '127.0.0.1' });
+    try {
+      const boot = await fetchTunnelBootstrap(broker.url, TOKEN);
+      expect(boot.certs['ca-cert.pem']).toBe('CA');
+      expect(proxy.connects()).toBe(0);
+    } finally {
+      restore();
+    }
+    proxy.close();
+    broker.close();
+    echo.close();
+  });
+});
+
 describe('tunnel constants', () => {
   test('token header and path are stable', () => {
     expect(TUNNEL_TOKEN_HEADER).toBe('x-varlock-tunnel-token');