How AutoPause and AutoResume Work for Idle Sandbox Cost Optimization in CubeSandbox

CubeSandbox automatically pauses idle sandboxes after a configurable timeout to eliminate CPU and memory costs, then transparently resumes them on the next request by restoring a frozen snapshot.

CubeSandbox implements intelligent idle sandbox cost optimization through its AutoPause and AutoResume mechanisms. When a sandbox remains inactive for a specified duration, the platform captures a complete snapshot of its runtime state—including memory, filesystem, and CPU registers—and instantly reclaims compute resources, reducing operational costs to near zero while maintaining instant availability.

Sandbox Lifecycle States

The CubeSandbox platform manages sandboxes through a deterministic state machine defined in docs/guide/lifecycle.md. Understanding these states is essential to grasp how AutoPause achieves zero resource consumption during inactivity.

• running: The sandbox actively executes code and consumes allocated CPU and memory resources.
• pausing: An intermediate state where the platform captures a complete snapshot of the sandbox's runtime state.
• paused: The snapshot resides on disk with zero CPU and memory footprint, incurring only storage costs.
• resuming: The system restores the snapshot from disk back into active memory.
• terminated: The sandbox is permanently destroyed and cannot be revived.

Configuration Settings That Drive AutoPause and AutoResume

Three primary settings control the automatic pause and resume behavior. These parameters are defined in the JSON schema at cube-lifecycle-manager/internal/lifecycle/schema.go and processed by the HTTP handler in CubeAPI/src/services/sandboxes.rs.

• timeout: Specifies the idle duration in seconds before triggering an action. If omitted, the server applies a default value or disables automatic management.
• on_timeout: Determines the action when the timeout expires. Set to "pause" to enable AutoPause (instead of the default "kill" which destroys the sandbox).
• auto_resume: A boolean flag that, when true, allows any incoming request to automatically trigger the resume process for a paused sandbox. When false, the sandbox remains paused until explicitly awakened via Sandbox.connect().

The Go struct definitions in CubeMaster/pkg/service/sandbox/types/types.go mirror these fields as AutoPause and AutoResume for internal service communication.

How AutoPause Works: From Idle Detection to Resource Reclamation

AutoPause operates through a coordinated sequence across CubeMaster, Redis, and the node-level CubeProxy.

Idle detection occurs whenever the SDK executes operations like run_code, files.read/write, or any inbound HTTP traffic hits the sandbox. This activity resets the internal idle clock.

After timeout seconds of inactivity, CubeMaster publishes a pause event to Redis, which the cube-lifecycle-manager service consumes. The lifecycle manager, implemented in cube-lifecycle-manager/internal/resumer/resumer.go, instructs CubeProxy to initiate the snapshot process.

CubeProxy freezes the VM's memory and serializes the complete runtime state to a storage-backed snapshot. Once the snapshot completes, the transition from pausing to paused occurs, and the node immediately reclaims CPU and memory resources.

By default, paused sandboxes continue counting against scheduling quotas. However, administrators can enable partial quota release by configuring host.quota.paused_resource_release_ratio in Cubelet/config/config.toml. Setting this to 0.5, for example, returns half of the paused sandbox's resource allocation to the available node capacity.

How AutoResume Works: Transparent Restoration on Demand

When a paused sandbox receives any request—whether HTTP traffic, code execution, or file operations—the AutoResume process activates instantly.

CubeProxy detects the incoming request and validates that auto_resume is enabled for the target sandbox. Upon confirmation, it issues a resume RPC to the control plane, triggering the restoration of the frozen snapshot from disk into active memory.

The sandbox transitions through resuming to running, and the request proceeds as if the sandbox had never been interrupted. This seamless restoration typically completes fast enough that callers experience no perceptible delay.

If the node lacks sufficient capacity to accommodate the restored sandbox—particularly when paused_resource_release_ratio freed resources that were subsequently allocated elsewhere—the resume operation returns a 409 Conflict error. The SDK treats this as a retriable condition, allowing for graceful handling of resource contention.

