How CubeSandbox AutoPause/AutoResume Works for Idle Sandbox Cost Optimization

CubeSandbox's AutoPause/AutoResume feature automatically snapshots idle sandboxes to disk after a configurable timeout, reducing CPU and memory costs to zero, then transparently restores state when new requests arrive.

The TencentCloud/CubeSandbox platform provides intelligent lifecycle management that eliminates wasted compute resources from idle sandboxes. By leveraging AutoPause, the system freezes VM memory and filesystem state to persistent storage, while AutoResume handles automatic restoration when SDK calls or HTTP requests target a paused sandbox. This mechanism ensures developers pay only for active execution time without losing ephemeral workspace data.

Sandbox Lifecycle States for AutoPause/AutoResume

The AutoPause/AutoResume feature operates through a strict state machine defined in docs/guide/lifecycle.md. Each sandbox transitions through specific phases that determine resource consumption and availability.

Understanding the State Transitions

State	Resource Usage	Description
running	Full CPU & memory	Actively executing code and processing requests.
pausing	Transitioning	The platform captures a full VM snapshot including memory and CPU registers.
paused	Zero CPU/memory	Snapshot stored on disk; sandbox consumes no active resources.
resuming	Transitioning	Snapshot restoration in progress; resources reallocated.
terminated	None	Sandbox permanently destroyed; cannot be revived.

When a sandbox enters the paused state, the cube-lifecycle-manager service has successfully offloaded the runtime state to storage, making the workload eligible for complete resource reclamation.

Configuration Settings for Idle Timeout Management

Three critical parameters control AutoPause/AutoResume behavior, parsed by the HTTP handler in CubeAPI/src/services/sandboxes.rs and processed through the control plane structs defined in CubeMaster/pkg/service/sandbox/types/types.go.

• timeout (int): Idle seconds before trigger. Omitting this uses server defaults or disables auto-pause.
• on_timeout (string): "kill" (default) destroys the sandbox; "pause" initiates the snapshot sequence.
• auto_resume (bool): true enables transparent resume on any incoming request; false requires explicit Sandbox.connect() calls.

Python SDK Configuration Example

from cubesandbox import Sandbox

# Create sandbox with 5-minute idle timeout

sandbox = Sandbox.create(
    template="base-template",
    timeout=300,
    lifecycle={
        "on_timeout": "pause",    # Snapshot instead of terminate

        "auto_resume": True,      # Auto-resume on next request

    },
)

The JSON schema in cube-lifecycle-manager/internal/lifecycle/schema.go validates these fields during sandbox creation.

How AutoPause Works Under the Hood

The AutoPause mechanism involves four coordinated steps across the CubeSandbox infrastructure.

Idle Detection The idle clock resets on every SDK operation (run_code, files.read, files.write) or inbound HTTP traffic. This tracking ensures only truly inactive sandboxes qualify for pausing.

Timeout Firing After timeout seconds of inactivity, CubeMaster publishes a pause event via Redis to the cube-lifecycle-manager service.

Snapshot Creation The manager instructs CubeProxy on the node to freeze the VM and serialize its state. During the pausing → paused transition, the complete memory image and filesystem are written to storage-backed snapshots.

Resource Reclamation CPU and memory are instantly reclaimed. By default, paused sandboxes still count against scheduler quotas, but the node-level configuration host.quota.paused_resource_release_ratio in Cubelet/config/config.toml can release a configurable fraction (e.g., 0.5 for 50%) of that quota back to the pool.

How AutoResume Handles Incoming Requests

When a paused sandbox receives traffic, the AutoResume logic in cube-lifecycle-manager/internal/resumer/resumer.go orchestrates transparent restoration.

Request Interception CubeProxy detects incoming requests and checks the auto_resume flag for the target sandbox.

Snapshot Restoration The proxy issues a resume RPC to the control plane, which reloads the VM state from disk (resuming → running). This process typically completes in milliseconds.

Timeout Reset Every successful auto-resume resets the idle countdown, allowing the pause/resume cycle to repeat indefinitely without manual intervention.

Capacity Constraints If the node cannot accommodate the restored resources (common when paused_resource_release_ratio > 0 and the node is near capacity), the resume returns a 409 Conflict error. The SDK treats this as retriable, allowing the scheduler to migrate or free resources.

Implementation Examples

Auto-Pause with Automatic Resume

from cubesandbox import Sandbox

sandbox = Sandbox.create(
    template="python-dev",
    timeout=600,  # 10 minutes

    lifecycle={
        "on_timeout": "pause",
        "auto_resume": True,
    },
)

# Sandbox pauses after idle period

# This call triggers automatic resume if needed

result = sandbox.run_code("print('Resumed successfully')")

Manual Pause and Resume Control

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

# Explicit lifecycle management

sandbox.pause()       # Force snapshot to disk

sandbox.connect()   # Explicitly resume from paused state

sandbox.run_code("print('Manual control works')")

Node-Level Quota Optimization

# Cubelet/config/config.toml

[host.quota]
paused_resource_release_ratio = 0.5

This configuration releases 50% of the CPU and memory quota for paused sandboxes, increasing cluster density but requiring careful capacity management for resumed workloads.

Summary

• AutoPause freezes idle sandboxes after a configurable timeout, storing complete state (memory, filesystem, registers) to disk and reducing CPU/memory costs to zero.
• AutoResume transparently restores snapshots when requests arrive, handling the paused → running transition automatically when auto_resume is enabled.
• The lifecycle states (running, pausing, paused, resuming) are managed by cube-lifecycle-manager and documented in docs/guide/lifecycle.md.
• Resource quotas can be partially released for paused sandboxes via host.quota.paused_resource_release_ratio in the Cubelet configuration.
• Resume operations may return 409 Conflict if node capacity is insufficient, triggering SDK-level retries.

Frequently Asked Questions

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

All memory contents, open file descriptors, and CPU register states are preserved in a snapshot stored on disk. When the sandbox resumes, the environment continues exactly where it left off, as if no interruption occurred. This snapshot mechanism ensures zero data loss during the pause/resume cycle.

How does AutoResume affect request latency?

The first request hitting a paused sandbox experiences additional latency while the system restores the snapshot (typically milliseconds to seconds depending on memory size). Subsequent requests perform at normal speed. The SDK handles this transparently, blocking the caller until the resuming → running transition completes.

Can I disable auto-pause but keep auto-resume capabilities?

No, AutoResume requires the sandbox to be in a paused state, which only occurs after AutoPause triggers or manual pause() calls. If you set on_timeout: "kill", the sandbox terminates instead of pausing, making auto-resume impossible. You must use on_timeout: "pause" to enable the resume functionality.

What is the difference between timeout reset on resume versus manual connect?

When auto_resume: true, the idle timer automatically resets to zero upon successful resumption, restarting the countdown toward the next auto-pause. With manual connect() calls, you must explicitly manage the lifecycle; the timeout behavior depends on the specific SDK implementation and platform policies defined in docs/guide/lifecycle.md.

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