Sandbox Runtime Lifecycle

Sandbox-backed apps separate the sandbox lifecycle from the commands that run inside it.

Core model

Start sandbox brings the sandbox environment online.
Start entrypoint is the app's primary long-running command, if one is defined.
Actions are one-off commands that can run and exit.
Services are additional background processes.
Preview only works when a process is listening on the declared port.

The sandbox can be online even when no app process is running. In that state, file operations, command execution, PTY, uploads, downloads, and actions can still work. A preview URL will not respond unless a process is serving traffic.

Template shape

Use start for the primary app process. Use actions for one-off jobs. Use services for additional background processes. Templates that do not serve traffic can omit the primary app start entrypoint and run only actions.

yaml

start:
  command: "bun run dev --host 0.0.0.0"
  ports:
    - port: 3000
      label: web
      path: /
  timeoutSeconds: 900

actions:
  - name: generate-report
    command: "bun run report"
    timeoutSeconds: 900
    artifactPaths:
      - artifacts/report.json

  - name: smoke-test
    command: "bun run test:smoke"
    timeoutSeconds: 300
    requiresStart: true

services:
  - name: worker
    command: "bun run worker"

Start sandbox

Starting a sandbox should:

Boot or restore the sandbox.
Make the sandbox agent reachable.
Start the template start.command as the internal entrypoint session when one is defined.
Open declared start.ports.
Mark the preview ready after the readiness check passes.

If no start.command is defined, the sandbox is still usable. It just has no app server running, so previews should stay closed until a process is listening on a port.

Actions

Actions do not require the app to be started by default.

Use normal actions for self-contained jobs:

yaml

actions:
  - name: export-csv
    command: "bun run export:csv"

Use requiresStart: true only when the action needs the app server or another start entrypoint side effect:

yaml

actions:
  - name: browser-smoke-test
    command: "bun run test:browser"
    requiresStart: true

When requiresStart is true, the runner should start the sandbox, run the start.command, wait for readiness, then run the action.

Services

Services are long-running processes beyond the primary start entrypoint. Use them for workers, queues, or support daemons.

Services should be explicit because they change runtime cost and cleanup behavior. Starting a sandbox should not automatically start every service unless the template or launch policy asks for it.

Schedules

Scheduled sandbox runs should target actions.

By default, a schedule should:

Create or restore a run sandbox from the snapshot.
Run the selected action.
Capture logs, artifacts, status, and receipts.
Stop, archive, or delete the run sandbox by policy.

If a scheduled action has requiresStart: true, the scheduler should start the app entrypoint and wait for readiness before running the action.