Sandbox Lifecycles
Documentation and guides for OutcomeDev.
OutcomeDev uses an ephemeral compute model designed to maximize agent speed while protecting your runtime budget. This system relies on two core concepts: Sandboxes and Timeboxes.
Auto mode is the default. New tasks are created with Auto-manage sandbox enabled: the platform handles the entire lifecycle below for you, warm window on, keep-alive off, automatic stop, transparent wake-up on follow-ups. The granular controls described on this page apply when you switch a task to manual mode. See Autonomous Tasks & Self-Healing for the full picture.
1. The Task Sandbox
Every task you start is allocated a dedicated, isolated cloud VM (a Sandbox). This environment contains your code, dependencies, and any tools the agent needs to execute.
Sandbox States
- Active: The VM is powered on and the agent is actively executing.
- Warm (Idle): The agent has finished its current step, but the VM remains "hot" for about 2 minutes so you can review the live preview and fire a follow-up with an instant response. The window is presence-aware: if nobody has the task open when it finishes, the sandbox stops immediately instead of idling.
- Keep Alive: An optional mode where the VM stays hot indefinitely (until your budget runs out). Use this for complex, multi-step engineering sessions where state persistence is critical.
- Reclaimed: The VM has been powered down to save credits. Sending a new message will trigger a "Cold Start" (30-90 seconds to re-provision).
Ephemeral vs. Persistent
By default, sandboxes are ephemeral: when the machine is reclaimed, its disk is discarded entirely — nothing is retained by the compute provider. Your work is always safe because the agent pushes code to your branch before the task completes; the sandbox is just the workbench, not the vault.
Checking Persistent Sandbox in Task Options changes that: the workspace disk is snapshotted when compute stops and restored on your next task in that workspace, so the environment (cloned repo, installed dependencies, build caches) survives without re-cloning or re-installing. Compute still stops between sessions — you're keeping the disk, not paying for an idle VM.
Persistent workspaces expire after 30 days without use. Every use resets the timer, so an active workspace never expires. If a workspace does expire, nothing breaks: the next task in it simply starts from a fresh clone. You can see each workspace's expiry countdown in the Sandboxes panel.
2. The Task Timebox
The Timebox is your safety valve. It represents the maximum amount of compute time allocated to a specific task.
How Billing Works
- Live VM = Billed Time: As long as a Sandbox is active or in a "Warm" state, it consumes your runtime budget.
- Idle Charging: The warm window is billed because it provides a significant performance benefit for follow-up interactions. Because it's presence-aware, you're only paying for warmth while you're actually there to use it.
- Stopping: You can freeze your budget at any time by clicking "Stop Sandbox" in the task interface. This immediately reclaims the VM and stops the clock.
3. Best Practices
- Use Keep Alive for R&D: When you are iterating rapidly on a complex feature, Keep Alive prevents the delay of cold starts.
- Manual Stop for Efficiency: If you know you won't be following up on a task for a while, stop the sandbox manually to preserve your credits.
- Cold Starts are Free: You are never billed for the time it takes to provision a new sandbox or clone your repository. Billing only begins once the agent starts working.
By combining ephemeral sandboxes with precise timeboxing, OutcomeDev ensures you only pay for the compute you actually use to reach your desired result.