# Sandboxes (/web/sandboxes)



Sandboxes is the cross-repo runtime view for Mogplex previews.

In the app, this surface lives at `/spaces/sandboxes`. Use it when
[Projects](/web/spaces) is too repo-centric and you need to operate the
sandbox fleet directly.

A Sandbox is remote compute, not a Git checkout. A
[Worktree](/web/worktrees) is a separate task checkout inside selected Sandbox
compute. Starting a Sandbox does not create or increment a Worktree.

## Use Sandboxes when [#use-sandboxes-when]

* you need one list of live and pending sandboxes across repos
* a preview is stuck in creating or installing and you want manual override
* you need to open a workspace pinned to one specific sandbox instance
* you want to jump straight from a sandbox to health or observability
* you need to stop or remove stale sandbox records after the repo work moved on

If you are still choosing the repo or changing repo settings, start from
[Projects](/web/spaces). If you already know the failing call or job, move into
[Observability](/web/observability).

## What the page actually shows [#what-the-page-actually-shows]

The current page supports:

* search by repo, branch, preview URL, or status
* a status filter for **Live + pending** versus **All**
* status-first sorting, with running sandboxes shown before installing,
  creating, error, and older inactive records
* repo, working branch, base branch, preview URL, and last-activity cues
* direct actions for opening the workspace, opening health, stopping a
  sandbox, deleting the record, and refreshing the list

That makes it the operational answer to:

**Which preview runtime is actually alive right now?**

## What the main actions do [#what-the-main-actions-do]

### Open workspace [#open-workspace]

This opens a workspace session pinned to that sandbox and lands you back in the
main app with preview focus already attached to the chosen runtime.

Use it when the repo has more than one recent sandbox branch and you want to be
certain you are attaching to the right one.

### Health [#health]

This opens the same repo workspace pinned to that sandbox, but focuses the
preview health view instead of the normal preview tab.

Use it when the runtime exists but the preview still looks unhealthy.

### Observability [#observability]

Each sandbox can deep-link into [Observability](/web/observability) with the
repo and sandbox record preselected.

That is the path when you need the call, job, and cost trail behind a runtime
problem instead of only the preview state.

### Stop [#stop]

Use **Stop compute** for a Sandbox that should stop consuming runtime. Stop
removes compute, snapshots, sessions, and preview. It keeps the Sandbox record
in `stopped` state, so Control can restart the same record.

Worktree records and Git branches remain. Their checkouts are unavailable while
compute is stopped. Preserve important Git changes before Stop.

### Delete [#delete]

**Delete sandbox** removes compute, snapshots, sessions, preview, and the
Sandbox record.

Worktree records and Git branches remain, but their checkouts become
unavailable through that Sandbox. Use Delete for stale or broken records that
must disappear. Delete is not Stop.

## How Sandboxes relate to Worktrees [#how-sandboxes-relate-to-worktrees]

One Sandbox can host zero or more Worktrees. Each Worktree still owns a
different task ID, branch, and checkout path.

Sandbox lifecycle actions do not archive or prune Worktrees. Worktree actions
do not stop or delete Sandbox compute.

Use the separate **Sandboxes** and **Worktrees** tabs in Control. Their counts
measure different resources. Read
[Control Execution Environments](/guides/control-execution-environments) for
the complete decision table and lifecycle consequences.

## How Sandboxes relates to Projects [#how-sandboxes-relates-to-projects]

[Projects](/web/spaces) in Command Center is still where sandbox launch
usually begins.

Use Command Center when you need to:

* pick the repo
* change project settings like root directory, dev command, or environment
  variables
* start a mission without caring which sandbox instance backs it

Use Sandboxes when you already know the runtime is the thing you need to
inspect or control.

## Common situations [#common-situations]

### A preview never becomes healthy [#a-preview-never-becomes-healthy]

1. Open Sandboxes and filter to **Live + pending**.
2. Find the repo or working branch.
3. Open **Health** if the runtime exists but the preview looks wrong.
4. Open [Observability](/web/observability) if you need the linked call, job,
   or sandbox record details.

### A repo has multiple recent sandbox branches [#a-repo-has-multiple-recent-sandbox-branches]

Open Sandboxes instead of guessing from Projects. The list shows the working
branch directly, which is often the fastest way to tell which runtime matches
the work you care about.

### A sandbox is clearly stale [#a-sandbox-is-clearly-stale]

Use **Delete sandbox** when the record should disappear. Use **Stop compute**
when you want to halt the runtime and keep the record for restart.

## Failure modes that matter [#failure-modes-that-matter]

* **A repo exists but no sandbox row does**: the runtime likely never launched;
  go back to [Projects](/web/spaces) and start from the repo card.
* **A sandbox row exists but workspace open feels wrong**: open the workspace
  from the sandbox row so the session binds to the exact runtime you meant.
* **Preview is up but the run trail is still unclear**: jump to
  [Observability](/web/observability) from the sandbox context instead of
  debugging from the repo alone.
* **Delete feels destructive**: it is meant for stale or broken runtime
  records, not for routine day-to-day stop and start control.

## Read next [#read-next]

<Cards>
  <Card title="Control Execution Environments" href="/https/docs.mogplex.com/guides/control-execution-environments" />

  <Card title="Worktrees" href="/https/docs.mogplex.com/web/worktrees" />

  <Card title="Projects" href="/https/docs.mogplex.com/web/spaces" />

  <Card title="Observability" href="/https/docs.mogplex.com/web/observability" />
</Cards>
