diff --git a/docs.json b/docs.json index 0ffb5bb..fc33300 100644 --- a/docs.json +++ b/docs.json @@ -58,6 +58,8 @@ "pages": [ "features/sandbox/overview", "features/projects", + "features/sandbox/computer", + "features/sandbox/keep-alive", "features/sandbox/custom-dependencies", "features/sandbox/environment-variables" ] diff --git a/features/sandbox/computer.mdx b/features/sandbox/computer.mdx new file mode 100644 index 0000000..7ddd9c1 --- /dev/null +++ b/features/sandbox/computer.mdx @@ -0,0 +1,65 @@ +--- +title: 'Computer' +description: 'Watch and control the sandbox desktop while a session runs.' +--- + +The **Computer** tab streams the Linux desktop running inside your session's [sandbox](/features/sandbox/overview) into the Tembo dashboard. Use it to watch what an agent is doing in a browser or editor, and to take over with your own mouse and keyboard when you want to drive the environment yourself. + +The desktop runs in the same VM as the agent, so both see the same `/workspace`, the same installed [dependencies](/features/sandbox/custom-dependencies), and the same [environment variables](/features/sandbox/environment-variables). + +## Prerequisites + +- The session runs in a VM sandbox. +- The VM is running. If it has stopped, send a message in the session to start it again. + +## Open the Computer tab + +1. Open a session in the [dashboard](https://app.tembo.io). +2. In the session's right sidebar, select **Computer**. + +The sidebar also holds **Changes**, **Artifacts**, **Files**, **Terminal**, and **VM logs**. In the expanded view these open as tabs, so you can keep the desktop next to a diff or a terminal. + +## What's on the desktop + +A dock at the bottom of the desktop launches the tools bundled into the sandbox image: + +| Dock item | Application | Opens | +|-----------|-------------|-------| +| Menu | Ulauncher | Application search | +| Browser | Chromium | `about:blank` | +| Files | PCManFM | `/workspace` | +| Code | Visual Studio Code | `/workspace` | +| Terminal | Ghostty | `/workspace` | + +Because agents drive this same desktop, browser automation and other GUI work show up live in the preview. + +## Copy and paste + +The stream carries the clipboard in both directions, so you can copy text out of the sandbox desktop and paste your own text into it using your normal keyboard shortcuts. + +## Copy or refresh the preview URL + +While the **Computer** tab is open, two buttons appear in the sidebar header: + +- **Copy computer URL** copies the preview URL so you can open the desktop in its own browser tab. +- **Refresh computer URL** re-establishes the tunnel to the desktop. Use it if the stream looks stale or blank. + + + The preview URL changes whenever the tunnel restarts. A URL you copied earlier stops working after a refresh or after the VM restarts — copy it again. + + +## Preview states + +| State | What it means | +|-------|---------------| +| **Computer is booting up** | The VM is still starting. The message names the current boot phase. | +| **Refreshing computer URL** | A refresh is in flight. The preview reloads when the new URL is ready. | +| **Computer unavailable** | The session has no running VM. The preview appears once a VM is running. | + +After the VM reports as running, the desktop stream can take up to about a minute to become available. Tembo keeps polling for it in the background and reloads the preview automatically. + +## Constraints + +- The desktop is streamed at 60 FPS from inside the sandbox. Throughput depends on your network connection to the tunnel. +- Docker-based sandboxes do not run a desktop, so the **Computer** tab stays unavailable for them. +- The desktop is part of the sandbox, so the stream ends when the VM stops. Extend the session's [keep-alive window](/features/sandbox/keep-alive) if you want the desktop to stay up after the agent finishes. diff --git a/features/sandbox/keep-alive.mdx b/features/sandbox/keep-alive.mdx new file mode 100644 index 0000000..b6c5438 --- /dev/null +++ b/features/sandbox/keep-alive.mdx @@ -0,0 +1,79 @@ +--- +title: 'Keep Alive' +description: 'Control how long a session sandbox keeps running after the agent finishes.' +--- + +A session's [sandbox](/features/sandbox/overview) VM does not stop the moment an agent finishes. Tembo holds it open for a short keep-alive window so you can read the diff, run commands in the terminal, or drive the [Computer](/features/sandbox/computer) desktop. When the window expires, Tembo stops the VM. + +Keep-alive is what you extend when you want more time in a live sandbox — and what to watch when a sandbox disappears sooner than you expected. + +## Default windows + +Each time work completes in a session, Tembo pushes the stop time out based on where the work came from: + +| Where the work came from | Keep-alive after it finishes | +|--------------------------|------------------------------| +| Dashboard session or chat message | 10 minutes | +| Slack message or reply | 5 minutes | +| Scheduled or triggered [agent](/features/agents) | 1 minute | + +These automatic extensions only ever move the stop time later. They never shorten a longer window you set yourself. + + + Self-hosted deployments can change the dashboard and Slack windows with the `SANDBOX_KEEP_ALIVE_APP_MINUTES` and `SANDBOX_KEEP_ALIVE_SLACK_MINUTES` environment variables. See [Self-hosted](/features/self-hosted/overview). + + +## An open session tab holds the VM open + +While a session is the active tab and your browser window is focused, the dashboard sends a keep-alive heartbeat every 4 minutes that pushes the stop time 10 minutes out. You do not need to do anything to keep a sandbox alive while you are actively looking at it. + +Switching tabs, backgrounding the window, or closing the session stops the heartbeat, so the VM stops roughly 10 minutes later. + +## Extend from the composer + +To hold a sandbox open for longer than the default window: + +1. Type `/` in the session composer. +2. Select **Keep alive**. +3. Choose **10 minutes**, **1 day**, or **1 week**. + +A checkmark marks the window that is currently in effect. If the session has no running VM, the option reads **No active VM** and cannot be selected. + + + Choosing a duration sets the window from now, so it can shorten an existing one. Selecting **10 minutes** while a 1 week window is active leaves 10 minutes, not a week and 10 minutes. + + +## Extend from inside the sandbox + +Run the `tembo` CLI from a session terminal, a [hook](/features/hooks), or a script: + +```bash +tembo set-vm-keep-alive 3600 +``` + +The argument is a positive whole number of seconds. The command prints the new window: + +```json +{ + "vmId": "3f8a1c52-9d4e-4b7a-8f21-6c0b5d2e7a94", + "seconds": 3600, + "keepAliveUntil": "2026-01-01T12:00:00.000Z" +} +``` + +The command fails if the session has no VM or if its VM is no longer running. + +Agents running in a session can do the same thing through Tembo's own MCP server, which exposes a `setVmKeepAlive` tool taking the same `seconds` argument. That is what an agent reaches for when you ask it to keep the sandbox up while you take a look. + +## When the window expires + +Tembo does not discard the sandbox outright. It suspends the VM, captures a session snapshot, then stops it. When the session needs a VM again — for example because you send another message — Tembo resumes from that snapshot instead of cloning and installing from scratch, falling back to the [project](/features/projects) environment and then to a cold boot if the snapshot cannot be restored. + +Tembo also skips stopping a VM that still has active agent work, even if the window has technically expired. + +## Constraints + +- Keep-alive applies to VM sandboxes and requires the VM to be running. +- A VM that stays alive keeps consuming compute for the whole window, billed at the hourly rate for its [sandbox size](/resources/pricing#cloud-vm-compute-rates). A 1 week keep-alive on a large sandbox is expensive — prefer the shortest window that covers what you need. +- Only one window is in effect at a time. Setting a new one replaces the previous value rather than adding to it. +- The keep-alive window controls how long the VM stays up, not how long the session lasts. Sessions and their history remain available after the sandbox stops. diff --git a/features/sandbox/overview.mdx b/features/sandbox/overview.mdx index c55afe2..a96d067 100644 --- a/features/sandbox/overview.mdx +++ b/features/sandbox/overview.mdx @@ -5,6 +5,8 @@ description: 'Secure, isolated environments where coding agents execute sessions Every session runs in its own isolated sandbox. Sandboxes are ephemeral: spun up for the session, destroyed when it's done. No code or state persists after execution. +While a sandbox is running you can watch and control its desktop from the [Computer](/features/sandbox/computer) tab, and use [keep alive](/features/sandbox/keep-alive) to hold it open after the agent finishes. + ## Data handling Your repository is cloned into the sandbox for the duration of a session and torn down when the session ends — no repository contents or working state persist afterward. @@ -15,7 +17,7 @@ Model providers handle prompt data according to their own retention policies — ## Sandbox sizes -Tembo offers five sandbox sizes. Each session runs in a dedicated Linux VM, and no two sessions share the same VM. +Each session runs in a dedicated Linux VM, and no two sessions share the same VM. | Size | vCPU | Memory | Disk | |------|------|--------|------| @@ -24,10 +26,12 @@ Tembo offers five sandbox sizes. Each session runs in a dedicated Linux VM, and | Medium | 4 | 8 GB | 50 GB | | Large | 8 | 16 GB | 100 GB | | XL | 16 | 32 GB | 200 GB | +| XXL | 16 | 64 GB | 200 GB | +| Ultra | 32 | 128 GB | 200 GB | Micro and Medium are best for routine code analysis, fixes, features, and reviews. Large and XL are best for heavier builds, integration tests, Docker workloads, large repositories, or multi-container setups. -Need more than 32 GB of RAM? Contact [support@tembo.io](mailto:support@tembo.io) to request access. +Your plan sets the largest size you can select — see [Plans](/resources/pricing#plans). XXL and Ultra are not included in a standard plan; contact [support@tembo.io](mailto:support@tembo.io) to request access. VM sandboxes include full nested virtualization for Docker-in-Docker and provide a stronger isolation boundary.