Projects, Sandboxes, and Worktrees
Understand how Projects connect repository context to Sandbox compute and task-specific Worktree checkouts in Control.
Projects, Sandboxes, and Worktrees form the repo execution layer of the app.
Use Projects when you are choosing or configuring a repo. Use Sandboxes when the runtime itself is the thing you need to inspect or control. Use Worktrees when one planned task needs an isolated Git checkout.
Mental model
| Term | Meaning |
|---|---|
| Repo | The imported GitHub repository Mogplex knows about |
| Project | The app grouping layer shown as Projects at /spaces |
| Workspace session | The live repo session you open from the app |
| Sandbox | The runtime and preview environment attached to repo work |
| Worktree | A task-specific branch and checkout bound to one Sandbox |
This split matters because repo visibility, workspace launch, and sandbox health are related but not identical.
Starting a Sandbox does not create a Worktree. One Sandbox can host multiple Worktrees with separate tasks, branches, and checkout paths.
Use Projects when
- syncing repos or checking whether the right repo is visible
- searching and organizing repo cards
- opening a workspace
- configuring root directory, install command, dev command, dev port, env mapping, timeout, secrets, or snapshot state
- creating repo-bound assignments or cron-backed work
- choosing a sub-project inside a monorepo
Projects is where sandbox launch usually begins because the repo card has the repo settings needed to start the right runtime.
Use Sandboxes when
- you need one cross-repo list of live and pending previews
- a runtime is stuck creating, installing, unhealthy, stale, or attached to the wrong branch
- you need to open a workspace pinned to a specific sandbox instance
- you need manual Stop or Delete controls
- you want to jump from a runtime to health or observability
Sandboxes is the operational runtime list. It answers:
Which preview is actually alive right now?
Use Worktrees when
- one planned coding task needs an isolated branch and checkout
- several coding tasks must run in parallel without sharing files
- you need the persisted Diff or Rebase action for one task
- you need to Archive a checkout without removing it
- you need to Prune an archived checkout without deleting its branch or Sandbox
Worktrees answers:
Which checkout belongs to this task, and where does it run?
Use Control Execution Environments for the outcome-based decision table and all lifecycle consequences.
Common paths
First repo setup
- Confirm GitHub coverage in Installations.
- Sync and find the repo in Projects.
- Set root directory, dev command, preview port, optional Vercel metadata, or env mapping if needed.
- Open the workspace or start preview from the repo card.
Broken preview
- Find the runtime in Sandboxes.
- Open Health if the runtime exists but the preview is unhealthy.
- Open Observability from sandbox context when you need run, call, cost, or tool detail.
- Stop or delete stale runtimes only when the current state supports it.
Monorepo work
Use Projects to create sub-project entries or set root_directory,
dev_command, and dev_port explicitly. Do not rely on one repo root when the
actual app lives under a package or app directory.
Billing and Vercel relationship
Sandbox access is billed through Mogplex. Optional linked Vercel project metadata can still matter for preview env sync or project-specific settings. If sandbox launch fails after repo setup, confirm Plans & Billing and Vercel before editing routing or agent behavior.