update docs to match new templates system, some fixes

[breardon2011]

Summary

Docs: Replace all references to the old Dockerfile-based Templates system with the current Image builder + Snapshots system.

Per-template golden snapshots: When a snapshot/image is built, the worker now captures a golden snapshot from the checkpoint cache. Subsequent Sandbox.create({ snapshot }) uses snapshot restore (~150ms) instead of cold boot (~10s).

Proxy readiness: The control plane proxy now blocks requests until async sandbox operations complete, instead of returning 500:

• Sandbox.create({ image/snapshot }) — exec blocks until VM finishes booting
• createCheckpoint — exec blocks until VM resumes after pause+snapshot
• restoreCheckpoint — exec blocks until restore completes (already worked via pendingCreates)

Changes

Docs (6 files)

• docs/sandboxes/templates.mdx — Full rewrite with CodeGroup tabs (TS/Python/curl) for both Image builder and Snapshots workflows
• docs/reference/api.mdx — Replace Templates section with Snapshots API, add image/snapshot fields to create sandbox endpoint, update route table
• docs/reference/typescript-sdk.mdx — Replace Templates with Image + Snapshots sections, add missing params to SandboxOpts
• docs/reference/python-sdk.mdx — Replace Template with Image + Snapshots sections, add missing params to Sandbox.create
• docs/how-it-works.mdx — Update Templates paragraph
• docs/guides/build-a-lovable-clone.mdx — Fix stale Dockerfile reference

Per-template golden snapshots (5 files)

• proto/worker/worker.proto — Add prepare_golden field to CreateCheckpointRequest
• internal/firecracker/snapshot.go — RegisterTemplateGoldenFromCache(): reflink-copies checkpoint cache files to golden dir (~1ms), createFromGoldenSnapshot() now checks per-checkpoint goldens
• internal/firecracker/manager.go — templateGoldens map on Manager, lookup in createWithID before cold boot
• internal/worker/grpc_server.go — Call RegisterTemplateGoldenFromCache from onReady callback when prepare_golden is set
• internal/api/image_builder.go — Set PrepareGolden: true on CreateCheckpoint during image builds
• pkg/types/sandbox.go — Add CheckpointID field to SandboxConfig

Proxy readiness + checkpoint blocking (3 files)

• internal/proxy/sandbox_api_proxy.go — waitForReady callback, blocks proxy until pendingCreates resolves
• internal/api/router.go — Wire waitForReady using existing pendingCreates sync.Map
• internal/api/sandbox.go — Register pendingCreates during createCheckpoint so exec blocks during pause; mark checkpoint ready immediately after gRPC returns (not after S3 upload)

Test results (dev.opensandbox.ai)

Default template:          ~700ms create, exec works
On-demand image (cold):    ~19s build
On-demand image (cached):  151ms (golden snapshot)
Named snapshot create:     ~16s build
Sandbox from snapshot:     156ms (golden snapshot)
Checkpoint + exec:         exec blocks during pause, succeeds
Restore + exec:            exec blocks 500ms, returns correct state
20/20 integration tests passed

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
opensandbox	Ready	Preview, Comment	Mar 13, 2026 8:41pm

[github-actions]

Preview Environment Destroyed

The preview environment dev-pr-68 has been torn down.
All AWS resources for this environment have been cleaned up.