Sandbox Lifecycle Management
Relevant source files
The following files were used as context for generating this wiki page:
Sandbox Lifecycle Management governs the entire duration of a development environment, from its initial creation and resource allocation to its eventual archival or destruction. The system ensures that sandboxes transition through valid states while maintaining resource quotas and automated cleanup policies.
The core logic resides in the SandboxService, which coordinates between the API requests, database persistence via the Sandbox entity, and the runner adapters that execute the physical lifecycle operations on the infrastructure.
Sources: apps/api/src/sandbox/services/sandbox.service.ts, apps/api/src/sandbox/entities/sandbox.entity.ts
Architecture and Components
The lifecycle system is built on a desired-state reconciliation model. The system tracks the current state of a sandbox and a desiredState requested by the user or automation.
Key Data Structures
- Sandbox Entity: The primary database representation, containing metadata like region, resource limits (CPU, memory, disk), and lifecycle intervals.
- SandboxState: An enum representing the actual current status (e.g.,
started,stopped,error,resizing). - SandboxDesiredState: An enum representing what the state should be (e.g.,
started,stopped,archived,destroyed).
Sources: apps/api/src/sandbox/entities/sandbox.entity.ts:60-155, apps/api/src/sandbox/dto/sandbox.dto.ts:300-330
State Machine Transition Logic
The system validates transitions to ensure a sandbox does not move from an incompatible state (e.g., an archived sandbox cannot be stopped directly; it must be started or restored first).
The diagram above represents the typical state transitions managed by the service layer.
Sources: apps/api/src/sandbox/entities/sandbox.entity.ts:210-260
Lifecycle Operations
Creation and Provisioning
Sandboxes can be created from snapshots or build information. The process involves validating organization quotas, reserving resources, and assigning a runner. If a warm pool is available, the system may assign a pre-started sandbox to reduce latency.
Sources: apps/api/src/sandbox/services/sandbox.service.ts:310-450
Resource Resizing
Daytona supports both "hot" and "cold" resizing:
- Hot Resize: Increasing CPU or memory while the sandbox is
STARTED. - Cold Resize: Modifying disk space or decreasing CPU/memory, which requires the sandbox to be in a
STOPPEDstate.
| Parameter | Hot Resize | Cold Resize |
|---|---|---|
| CPU | Increase Only | Increase/Decrease |
| Memory | Increase Only | Increase/Decrease |
| Disk | N/A | Increase Only |
Sources: apps/api/src/sandbox/services/sandbox.service.ts:1000-1150
Archival and Backup
Archiving moves the entire filesystem state to cost-effective object storage. This is distinct from stopping, as it frees up runner resources. The autoArchiveInterval controls how long a sandbox can remain stopped before being automatically moved to storage.
Sources: apps/api/src/sandbox/services/sandbox.service.ts:260-295, libs/sdk-typescript/src/Sandbox.ts:650-660
Automated Lifecycle Management
The system implements automated cleanup and resource saving through three primary intervals:
| Interval | Description | Default |
|---|---|---|
autoStopInterval | Minutes of inactivity before the sandbox stops. | 15 minutes |
autoArchiveInterval | Minutes a sandbox remains stopped before archiving. | 7 days |
autoDeleteInterval | Minutes a sandbox remains stopped before deletion. | Disabled (-1) |
The updateLastActivityAt function is called during SSH access, preview URL hits, or Toolbox API calls to reset the autoStop timer.
Sources: apps/api/src/sandbox/entities/sandbox.entity.ts:160-185, apps/api/src/sandbox/services/sandbox.service.ts:1175-1190
State Reconciliation Sequence
The transition from a user request to a running sandbox involves the API layer, the database, and the runner.
The sequence above illustrates how the pending flag is used to indicate a transition is in progress.
Sources: apps/api/src/sandbox/services/sandbox.service.ts:880-940, apps/dashboard/src/pages/Sandboxes.tsx:325-360
Error Handling and Recovery
When a sandbox enters the ERROR state, it is often due to infrastructure issues or build failures. The system provides a recover operation which attempts to repair the underlying instance (e.g., expanding storage if it ran out of space) and moves the state back to STOPPED before restarting.
Sources: apps/api/src/sandbox/services/sandbox.service.ts:970-1015, libs/api-client/src/api/sandbox-api.ts:1000-1025
Conclusion
Sandbox Lifecycle Management provides a robust framework for managing ephemeral and persistent development environments. By utilizing a desired-state model and automated lifecycle intervals, Daytona optimizes resource usage while ensuring environments are available when developers need them. The combination of hot-resizing and warm-pooling specifically addresses the performance and flexibility requirements of modern cloud development workflows.