# How CubeSandbox AutoPause/AutoResume Works for Idle Sandbox Cost Optimization

> CubeSandbox AutoPause AutoResume saves costs by snapshotting idle sandboxes to disk. It reduces CPU memory costs to zero and transparently restores state for new requests.

- Repository: [Tencent Cloud/CubeSandbox](https://github.com/TencentCloud/CubeSandbox)
- Tags: internals
- Published: 2026-07-11

---

**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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/CubeAPI/src/services/sandboxes.rs) and processed through the control plane structs defined in [`CubeMaster/pkg/service/sandbox/types/types.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/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

```python
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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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

```python
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

```python
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

```toml

# 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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/docs/guide/lifecycle.md).