Lifecycle

A sandbox has four lifecycle events: on_create, on_delete, on_suspend, and on_resume. Custom scripts can be hooked into these events at the workspace level to perform custom logic during lifecycle transitions.

Definition

Add a lifecycle section to a workspace definition:

workspaces:
- name: dev
  checkouts:
  - path: tools
    repo:
      git: git@github.com:example-org/sandbox-tools
  lifecycle:
    on_create:
      require_build: true
      timeout: 10m
      max_retries: 5
      run:
        cmd: ./scripts/handle_sandbox_lifecycle.sh $SANDBOX_LIFECYCLE
        dir: tools
    on_delete:
      run:
        cmd: ./scripts/handle_sandbox_lifecycle.sh $SANDBOX_LIFECYCLE
        dir: tools
    on_suspend:
      run:
        cmd: ./scripts/handle_sandbox_lifecycle.sh $SANDBOX_LIFECYCLE
        dir: tools
    on_resume:
      run:
        cmd: ./scripts/handle_sandbox_lifecycle.sh $SANDBOX_LIFECYCLE
        dir: tools

Field reference:

• run.cmd: The command to execute.
• run.dir: Optional working directory; must be an existing relative path under $HOME.
• require_build: true: The hook waits until all build hooks are complete before running.
• timeout: Maximum duration before the hook is considered failed.
• max_retries: Number of automatic retries on failure.

Commands run as the owner user. The environment variable $SANDBOX_LIFECYCLE is set to the lifecycle event name.

Failures

Scripts are expected to exit with code 0 to indicate success. A non-zero exit code is treated as a failure.

A lifecycle hook failure blocks the corresponding lifecycle transition. For example:

• An on_create failure keeps the sandbox in a transition state (Creating).
• An on_suspend failure keeps the sandbox stuck in Suspending.

Failures must be manually resolved. Use the Web UI or CLI:

cs sandbox lifecycle resolve -S sandbox -a skip dev1:retry

This skips all other failures in the sandbox and retries the hook on workload dev1.

Lifecycle States

Each workload inside a sandbox progresses through the following lifecycle states:

Creating, Suspending, Resuming, and Deleting are transition states — they are expected to move to a stable state. Failures in lifecycle hooks cause the workload to remain in the transition state until resolved.

Auto Suspension Interaction

When Auto Suspension triggers while a workload is stuck in a transition state:

• The workload may start the on_suspend transition from any stuck transition state, except if it is already stuck in Suspending (in which case the sandbox will never be suspended automatically).
• When resumed, the state is restored to the previous failed transition state with the previous failure still pending, waiting for manual resolution.

See Also

• External Resources — using lifecycle hooks for cloud resource provisioning
• Auto Suspension — how suspension interacts with lifecycle states
• Sandbox — sandbox structure and workloads
• Workspace Automation — require_build and the build hook dependency