Add Vercel Sandbox guide - #963
Conversation
Deploying with
|
| Status | Name | Latest Commit | Preview URL | Updated (UTC) |
|---|---|---|---|---|
| ✅ Deployment successful! View logs |
varlock-website | 35cb4f2 | Commit Preview URL Branch Preview URL |
Jul 31 2026, 12:05 AM |
![pullfrog[bot]](https://avatars.githubusercontent.com/in/1768019?s=60&v=4){kind=small}
There was a problem hiding this comment.
Important
The copyable broker recipe has three lifecycle and provisioning failures that should be fixed before merging.
Reviewed changes in the new Vercel Sandbox documentation and navigation, including the recipe's contracts with the Vercel SDK and varlock proxy.
- Direct value delivery: Documents loading validated values in the orchestrator and passing them through Vercel's sandbox environment.
- Persistent broker topology: Adds broker creation, proxy startup, agent tunnel wiring, CA persistence, and lifecycle guidance.
- Network controls: Covers live egress lockdown and compares varlock policy with Vercel firewall transforms.
- Documentation navigation: Adds the guide to the sandbox overview and site sidebar.
azure/gpt-5.6-sol ｜ 𝕏
| // yourself (or let the broker mint one and read it back with `varlock proxy | ||
| // token`). It is the credential to USE the broker over the tunnel, not to read | ||
| // its secrets. | ||
| const PROXY_TOKEN = crypto.randomUUID(); |
There was a problem hiding this comment.
Because this token is regenerated on every orchestrator invocation, an existing named broker keeps its create-time token while the new agent below receives a different token. Re-running the recipe against a running or resumed broker therefore makes new agents fail tunnel authentication; use a stable externally managed token, or rotate the broker and agents together.
Technical details
# Keep the broker token stable across `getOrCreate`
## Affected sites
- `packages/varlock-website/src/content/docs/sandboxes/vercel.mdx:73` generates a new token for each orchestrator process.
- `packages/varlock-website/src/content/docs/sandboxes/vercel.mdx:95` uses `Sandbox.getOrCreate`, whose creation parameters are ignored when the named sandbox already exists.
- `packages/varlock-website/src/content/docs/sandboxes/vercel.mdx:136` passes the newly generated token to each agent.
## Required outcome
- Existing and resumed brokers must receive the same `VARLOCK_PROXY_TOKEN` as every agent that connects to them.
## Suggested approach
- Resolve `PROXY_TOKEN` from durable orchestrator configuration rather than calling `crypto.randomUUID()` on each invocation.
- If intentional rotation is shown instead, recreate or update all affected broker and agent state as one operation.
## References
- https://vercel.com/docs/sandbox/sdk-reference#sandbox.getorcreate
- https://vercel.com/docs/sandbox/concepts/persistent-sandboxes| // upload the schema (plus any other .env files your project loads); | ||
| // real values arrive via env above instead | ||
| await sbx.writeFiles([ | ||
| { path: 'proj/.env.schema', content: Buffer.from(envSchemaContents) }, |
There was a problem hiding this comment.
A fresh sandbox does not contain proj, and Vercel documents that writeFiles() requires callers to create a missing target directory first. Add await sbx.mkDir('proj') before this upload, otherwise onCreate fails before the proxy can start. See https://vercel.com/docs/sandbox/sdk-reference#sandbox.mkdir.
| name: 'varlock-broker', | ||
| runtime: 'node24', | ||
| ports: [8080], | ||
| timeout: 60 * 60 * 1000, // default is only 5 minutes; max 45m (Hobby) / 24h (Pro) |
There was a problem hiding this comment.
This requests 60 minutes even though the adjacent comment correctly notes Hobby's 45-minute maximum, so the generic recipe is rejected on Hobby. Use a value valid on every supported plan or show how to select a plan-specific timeout, and make the same change to the agent timeout on line 133. See https://vercel.com/docs/sandbox/pricing#runtime-limits.
|
Closing for now -- I think we actually want to hold off here and make something more like what we are planning for cloudflare. |
1 participant
Adds a Vercel Sandbox recipe to the sandbox guides, following the same shape as the E2B and Fly.io guides from #931: pass resolved values for trusted workloads, broker sandbox with the built-in tunnel for agentic ones, egress lockdown via the platform firewall, and a comparison note on Vercel's native firewall transforms.
The whole topology was validated live on real Vercel sandboxes, including wire substitution (hash oracle), response scrubbing, strict egress, and a live
networkPolicyclamp. Vercel-specific facts baked into the recipe, all verified empirically:getOrCreate+onResume+--persist-camakes broker wakes invisible to agentsnpm i -g varlockworks on the default runtimeDocs only; no varlock code changes needed.