# CubeSandbox Lifecycle States and State Transition Rules Explained

> Understand CubeSandbox lifecycle states running pausing paused and resuming Master state transition rules and failure rollback mechanisms for robust sandbox orchestration.

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

---

**CubeSandbox defines four explicit lifecycle states—`running`, `pausing`, `paused`, and `resuming`—that are persisted in Redis and orchestrated through a state machine with specific transition rules and automatic failure rollback mechanisms.**

CubeSandbox manages micro-VM sandboxes through a deterministic lifecycle model tracked in Redis. The system recognizes four distinct sandbox lifecycle states that coordinate pause and resume operations across side-car replicas and the central CubeMaster service. These states are stored under the key `cube:v1:shared:sandbox:lifecycle:state:<sandboxID>` and enforced by the side-car's validation logic.

## The Four Sandbox Lifecycle States

The state machine is defined in [`cube-lifecycle-manager/internal/lifecycle/schema.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/cube-lifecycle-manager/internal/lifecycle/schema.go), where the `StateKey` function enumerates the four valid string values. Each state represents a specific phase of the micro-VM's existence.

### Running

The **`running`** state indicates the sandbox micro-VM is active and executing user code. This is the primary stable state where compute resources are allocated and the environment is fully operational.

### Pausing

The **`pausing`** state is a transient intermediate state entered when a pause request is initiated. During this phase, the side-car acquires a distributed lock and coordinates the shutdown of the VM, preventing concurrent modifications while the operation is in-flight.

### Paused

The **`paused`** state represents a stable stopped condition where the VM has been shut down and compute resources released, though metadata persists. Sandboxes in this state can be resumed later without data loss, making it ideal for cost-saving sleep operations.

### Resuming

The **`resuming`** state is the transient counterpart to pausing, entered when a resume request is in-flight. The side-car uses this state to signal that the VM is currently booting and not yet ready to accept traffic, protecting against premature health checks.

## State Transition Rules and Triggers

Transitions between states follow strict rules enforced by the side-car's Redis-backed coordination mechanism. The system uses `SETNX` (set if not exists) with a TTL to ensure atomic state updates and prevent race conditions across distributed components.

### Pause Operation: Running to Paused

When a **Pause** request is received for a `running` sandbox, the side-car first writes `pausing` using `SETNX` with a TTL to signal an ongoing operation. After the VM is successfully stopped, the state is updated to `paused`. This two-phase commit ensures visibility of the transition in progress and prevents duplicate pause attempts.

### Resume Operation: Paused to Running

The **Resume** operation follows the inverse pattern. The side-car writes `resuming` (via `SETNX`) and, once the VM boots successfully, flips the state to `running`. The **Resumer** component in [`cube-lifecycle-manager/internal/resumer/resumer.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/cube-lifecycle-manager/internal/resumer/resumer.go) (lines 61-68) implements this logic, handling idempotency and concurrent calls through the Redis lock mechanism.

### Failure Handling and Rollback

If a pause or resume operation fails or exceeds the configured TTL, the side-car rolls back the transient state. The system re-enters the previous stable state—either `running` or `paused`—ensuring the sandbox does not remain stuck in `pausing` or `resuming` indefinitely.

### Termination and Cleanup

A **Delete** operation triggers sandbox termination and immediately removes the Redis state key. There is no transition to a terminal state; the lifecycle metadata is erased, preventing any further state changes or recovery operations.

## Implementation in the Source Code

The state machine is implemented across several components in the `cube-lifecycle-manager` directory.

The **ProxyPush** client enforces state validation before transmission. In [`cube-lifecycle-manager/internal/proxypush/client.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/cube-lifecycle-manager/internal/proxypush/client.go) (line 104), the code explicitly checks that pushed states match the allowed set: `"running" | "pausing" | "paused" | "resuming"`.

State persistence uses the `StateKey` function defined in [`cube-lifecycle-manager/internal/lifecycle/schema.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/cube-lifecycle-manager/internal/lifecycle/schema.go) (lines 33-35). This function generates the Redis key `cube:v1:shared:sandbox:lifecycle:state:<sandboxID>` and documents the valid state values in its source comments.

## Practical Usage Examples

The following Go SDK examples demonstrate how to trigger state transitions programmatically.

To pause an active sandbox:

```go
sandboxID := "sb-123"
client := cubesandbox.NewClient("http://cube-master.local")
if err := client.Pause(context.Background(), sandboxID); err != nil {
    log.Fatalf("pause failed: %v", err)
}

```

To resume a paused sandbox:

```go
if err := client.Resume(context.Background(), sandboxID); err != nil {
    log.Fatalf("resume failed: %v", err)
}

```

Both SDK calls update the Redis state key, driving the side-car's state machine through the `pausing` or `resuming` intermediates before reaching the stable target state.

## Summary

- CubeSandbox defines **four lifecycle states**: `running`, `pausing`, `paused`, and `resuming`.
- **Stable states** (`running` and `paused`) hold the sandbox between operations, while **transient states** (`pausing` and `resuming`) coordinate VM shutdown and startup.
- Transitions use **Redis SETNX with TTL** to ensure atomic updates and prevent race conditions across side-car replicas.
- Failed operations roll back to the last stable state rather than leaving the sandbox in a transient condition.
- State values are validated in [`cube-lifecycle-manager/internal/proxypush/client.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/cube-lifecycle-manager/internal/proxypush/client.go) and defined in [`cube-lifecycle-manager/internal/lifecycle/schema.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/cube-lifecycle-manager/internal/lifecycle/schema.go).

## Frequently Asked Questions

### What are the valid sandbox lifecycle states in CubeSandbox?

CubeSandbox recognizes four states: `running` (VM active), `pausing` (shutdown in progress), `paused` (VM stopped, metadata retained), and `resuming` (boot in progress). These are enumerated in the `StateKey` comments in [`cube-lifecycle-manager/internal/lifecycle/schema.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/cube-lifecycle-manager/internal/lifecycle/schema.go).

### How does CubeSandbox prevent concurrent state transitions?

The side-car uses Redis `SETNX` (set if not exists) with a TTL on the state key `cube:v1:shared:sandbox:lifecycle:state:<sandboxID>`. This creates a distributed lock ensuring only one replica can drive a pause or resume operation at a time, preventing split-brain scenarios.

### What happens if a pause or resume operation fails?

If the operation fails or times out, the side-car rolls back the transient state (`pausing` or `resuming`) to the previous stable state (`running` or `paused`). This prevents the sandbox from remaining in an undefined intermediate state and ensures eventual consistency.

### Where is the sandbox state stored in CubeSandbox?

The state is persisted in Redis under the key `cube:v1:shared:sandbox:lifecycle:state:<sandboxID>`, generated by the `StateKey` function. The `cube-lifecycle-manager` components read and write this key to coordinate lifecycle transitions across the distributed system.