Timeouts and auto-stop

timeout_sec is the active-session timeout, defaults to 3600 seconds, and accepts values from 1 through 86400. POST /api/v1/sandboxes/{id}/extend replaces that timeout; it does not add seconds to the previous value. An omitted extend body preserves the current timeout. Set always_on: true only when policy permits a sandbox to run until an explicit lifecycle action.

Auto-stop semantics

timeout_sec is a wall-clock TTL on the active session, not a countdown since the last command. At the deadline:

• A persistent sandbox (persistent: true, the default) stops its running session and moves to paused. The filesystem is preserved, so resume brings it back with /workspace and installed dependencies intact. Billing drops from the compute rate to the storage rate.
• A non-persistent sandbox (persistent: false) is destroyed, and the filesystem is discarded.

Activity that resets the idle clock (used by idle_timeout_sec) is separate from timeout_sec: exec calls, file writes, preview HTTP traffic, and terminal stdin all count.

Idle auto-pause and wake on request

idle_timeout_sec pauses a persistent sandbox after it has been idle, rather than at a fixed wall-clock deadline. It is off unless you set it; 0 disables it explicitly.

A paused persistent sandbox wakes on request: a request to its preview URL resumes it and is held until it is running, then continues. If the resume takes longer than the wait budget, the request returns 503 with Retry-After while the resume finishes in the background, so a retry finds the sandbox running. Authorization is checked first, so a private preview never wakes for anonymous traffic, and a request for a port that is not exposed does not wake the sandbox.

Sandbox usage

GET /api/v1/sandboxes/{id}/usage returns runtime_sec, provisioned_vcpu_ms, active_cpu_ms, network ingress and egress bytes, estimated cost, and timeout visibility. runtime_sec and provisioned_vcpu_ms are allocation measurements. Use measurement_status before interpreting active CPU or network values:

Provisioned resources are always reported with measurement_status.provisioned_resources: "measured". timeout_remaining_ms can be null before start or when timeout enforcement is disabled.