Timeout Reset and Continuous Optimization

Every successful AutoResume resets the idle timeout countdown to its full duration. This enables sandboxes to cycle indefinitely between active execution and zero-cost paused states without manual intervention, continuously optimizing infrastructure costs based on actual utilization patterns.

Implementing AutoPause and AutoResume in Practice

Python SDK Configuration

Create a sandbox that automatically pauses after five minutes of inactivity and transparently resumes on the next request:

from cubesandbox import Sandbox

# Create a sandbox with auto-pause enabled

sandbox = Sandbox.create(
    template="my-template",
    timeout=300,                     # 5 min idle timeout

    lifecycle={
        "on_timeout": "pause",       # pause instead of kill

        "auto_resume": True,        # transparently resume on next request

    },
)

# If idle for 5 min, sandbox auto-pauses. This call triggers auto-resume if needed.

result = sandbox.run_code("print('hello from resumed sandbox')")
print(result)

Manual Pause and Resume Control

For explicit lifecycle management outside of automatic triggers:

sandbox = Sandbox.create(template="my-template")

# Manually trigger snapshot and pause

sandbox.pause()

# Manually resume from snapshot

sandbox.connect()

# Execution continues from preserved state

sandbox.run_code("print('back')")

Node-Level Quota Tuning

Adjust the scheduler behavior for paused sandboxes by editing Cubelet/config/config.toml:

# Cubelet/config/config.toml

[host.quota]
paused_resource_release_ratio = 0.5   # release 50% of paused sandbox resources

This configuration allows the node to reclaim half of the CPU and memory quota from paused sandboxes, increasing capacity for active workloads while retaining the ability to resume the frozen instances.

Summary

• AutoPause freezes sandboxes to disk after a configurable timeout, eliminating CPU and memory costs while preserving complete runtime state.
• AutoResume restores snapshots transparently when requests arrive, with logic implemented in cube-lifecycle-manager/internal/resumer/resumer.go.
• Configuration requires setting lifecycle={"on_timeout": "pause", "auto_resume": True} during sandbox creation.
• Resource quotas can be partially released via paused_resource_release_ratio in Cubelet/config/config.toml to optimize node utilization.
• Failed resumes due to capacity constraints return 409 Conflict, which the SDK handles as a retriable error.

Frequently Asked Questions

What happens to in-memory data when a sandbox auto-pauses?

When AutoPause triggers, CubeProxy captures a complete snapshot of the sandbox's runtime state, including memory contents, CPU registers, and filesystem state, into a storage-backed frozen image. This snapshot preserves all in-memory data and execution context exactly as it existed at the pause moment, allowing seamless restoration during AutoResume without data loss.

Can AutoResume fail, and how does the SDK handle it?

AutoResume can fail if the node lacks sufficient capacity to restore the sandbox, particularly when paused_resource_release_ratio has allocated the released resources to other workloads. In this scenario, the control plane returns a 409 Conflict error, which the SDK interprets as a retriable condition, automatically attempting the resume operation again after a brief backoff period.

How does paused_resource_release_ratio affect cost versus scheduling?

The paused_resource_release_ratio setting in Cubelet/config/config.toml controls scheduling quota reclamation rather than direct billing metrics. While paused sandboxes inherently consume zero CPU and memory resources, this ratio determines what percentage of the sandbox's resource allocation returns to the node's available scheduling capacity, allowing denser packing of active workloads while maintaining the ability to resume paused instances.

Is there a time limit for how long a sandbox can stay paused?

CubeSandbox imposes no explicit time limit on the paused state duration; sandboxes can remain paused indefinitely as long as the underlying snapshot storage persists and the sandbox is not explicitly terminated. The platform maintains the frozen snapshot on disk until either an AutoResume event occurs, a manual connect() call is issued, or the sandbox receives a termination signal.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}