docs(sandbox): document Computer preview and VM keep-alive

[tembo]

Docs added/updated

Added

• features/sandbox/computer.mdx — the Computer tab: what it streams, the desktop dock (Ulauncher, Chromium, PCManFM, VS Code, Ghostty) and the paths each opens, bidirectional clipboard, the copy/refresh preview-URL controls, the four preview states, and the constraints (60 FPS, no desktop on Docker sandboxes, stream ends with the VM).
• features/sandbox/keep-alive.mdx — how long a sandbox stays up: default windows per work source, the focused-tab heartbeat, the composer / option, the tembo set-vm-keep-alive CLI, the setVmKeepAlive MCP tool, suspend-and-snapshot on expiry, and the compute-cost constraint.

Updated

• features/sandbox/overview.mdx — added XXL and Ultra rows to the sandbox size table, replaced the "more than 32 GB of RAM" line with a pointer to plan limits on the pricing page, and linked the two new pages.
• docs.json — added both pages to Features → Sandbox.

Codepaths covered

Doc claim	Source
Default keep-alive per source (dashboard 10m, Slack 5m, background agent 1m); never shortens a longer window	apps/api/src/agent/sandbox/keepAlive.ts, apps/api/src/config.ts (sandbox.keepAlive.*)
Focused-tab heartbeat every 4 min pushing the stop time 10 min out	apps/web/hooks/use-vm-keep-alive-activity.ts, POST /virtual-machine/:id/touch-keep-alive
Composer durations (10 minutes / 1 day / 1 week), "No active VM" state, absolute-from-now semantics	apps/web/components/composer/slash-menu/keep-alive-scope.tsx, session-options.tsx, use-composer-keep-alive.ts
tembo set-vm-keep-alive <seconds>, JSON output, error cases	apps/api/src/agent/guest/cli/commands/setVmKeepAlive.ts, packages/agent-runtime/src/runtime/tools/setVmKeepAlive.ts
setVmKeepAlive MCP tool	apps/api/src/server/routes/public-api/mcp.ts
Suspend + session snapshot on expiry; restore order session snapshot → golden → cold boot; busy VMs are skipped	apps/api/src/agent/manager/stopExpiredKeepAliveVMs.ts, tasks/vm_stop.ts, tasks/vm_start.ts
VM runtime is metered per running interval	apps/api/src/services/vmRuntimeUsage.ts
Computer preview enabled only for VM sandboxes; ~1 min of polling after boot	apps/api/src/agent/sandbox/sandboxes/vm.ts, apps/api/src/agent/sandbox/tools.ts, config.ts (sandbox.computerPreview.*)
Preview states and their copy	apps/web/components/session/workspace/computer/preview-state.ts, booting-state.tsx, unavailable-state.tsx
Copy/refresh URL buttons (both ungated in the sidebar header)	apps/web/components/session/workspace/sidebar-header/{copy,refresh}-computer-url-button.tsx
Sidebar tabs and labels	apps/web/components/session/workspace/sidebar-pages.tsx
Dock applications and the paths they open; 60 FPS; bidirectional clipboard	nix/sandbox/guest/computer-preview/{desktop,selkies,default}.nix, nix/sandbox/tembo-enable-computer.nix
Sandbox sizes incl. XXL (16/64 GB) and Ultra (32/128 GB); plan max sizes	apps/api/src/config.ts (sandbox.sizes.*), packages/shared/src/entitlements.ts

Key knowledge gaps addressed

• Sandbox lifetime was undocumented. Nothing explained why a sandbox is still reachable minutes after an agent finishes, or why it disappears — a common source of "my sandbox vanished" confusion. Both the automatic windows and every way to extend them are now written down, including that selecting a duration replaces rather than adds to the current window.
• The Computer tab had zero docs despite a large amount of recent work on it. Users had no way to learn that a full Linux desktop with a browser, editor, and terminal is available, that the clipboard works both ways, or what to do when the stream goes blank (refresh the URL).
• Cost of keeping a VM alive was not connected to the pricing page; a 1-week keep-alive bills compute for the whole week.
• Size table drift: the overview listed five sizes while the pricing page already published XXL rates, and it stated a 32 GB ceiling that no longer reflects available sizes.

Verified with mintlify broken-links (no broken links) and docs.json JSON validation.

Want tembo to make any changes? Add a comment with @tembo and i'll get back to work!

      

---

Note

Low Risk
Documentation-only changes with no runtime or security impact; content was cross-checked against existing product behavior and pricing.

Overview
Adds Computer and Keep alive docs under Features → Sandbox and wires them into docs.json navigation.

The new Computer page explains the session sidebar desktop stream (dock apps, bidirectional clipboard, copy/refresh preview URL, boot/unavailable states, VM-only and keep-alive constraints). Keep alive documents default post-work windows by source, the focused-tab heartbeat, composer / extensions, tembo set-vm-keep-alive / MCP setVmKeepAlive, suspend-and-snapshot on expiry, and compute billing caveats.

Sandbox overview now links to both pages, adds XXL and Ultra to the size table, and points plan limits at pricing instead of the old 32 GB RAM contact line.

^{Reviewed by Cursor Bugbot for commit 062fee9. Bugbot is set up for automated code reviews on this repo. Configure here.}

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
tembo	🟢 Ready	View Preview	Aug 28, 2026, 8:15 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[tembo]

Requesting review from @benja who has experience with the following files modified in this PR:

• docs.json

[tembo]

A few blockers before this should merge:

1. features/sandbox/computer.mdx says the agent and desktop see the same environment variables. Workspace/project variables are injected into agent runtime commands and related execution paths; the desktop systemd service receives only its limited desktop environment. Please remove or narrow the environment-variable claim.

2. The new snapshot documentation conflicts with features/sandbox/overview.mdx, which still says “No code or state persists after execution” and that no working state persists afterward. Keep-alive expiry now creates a temporary session snapshot that can restore working state. Please update the overview language so the pages do not contradict each other.

3. Release gate: the focused-tab heartbeat documented here shipped in tembo/monorepo#10838 on August 27. It is not in the latest published release (v0.2.828) and currently appears only in draft v0.2.829. Please hold this docs PR until a containing release is published and its production deployment succeeds.

The remaining documented behavior—including default windows, composer durations, CLI/MCP controls, snapshot fallback order, billing, preview states, and XXL/Ultra specifications—matches the implementation.