Runner Service & Docker Integration
Relevant source files
The following files were used as context for generating this wiki page:
The Runner Service is a core component of the Daytona architecture responsible for managing the lifecycle of isolated development environments (Sandboxes). It acts as the execution layer that interfaces with containerization technologies, primarily Docker, to provision, monitor, and manage resources required for code execution and developer workflows.
Each Runner serves as a managed compute node within a specific region. It reports health metrics, handles resource allocation for sandboxes, and integrates specialized plugins like computer-use to provide enhanced capabilities such as VNC desktop environments within the containers.
Runner Architecture and Lifecycle
Runners are represented as persistent entities within the Daytona API. They transition through various states—from initialization to ready, or unresponsive if health checks fail. A Runner manages a pool of resources (CPU, Memory, Disk, and optionally GPU) which are then partitioned among the sandboxes it hosts.
Runner State Management
The lifecycle of a Runner is tracked via the state field, which dictates whether the Daytona scheduler can assign new sandboxes to it.
The diagram above shows the typical state transitions for a Runner as managed by the system.
Sources: apps/api/src/sandbox/entities/runner.entity.ts:103-107, apps/dashboard/src/components/RunnerDetailsSheet.tsx:43-52
Key Data Structures
The Runner entity maintains comprehensive metadata regarding its connection, capacity, and current utilization.
| Field | Type | Description |
|---|---|---|
id | UUID | Unique identifier for the Runner instance. |
apiUrl | String | The endpoint where the Runner's API is accessible. |
state | RunnerState | Current operational status (e.g., READY, INITIALIZING). |
cpu | Number | Total CPU capacity available to the Runner. |
memoryGiB | Number | Total memory capacity in GiB. |
currentStartedSandboxes | Number | The number of active sandboxes currently running on this node. |
unschedulable | Boolean | If true, the scheduler will not place new sandboxes on this Runner. |
Sources: apps/api/src/sandbox/entities/runner.entity.ts:16-118, libs/api-client/src/models/runner.ts:25-131
Docker and Sandbox Integration
The Runner facilitates the creation of sandboxes by interfacing with Docker. It manages the underlying container processes and provides a secure boundary for code execution.
Resource Allocation Logic
Runners track both "Total" and "Allocated" resources. This allows the API to determine if a Runner has sufficient headroom to host additional sandboxes based on their defined SandboxClass (e.g., SMALL).
This flow illustrates how the system decides to place a sandbox on a specific Runner based on its current resource pressure and scheduling state.
Sources: apps/api/src/sandbox/entities/runner.entity.ts:114-118, libs/api-client/src/models/runner.ts:60-80
ComputerUse Plugin
The Runner can include the computer-use plugin, which enables agents to control a VNC desktop environment inside the Docker container. This integration involves managing four specific processes:
- Xvfb: Virtual display buffer.
- XFCE4: The desktop environment.
- x11vnc: The VNC server exposing the display.
- noVNC: A web-based client for browser access.
Sources: libs/computer-use/README.md:1-12, apps/runner/project.json:23-40
API and Communication
Runners communicate with the central Daytona API to provide health updates and receive commands.
Healthcheck and Metrics
Runners perform periodic healthchecks to update their lastChecked timestamp and report real-time metrics such as currentCpuUsagePercentage and availabilityScore.
Admin and Management Endpoints
The system provides a set of administrative actions to manage the Runner pool:
- Create/Delete Runner: Provisioning or removing compute nodes.
- Update Scheduling: Manually marking a runner as
unschedulable. - Update Draining: Safely removing a runner from service by preventing new sandboxes while allowing existing ones to finish.
Sources: libs/api-client-go/api_admin.go:37-90, libs/api-client/src/api/runners-api.ts:286-350
Conclusion
The Runner Service is the physical implementation layer of the Daytona platform. By integrating tightly with Docker and providing a robust API for state and resource management, it ensures that development sandboxes are isolated, performant, and observable. The inclusion of specialized plugins like computer-use further extends the Runner's capability from simple code execution to full interactive desktop environments.