API Services Overview
Relevant source files
The following files were used as context for generating this wiki page:
The Daytona API services constitute the core communication backbone of the Daytona AI platform. These services provide a unified interface for managing isolated development environments (sandboxes), orchestrating resources, and handling administrative tasks such as user authentication and organization management. The system is designed around a central API server that interacts with various specialized services including runners, proxies, and storage providers.
The API is formally defined using the OpenAPI specification, which enables the automatic generation of multi-language SDKs (Python, TypeScript, Ruby) and ensures consistent interaction patterns across the platform's dashboard, CLI, and external integrations.
Sources: apps/api/src/openapi.config.ts, libs/api-client/src/api.ts:1-35, docker/README.md:1-25
System Architecture
Daytona's API architecture follows a service-oriented approach where the main API server coordinates several infrastructure components. In a typical deployment, the API server relies on a PostgreSQL database for persistence and Redis for session management and caching.
The diagram shows the high-level flow of requests from clients through the proxy to the core API and its dependencies.
Sources: docker/README.md:10-25, apps/api/src/openapi.config.ts:10-30
Core API Modules
The API surface is categorized into specialized functional modules. Each module handles a specific domain of the Daytona ecosystem:
| Module | Description |
|---|---|
| Sandbox API | Manages the lifecycle and state of isolated execution environments. |
| Workspace API | Handles high-level workspace definitions and project structures. |
| ApiKeys API | Manages authentication tokens and access permissions for programmatic use. |
| Organizations API | Controls multi-tenant structures, roles, and resource quotas. |
| Snapshots API | Manages persistent states and images of development environments. |
| Toolbox API | Provides internal utilities for sandboxes, such as file system and process management. |
Sources: libs/api-client/src/api.ts:20-38, libs/api-client-python/daytona_api_client/init.py:40-60
Authentication and Security
Daytona employs a dual-layer authentication strategy. For interactive users, it supports OpenID Connect (OIDC) via providers like Dex or Auth0. For programmatic access (CLI, SDKs, and automation), it utilizes API Keys.
API Key Management
API keys are associated with specific organizations and can be granted granular permissions.
The sequence shows the process of generating and using a programmatic access token.
Sources: libs/api-client/src/api/api-keys-api.ts:35-60, libs/api-client-ruby/lib/daytona_api_client/models/api_key_list.rb:15-35
Security Configuration
The API server is configured with a strict security posture using the following parameters:
- Bearer Authentication: Used for API key access.
- OAuth2 / OIDC: Used for user-based authentication flows.
- Organization Scoping: Many endpoints require an
X-Daytona-Organization-IDheader to ensure multi-tenant isolation.
Sources: apps/api/src/openapi.config.ts:15-25, libs/api-client/src/api/api-keys-api.ts:47-52
Data Models
The API utilizes structured data models to represent system entities. These models are consistent across all SDKs.
API Key Schema
The ApiKeyList model represents the metadata of an access token:
| Field | Type | Description |
|---|---|---|
name | String | User-defined identifier for the key. |
value | String | Masked representation of the key value. |
permissions | Array | List of permitted actions (e.g., WRITE_SANDBOXES). |
createdAt | Time | Timestamp of key generation. |
lastUsedAt | Time | (Nullable) Timestamp of the last successful authentication. |
Sources: libs/api-client-ruby/lib/daytona_api_client/models/api_key_list.rb:18-45
File Information Schema
When interacting with the Toolbox API for file operations, the following metadata is provided:
- name: Name of the file or directory.
- isDir: Boolean flag indicating if the entry is a directory.
- size: File size in bytes.
- permissions: Unix-style permission string.
- owner/group: System ownership metadata.
Sources: libs/api-client-ruby/lib/daytona_api_client/models/file_info.rb:20-40
Specialized Service APIs
Toolbox API
The Toolbox API is a specialized set of endpoints used internally within sandboxes or by the SDK to perform low-level operations. Key endpoints include:
GET /user-home-dir: Retrieves the home directory path of the sandbox user.GET /work-dir: Retrieves the current working directory for command execution.GET /version: Returns the current version of the internal toolbox daemon.
Sources: libs/toolbox-api-client/src/api/info-api.ts:38-120
Runner and Runner Health
Runners are the physical or virtual hosts where sandboxes are executed. The API monitors runner health through specific metrics and states:
- RunnerState: Tracks if a runner is Online, Offline, or in Error.
- RunnerHealthcheck: Provides periodic status updates on service availability.
Sources: libs/api-client-python/daytona_api_client/init.py:145-155
Conclusion
The Daytona API services provide a robust and extensible framework for running development environments as code. By leveraging OpenAPI standards and a modular architecture involving core API servers, specialized runners, and toolbox utilities, Daytona ensures that infrastructure management remains seamless across local Docker-based setups and large-scale production deployments. Transversal features like OIDC integration and granular API key permissions provide the necessary security for enterprise environments.