Add Daytona sandbox guide - #973
Conversation
Broker topology validated live: linked sandboxes give an internal link network (broker sandbox id doubles as a DNS name), so agents reach the proxy over plain ws with no public URL, tunnel service, or tier requirements. Covers resolved-value injection, the linked broker recipe, tier-based egress notes, preview-URL and local-dev variants, and a comparison with Daytona's native Secrets feature.
Placeholder and example key values now keep their real prefix and pad with zeros instead of trailing dots or ellipsis, and mentions of the generated fallback spell out its vlk_placeholder_<KEY>_<hash> shape. Codified the convention in AGENTS.md.
Deploying with
|
| Status | Name | Latest Commit | Preview URL | Updated (UTC) |
|---|---|---|---|---|
| ✅ Deployment successful! View logs |
varlock-website | e126f8f | Commit Preview URL Branch Preview URL |
Jul 31 2026, 11:29 PM |
![pullfrog[bot]](https://avatars.githubusercontent.com/in/1768019?s=60&v=4){kind=small}
There was a problem hiding this comment.
ℹ️ Two documentation compatibility details are worth correcting inline.
Reviewed changes Reviewed the new Daytona sandbox guide, its navigation wiring, and the documentation-wide placeholder example cleanup.
- Daytona integration: Documents resolved-value injection and a linked broker sandbox topology using the credential proxy.
- Operational guidance: Covers broker lifecycle, account-tier egress behavior, preview and local tunnel alternatives, trust boundaries, and Daytona Secrets.
- Documentation consistency: Adds the Daytona navigation entries and replaces truncated placeholder examples with complete representative values.
azure/gpt-5.6-sol ｜ 𝕏
Daytona's TypeScript SDK moved from @daytonaio/sdk to @daytona/sdk. Re-validated the broker recipe end to end on @daytona/sdk 0.203.0.
There was a problem hiding this comment.
ℹ️ No new issues found in the SDK package correction.
Reviewed changes Reviewed the Daytona SDK package update since the prior Pullfrog review.
- Current SDK import: Replaced the deprecated
@daytonaio/sdkimport with Daytona's supported@daytona/sdkpackage in both TypeScript examples.
azure/gpt-5.6-sol ｜ 𝕏
Signed URLs expire (60s default, 24h max), which makes them a poor fit for a long-lived broker endpoint; public: true plus the data-plane token is the validated path.
There was a problem hiding this comment.
✅ No new issues found.
Reviewed changes Reviewed the Daytona preview URL guidance update since the prior Pullfrog review.
- Preview endpoint lifecycle: Removed the time-limited signed preview URL option and retained the validated
public: truepath for long-lived brokers.
azure/gpt-5.6-sol ｜ 𝕏
Calls out that Daytona has no wake-on-request (a stopped broker cannot be woken by connecting agents), contrasts fleet-scoped vs standing broker lifetimes, and points at running the proxy on your own infrastructure when the broker should outlive any one fleet.
There was a problem hiding this comment.
Important
The new lifecycle guidance can leave a broker billing indefinitely or restarted without proxy service.
Reviewed changes Reviewed the broker lifetime and cost guidance added since the prior Pullfrog review.
- Fleet lifecycle: Added fleet-scoped and standing-broker operating models around Daytona's stop, start, and deletion behavior.
- Cost controls: Documented running and stopped billing, auto-stop handling, archival, and alternatives for brokers that must remain reachable.
azure/gpt-5.6-sol ｜ 𝕏
|
|
||
| Daytona has no wake-on-request: a stopped sandbox's ports are dead until something calls `start()` through the API, so an agent cannot wake the broker by connecting to it. Plan the broker's lifetime around that: | ||
|
|
||
| - **Fleet-scoped (what the code above does).** The orchestrator creates the broker, runs its agents, and deletes it. Compute is billed only while the fleet is up, and deleting the broker cascade-deletes its linked agents, so nothing is left running. This is the shape Daytona's billing fits best. |
There was a problem hiding this comment.
The fleet-scoped option says this is what the sample does, but the sample never deletes the broker and explicitly sets autoStopInterval: 0. Copying it leaves the broker running and billing after the workload finishes, so add reliable cleanup to the sample or remove this claim.
Technical details
# Fleet-scoped sample omits teardown
## Affected sites
- `packages/varlock-website/src/content/docs/sandboxes/daytona.mdx:96` - Disables automatic broker stop.
- `packages/varlock-website/src/content/docs/sandboxes/daytona.mdx:144-150` - Runs the agent but contains no broker cleanup.
- `packages/varlock-website/src/content/docs/sandboxes/daytona.mdx:184` - Claims the code deletes the broker.
## Required outcome
- Ensure the shown fleet-scoped flow deletes the broker after agents finish and also cleans it up when orchestration fails.
## Suggested approach
- Put the fleet work in a `try` block and call `await broker.delete()` from `finally`, following Daytona's documented deletion API: https://www.daytona.io/docs/en/sandboxes.md#delete-sandboxes.| Daytona has no wake-on-request: a stopped sandbox's ports are dead until something calls `start()` through the API, so an agent cannot wake the broker by connecting to it. Plan the broker's lifetime around that: | ||
|
|
||
| - **Fleet-scoped (what the code above does).** The orchestrator creates the broker, runs its agents, and deletes it. Compute is billed only while the fleet is up, and deleting the broker cascade-deletes its linked agents, so nothing is left running. This is the shape Daytona's billing fits best. | ||
| - **Standing broker.** Either keep it running (compute is billed continuously; see [Daytona's pricing](https://www.daytona.io/pricing)) or have the orchestrator `start()` and `stop()` it around fleet runs. A stopped broker costs only storage, and its sandbox id, link-network alias, and (with `--persist-ca`) CA all survive the stop/start cycle, but stopping is teardown for its linked agents, not a pause: ephemeral children are deleted when stopped. Also note a sandbox stopped for 7 days is archived by default, which makes the next start slower. |
There was a problem hiding this comment.
start() restores the filesystem but clears memory, so the proxy session launched earlier does not survive a stop. A standing broker restarted as described will retain its CA files but have no listening proxy; document and show the relaunch sequence required after every start.
Technical details
# Restart does not restore the proxy process
## Affected sites
- `packages/varlock-website/src/content/docs/sandboxes/daytona.mdx:114-123` - Creates the in-memory session, launches the proxy, and waits for readiness only during initial setup.
- `packages/varlock-website/src/content/docs/sandboxes/daytona.mdx:185` - Presents `start()` and `stop()` as a standing-broker lifecycle without process restoration.
## Required outcome
- Make the broker listen on port 8080 again after each stop/start cycle before creating or reconnecting agents.
## Suggested approach
- After `await broker.start()`, recreate the process session, rerun the proxy command, and repeat the readiness check. Daytona documents that stop preserves files but clears memory and running processes: https://www.daytona.io/docs/en/persistence.md#memory-persistence.1 participant
Adds a Daytona guide to the sandboxes section, following the E2B guide's skeleton, plus a docs-wide placeholder cleanup.
The broker topology was validated live against Daytona before writing. The recipe leads with Daytona's linked sandboxes: agents created with
linkedSandbox: broker.idshare an internal link network where the broker's sandbox id resolves as a hostname, sovarlock proxy run --url ws://<broker-id>:8080works with no public URL, preview token, or tunnel service, on every account tier. The guide covers:envVars(create-time env vars are visible to session commands, verified live)runAsyncfor the proxy daemon,autoStopInterval: 0for the broker)Uses the current
@daytona/sdkpackage name (re-validated end to end on 0.203.0). Also sweeps the docs so placeholder examples look like real keys: zero-padded full values instead of dot/ellipsis truncation, generated-fallback mentions spell outvlk_placeholder_<KEY>_<hash>, and the convention is codified in AGENTS.md.