> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.aosplane.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.aosplane.io/_mcp/server.

# Sandboxes

A **sandbox** is an isolated cloud machine where a session's coding agent works, with its own files, software, processor, memory and disk. Every session gets a sandbox on its own, so you only open the **Sandboxes** tab to pick a size, keep a workspace running for longer work, or share one sandbox between several sessions.

> **Note**
>
> Owners, Admins and Engineers can create, stop, resume and snapshot sandboxes. Viewers and Billing can only look.

## Find a project's sandboxes

Open the project and choose the **Sandboxes** tab. The top counts what's **Running** and **Starting**, the **Total**, and your **Snapshots**.

![Sandboxes tab with the Running, Starting, Total and Snapshots counts, the All, Running, Stopping and Stopped filters, a search box and a list of sandboxes](/_fern-files/_img/598c8d83ed2f5292276a17ee217e7acc2dbaa5af15aa24384d23d7f10afb9cc7.webp)

* Filter with **All**, **Running**, **Stopping** or **Stopped** (failed sandboxes are under **Stopped**), search by name or ID, and sort by **Recent activity**, **Newest created** or **Name A–Z**.
* Each row shows the **Status**, **Size**, **CPU now**, **Memory**, **Activity**, **Sessions** and **Region**. Its **⋯** menu has **Stop**, **Resume** or **Start again**.
* Select a row to open the sandbox's page.

## Create a sandbox

#### Open the form

On the **Sandboxes** tab, choose **New sandbox**.

#### Name it and pick a source

Enter a **Name**. Under **Workspace source**, keep **Default image** or pick a snapshot to start with its repositories and dependencies already on disk.

#### Choose its size

Pick a **Size** and **Storage**. Every session in the sandbox shares this capacity, and you can't change it later.

#### Choose when it stops

Set the **Sandbox lifetime** and **Idle timeout**, and keep **Snapshot workspace when it stops** on if you want to resume it later.

#### Create it

Check the **Review** summary and choose **Create sandbox**.

![Create sandbox panel with Name, Workspace source, the Shrimp, Tuna, Shark and Whale sizes, Storage and the lifecycle options](/_fern-files/_img/191f48b59599447f49a5fe86f15ec9647211938ca8823d53018ef7df1a0427e5.webp)

| Size       | vCPU | Memory | Default disk | Plans          |
| ---------- | ---- | ------ | ------------ | -------------- |
| **Shrimp** | 4    | 8 GiB  | 40 GiB       | All plans      |
| **Tuna**   | 8    | 16 GiB | 120 GiB      | Starter and up |
| **Shark**  | 16   | 32 GiB | 200 GiB      | Team and up    |
| **Whale**  | 32   | 64 GiB | 250 GiB      | Enterprise     |

Your plan also caps the disk of one sandbox (40 GiB on Free, 120 GiB on Starter, 250 GiB on Team, 500 GiB on Enterprise) and how many sandboxes can be active in a project at once (2, 8, 32, or custom on Enterprise). Stopped sandboxes don't count. See [Billing and plans](/billing).

### Automatic shutdown

* **Idle timeout**: stop after **15 minutes**, **30 minutes** (the default), **1 hour** or **2 hours** without activity, or never (**No idle shutdown**). Sandboxes that sessions create stop after 30 minutes without activity, and wake up again when you send the session a message.
* **Sandbox lifetime**: stop after **1 hour**, **2 hours**, **4 hours** or **8 hours** in total. On Free, a sandbox runs for 1 hour at most.
* **Snapshot workspace when it stops**: on by default. The files are saved so you can resume. Off, stopping deletes the workspace.

## Work with a sandbox

The sandbox's page shows its status, **Sessions**, **Uptime**, **Size** and **Storage**, with the **Overview**, **Sessions**, **Usage** (CPU, memory and disk charts) and **Snapshots** tabs.

![Sandbox page with the New chat, Snapshot, Keep awake and Stop buttons, the Sessions, Uptime, Size and Storage figures, and the Overview tab](/_fern-files/_img/f52ae891c6d740108ed1b0d769ee37958113c59c8f019746f4df008074484464.webp)

* **New chat** starts another session in this sandbox, in a new browser tab.
* **Snapshot** saves the workspace while the sandbox keeps running. Give it a **Snapshot name** and choose **Snapshot sandbox**.
* **Keep awake** stops the idle timeout for **1 hour**, **8 hours** or **24 hours**. You're billed while it's awake.
* **Idle limit**, under **Configuration** on the **Overview** tab, changes the idle timeout of a running sandbox.
* **Update** appears when a newer sandbox version is out. It restarts the sandbox with your files in about a minute.

### Stop a sandbox

Choose **Stop**, type the sandbox ID shown, and choose **Stop sandbox**. Leave **Take a snapshot before stopping** checked to keep the files: the sessions in it pause and carry on when you choose **Resume**. Without a snapshot, the workspace is deleted, the sessions end, and changes that weren't pushed are lost. Conversations are kept either way.

Stopping a sandbox affects every session in it. Stopping one session leaves its sandbox running. A failed sandbox shows **Start again** instead of **Resume**.

### Snapshots

The **Snapshots** tab on the **Sandboxes** page lists every snapshot with its source sandbox, size and status (**Creating**, **Ready**, **Failed** or **Deleting**). Its **⋯** menu has **New sandbox from snapshot** and **Delete…** (type the snapshot's name to confirm). A stopped sandbox can't resume once the snapshot it would resume from is deleted.

## Look inside a session's sandbox

On a session's page, two buttons at the top right open the sandbox.

### Terminal

**Terminal** (<kbd>Ctrl</kbd>+<kbd>\`</kbd>) opens a command line in the sandbox under the chat, running as you. **New terminal** adds tabs (up to 8) and **Full page** opens it on its own page. People's terminal sessions are recorded in [Activity](/activity#replay-a-terminal-session).

### Workbench

**Workbench** (<kbd>Cmd</kbd>+<kbd>Option</kbd>+<kbd>B</kbd> on macOS, <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>B</kbd> elsewhere) opens a side panel with the session's views.

![Workbench panel beside the chat with Open a panel listing Changes, Desktop, Tasks, Files, Artifacts, Ports, Memory, Usage details and Terminal](/_fern-files/_img/5c9c821eac17f403eff296e9099de34c791172a342e70db748334b262061640d.webp)

| View                          | What it shows                                                                                                                |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| **Changes**                   | The agent's changes, file by file. See [Changes and pull requests](/session-changes).                                        |
| **Desktop**                   | The sandbox's screen, for apps such as a browser. Choose **Connect** to view and control it, or **Open in new tab**.         |
| **Files**, **Artifacts**      | The sandbox's files, and plans or documents the agent wrote for you.                                                         |
| **Tasks**, **Subagents**      | The agent's to-do list and background work, and helper agents it started.                                                    |
| **Ports**                     | Web servers running in the sandbox. **Expose** one to get a link. Links are **Private** unless you switch one to **Public**. |
| **Memory**, **Usage details** | The memories the agent is using, and what the session has used and spent.                                                    |

## Good to know

* Sessions in one sandbox share its files and capacity, and pause or end together when it stops.
* If AOSplane set a custom spec for your organization, the form shows **Custom spec** instead of sizes. Contact support to change it.
* Viewers and Billing can't open the terminal or the desktop, or expose ports.

## Related

* [Start a session](/start-a-session)
* [Stop a session](/stop-a-session)
* [Activity](/activity)