Customer Managed Compute

import { TabItem, Tabs } from '@astrojs/starlight/components'

Customer Managed Compute enables you to use your own runner machines to run sandbox workloads. Runners are machines that power Daytona's compute plane and provide the underlying infrastructure. Each runner is responsible for:

• Workload execution: running sandbox workloads
• Resource management: allocating and monitoring CPU, memory, and disk resources
• Health reporting: providing metrics and health status to the Daytona control plane
• Network connectivity: managing sandbox networking, proxy connections, and SSH access

Runners in shared and dedicated regions are fully managed by Daytona — from provisioning and maintenance to monitoring and scaling. For custom regions, you bring your own runner machines and are responsible for their management and operation.

Daytona provides two sets of runner management endpoints: custom runners (/runners) and admin operations (/admin/runners). While both support creating, listing, updating, and deleting runners, they serve different purposes and offer different levels of control.

Custom runner endpoints are scoped to your organization and support the X-Daytona-Organization-ID header. Admin endpoints operate across the entire platform and do not require an organization header.

Both Runner and RunnerFull share the same base fields, including resource metrics, allocated resources, availability score, snapshot count, and started sandboxes. The RunnerFull type extends Runner with the runner's apiKey and regionType fields.

Custom regions

Custom regions are created and managed by your organization, allowing you to use your own runner machines and scale compute resources independently within each region. This provides maximum control over data locality, compliance, and infrastructure configuration.

Additionally, custom regions have no limits applied for concurrent resource usage, giving you full control over capacity and performance.

Custom region configuration

name (required)

• A unique identifier for your region
• Must contain only letters, numbers, underscores, periods, and hyphens
• Used for targeting this region when creating a sandbox

proxyUrl (optional)

• The URL of the proxy service that routes traffic to sandboxes in this region
• Required if the runner machines in this region are deployed in a private network

sshGatewayUrl (optional)

• The URL of the SSH gateway that handles SSH connections to sandboxes in this region
• Required if the runner machines in this region are deployed in a private network

snapshotManagerUrl (optional)

• The URL of the snapshot manager that handles storage and retrieval of snapshots in this region
• Required if the runner machines in this region are deployed in a private network

Create a custom region

Daytona provides methods to create a custom region using the Daytona Dashboard ↗ or programmatically using the API.

1. Navigate to Daytona Dashboard ↗
2. Click the Create Region button
3. Enter the region name, proxy URL, SSH gateway URL, and snapshot manager URL

• Region name: the name of the region; must contain only letters, numbers, underscores, periods, and hyphens.
• Proxy URL (optional): the URL of the custom proxy for this region
• SSH gateway URL (optional): the URL of the custom SSH gateway for this region
• Snapshot manager URL (optional): the URL of the custom snapshot manager for this region

4. Click Create to create the region

curl https://app.daytona.io/api/regions \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
    "name": "my-custom-region",
    "proxyUrl": "https://proxy.example.com",
    "sshGatewayUrl": "ssh://ssh-gateway.example.com",
    "snapshotManagerUrl": "https://snapshot-manager.example.com"
  }'

The response includes the region ID and credentials for any optional services you configured:

{
  "id": "region_12345",
  "proxyApiKey": "proxy-api-key-xyz",
  "sshGatewayApiKey": "ssh-gateway-api-key-abc",
  "snapshotManagerUsername": "daytona",
  "snapshotManagerPassword": "generated-password"
}

For more information, see the API reference:

createRegion (API)

Custom region credentials

When you create a custom region, Daytona will provide credentials for any optional services you configure:

• An API key that should be used by your proxy service to authenticate with Daytona
• An API key that should be used by your SSH gateway service to authenticate with Daytona
• Basic authentication credentials that Daytona uses to access your snapshot manager service

:::note If needed, these credentials can always be regenerated, but you will need to redeploy the corresponding services with the updated credentials. :::

List custom regions

Daytona provides methods to list all available regions for your organization using the Daytona Dashboard ↗ or programmatically using the API.

1. Navigate to Daytona Dashboard ↗
2. The list of regions is displayed in the Regions table with the following columns:

• Name: the name of the region
• ID: the ID of the region
• Created: the date and time the region was created

curl https://app.daytona.io/api/regions \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

For more information, see the API reference:

listAvailableRegions (API)

Get a custom region

Daytona provides methods to get the details of a specific region using the Daytona Dashboard ↗ or programmatically using the API.

1. Navigate to Daytona Dashboard ↗
2. Click the region you want to get the details of
3. The region details are displayed in the Region Details panel with the following information:

• Name: the name of the region
• ID: the ID of the region
• Created: the date and time the region was created
• URLs: the URLs of the region's proxy, SSH gateway, and snapshot manager services

curl https://app.daytona.io/api/regions/{regionId} \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

For more information, see the API reference:

getRegionById (API)

Update a custom region

Daytona provides methods to update the configuration of an existing custom region using the Daytona Dashboard ↗ or programmatically using the API.

1. Navigate to Daytona Dashboard ↗
2. Click the region you want to update the configuration of
3. Click the three dots menu (⋮) next to the region and select the Edit icon
4. Enter the new proxy URL, SSH gateway URL, and snapshot manager URL
5. Click Update to update the region configuration

• Proxy URL (optional): the new URL of the custom proxy for this region
• SSH gateway URL (optional): the new URL of the custom SSH gateway for this region
• Snapshot manager URL (optional): the new URL of the custom snapshot manager for this region

curl https://app.daytona.io/api/regions/{regionId} \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
    "proxyUrl": "https://new-proxy.example.com",
    "sshGatewayUrl": "ssh://new-ssh-gateway.example.com",
    "snapshotManagerUrl": "https://new-snapshot-manager.example.com"
  }'

For more information, see the API reference:

updateRegion (API)

Delete a custom region

Daytona provides methods to delete a custom region using the Daytona Dashboard ↗ or programmatically using the API. Regions that have runners assigned to them cannot be deleted.

1. Navigate to Daytona Dashboard ↗
2. Click the region you want to delete
3. Click the three dots menu (⋮) next to the region and select Delete
4. Confirm the deletion

curl https://app.daytona.io/api/regions/{regionId} \
  --request DELETE \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

For more information, see the API reference:

deleteRegion (API)

Regenerate proxy API key

Daytona provides an API to regenerate the proxy API key for a custom region.

curl https://app.daytona.io/api/regions/{regionId}/regenerate-proxy-api-key \
  --request POST \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

For more information, see the API reference:

regenerateProxyApiKey (API)

Regenerate SSH gateway API key

Daytona provides an API to regenerate the SSH gateway API key for a custom region.

curl https://app.daytona.io/api/regions/{regionId}/regenerate-ssh-gateway-api-key \
  --request POST \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

For more information, see the API reference:

regenerateSshGatewayApiKey (API)

Regenerate snapshot manager credentials

Daytona provides an API to regenerate the snapshot manager credentials for a custom region.

curl https://app.daytona.io/api/regions/{regionId}/regenerate-snapshot-manager-credentials \
  --request POST \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

For more information, see the API reference:

regenerateSnapshotManagerCredentials (API)

Custom runners

Custom runners are created and managed by your organization, allowing you to use your own runner machines and scale compute resources independently within each custom region.

Custom runner configuration

name (required)

• A unique identifier for the runner
• Must contain only letters, numbers, underscores, periods, and hyphens
• Helps distinguish between multiple runners in the same region

regionId (required)

• The ID of the region this runner is assigned to
• Must be a custom region owned by your organization
• All runners in a region share the region's proxy and SSH gateway configuration

Create a custom runner

Daytona provides methods to create a custom runner using the Daytona Dashboard ↗ or programmatically using the API.

1. Navigate to Daytona Dashboard ↗
2. Click the Create Runner button
3. Select a region and enter its name
4. Click Create to create the runner

• Region: the region this runner is assigned to
• Name: the name of the runner

curl https://app.daytona.io/api/runners \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
    "name": "my-custom-runner",
    "regionId": "region_12345"
  }'

Upon creating a runner, you will be presented with a secure token that you can use to authenticate the runner with the Daytona control plane. The response includes the runner ID and the API key token:

{
  "id": "runner123",
  "apiKey": "dtn_1234567890"
}

:::note Save this token securely. You won't be able to see it again. :::

For more information, see the API reference:

createRunner (API)

List custom runners

Daytona provides methods to list all runners in your organization using the Daytona Dashboard ↗ or programmatically using the API.

1. Navigate to Daytona Dashboard ↗
2. The list of runners is displayed in the Runners table with the following columns:

• ID: the ID of the runner
• Name: the name of the runner
• Region: the region this runner is assigned to
• State: the state of the runner
• Schedulable: checkbox to mark the runner as unschedulable

curl https://app.daytona.io/api/runners \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

For more information, see the API reference:

listRunners (API)

Get a custom runner

Daytona provides methods to get the details of a specific runner using the Daytona Dashboard ↗ or programmatically using the API.

1. Navigate to Daytona Dashboard ↗
2. Click the runner you want to get the details of
3. The runner details are displayed in the Runner Details panel with the following information:

• Name: the name of the runner
• UUID: the UUID of the runner
• State: the state of the runner
• Schedulable: whether the runner is schedulable
• Region: the region this runner is assigned to
• Version: the version of the runner
• Health metrics: the health metrics of the runner (availability score, CPU, memory, disk usage)
• Active sandboxes: the number of active sandboxes running on the runner
• Snapshots: the number of snapshots stored on the runner
• Total resources: the total resources allocated to the runner (CPU, memory, disk)
• Created at: the date and time the runner was created
• Updated at: the date and time the runner was last updated

curl https://app.daytona.io/api/runners/{runnerId} \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

For more information, see the API reference:

getRunnerById (API)

Update runner scheduling

Daytona provides methods to update the scheduling status of a runner using the Daytona Dashboard ↗ or programmatically using the API. This allows you to mark a runner as unschedulable, preventing new sandboxes from being assigned to it.

1. Navigate to Daytona Dashboard ↗
2. Use the checkbox to mark the runner as unschedulable or schedulable

curl https://app.daytona.io/api/runners/{runnerId}/scheduling \
  --request PATCH \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

For more information, see the API reference:

updateRunnerScheduling (API)

Delete a custom runner

Daytona provides methods to delete a custom runner using the Daytona Dashboard ↗ or programmatically using the API.

1. Navigate to Daytona Dashboard ↗
2. Click the three dots menu (⋮) next to the runner you want to delete and select Delete
3. Confirm the deletion

curl https://app.daytona.io/api/runners/{runnerId} \
  --request DELETE \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

For more information, see the API reference:

deleteRunner (API)

Admin operations

Admin runners operate across the entire platform. They do not require the X-Daytona-Organization-ID header and return RunnerFull objects with additional apiKey and regionType fields.

Admin runner configuration

name (required)

• A unique identifier for the runner
• Must contain only letters, numbers, underscores, periods, and hyphens

regionId (required)

• The ID of the region this runner is assigned to

apiKey (required)

• The API key used to authenticate the runner with the Daytona control plane

apiVersion (required)

• The API version of the runner
• Must be 0 or 2

domain (optional)

• The domain of the runner

apiUrl (optional)

• The API URL of the runner

proxyUrl (optional)

• The proxy URL of the runner

cpu (optional)

• The CPU capacity of the runner

memoryGiB (optional)

• The memory capacity of the runner in GiB

diskGiB (optional)

• The disk capacity of the runner in GiB

Create a runner

Daytona provides an admin API to create a runner with full configuration, including resource capacity and network settings. Unlike the custom runner endpoint, you must provide your own apiKey and specify the apiVersion (0 or 2).

curl https://app.daytona.io/api/admin/runners \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
    "name": "my-custom-runner",
    "regionId": "region_12345",
    "apiKey": "dtn_1234567890",
    "apiVersion": "2",
    "domain": "runner1.example.com",
    "apiUrl": "https://api.runner1.example.com",
    "proxyUrl": "https://proxy.runner1.example.com",
    "cpu": 8,
    "memoryGiB": 16,
    "diskGiB": 100
  }'

For more information, see the API reference:

adminCreateRunner (API)

List runners

Daytona provides an admin API to list all runners with full details, including resource usage metrics. You can optionally filter runners by region.

# List all runners
curl https://app.daytona.io/api/admin/runners \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

# Filter runners by region
curl 'https://app.daytona.io/api/admin/runners?regionId=region_12345' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

For more information, see the API reference:

adminListRunners (API)

Get runner

Daytona provides an admin API to get full runner details, including resource usage and allocation metrics.

curl https://app.daytona.io/api/admin/runners/{runnerId} \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

For more information, see the API reference:

adminGetRunnerById (API)

Update runner scheduling

Daytona provides an admin API to update the scheduling status of a runner.

curl https://app.daytona.io/api/admin/runners/{runnerId}/scheduling \
  --request PATCH \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

For more information, see the API reference:

adminUpdateRunnerScheduling (API)

Delete runner

Daytona provides an admin API to delete a runner.

curl https://app.daytona.io/api/admin/runners/{runnerId} \
  --request DELETE \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

For more information, see the API reference:

adminDeleteRunner (API)

Runner deployment

After registering a custom runner and obtaining its secure token, install and configure the Daytona runner application on your infrastructure. Daytona provides official Terraform modules and Helm charts for automated runner deployment.

Terraform

Daytona provides a Terraform module for deploying runners on AWS EC2 with automated installation and configuration. The module handles instance provisioning, security configuration, and runner registration with the Daytona platform.

View the full documentation and examples in the GitHub repository:

• GitHub: daytonaio/terraform-modules

Prerequisites

• Terraform >= 1.0
• AWS credentials configured
• VPC and subnet already created
• Ubuntu 22.04 or later AMI
• Daytona runner .deb package hosted at an accessible URL

Basic example

module "daytona_runner" {
  source = "./runner"

  # Network Configuration
  vpc_id    = "vpc-1234567890abcdef0"
  subnet_id = "subnet-1234567890abcdef0"

  # EC2 Configuration
  ami_id        = "ami-0c55b159cbfafe1f0"  # Ubuntu 22.04 LTS
  instance_type = "t3.medium"

  # Daytona Configuration
  api_url   = "https://daytona.example.com/api"
  api_key   = "your-api-key-here"
  region_id = "your-region-id"

  # Optional: Enable SSM for secure access
  enable_ssm = true

  tags = {
    Environment = "production"
    ManagedBy   = "terraform"
  }
}

Advanced example

module "daytona_runner" {
  source = "./runner"

  name_prefix = "production"

  # Network Configuration
  vpc_id    = "vpc-1234567890abcdef0"
  subnet_id = "subnet-1234567890abcdef0"

  # EC2 Configuration
  ami_id             = "ami-0c55b159cbfafe1f0"
  instance_type      = "t3.large"
  root_volume_size   = 100
  root_volume_type   = "gp3"

  # Daytona Configuration
  api_url   = "https://api.daytona.example.com"
  api_key   = var.api_key  # Use variable for sensitive data
  region_id = var.region_id

  # Security Configuration
  enable_ssh       = true
  ssh_cidr_blocks  = ["10.0.0.0/8"]
  key_name         = "my-ssh-key"
  enable_ssm       = true

  tags = {
    Environment = "production"
    Team        = "platform"
    ManagedBy   = "terraform"
  }
}

Inputs

Outputs

Security considerations

1. API Key: The api_key is marked as sensitive. Use Terraform variables or a secrets manager.
2. SSH Access: Disabled by default. Use SSM Session Manager instead for better security.
3. Encryption: Root volume is encrypted by default.
4. IMDSv2: Instance Metadata Service v2 is enforced.
5. Network: The instance only allows outbound traffic by default.

Access using SSM Session Manager

# No SSH key required
aws ssm start-session --target <instance-id>

# Check runner status
sudo systemctl status daytona-runner

# View logs
sudo journalctl -u daytona-runner -f

Access using SSH

ssh -i ~/.ssh/your-key.pem ubuntu@<instance-ip>

Troubleshooting

Troubleshoot cloud-init issues:

# View cloud-init output
sudo cat /var/log/cloud-init-output.log

# Check cloud-init status
sudo cloud-init status

Troubleshoot runner issues:

# Service status
sudo systemctl status daytona-runner

# Service logs
sudo journalctl -u daytona-runner -n 100 --no-pager

# Check configuration
sudo cat /etc/daytona/runner.env

Verify runner installation:

# Check if binary exists
ls -la /opt/daytona/runner

# Check binary permissions
file /opt/daytona/runner

Helm charts

Daytona provides a Helm chart for deploying custom regions and their supporting infrastructure on Kubernetes. The daytona-region chart deploys a proxy service, optional snapshot manager, and a registration job, allowing you to run Daytona sandboxes within your own Kubernetes cluster.

View the full documentation and examples in the GitHub repository:

• GitHub: daytonaio/helm-charts

Prerequisites

• Supported OS Architecture: AMD64/x86_64
• Docker: The script will install Docker if not present.
• Systemd: Required for service management.

Installation

1. Run the runner install script

curl -sSL https://download.daytona.io/install.sh | sudo bash

The script will prompt you for:

• Daytona API URL
• Daytona Admin API Key
• System resource allocation (CPU, memory, disk)
• Domain name for the runner
• Runner API URL
• Optional proxy URL, region, runner capacity, and runner API key

2. Automatic steps performed by the script

• Checks system architecture
• Downloads the Daytona runner binary
• Installs Docker if missing
• Registers the runner with the Daytona API
• Creates and enables a systemd service for the runner
• Starts the runner service

Manage the runner service

Check status:

sudo systemctl status daytona-runner

View logs:

sudo tail -f /var/log/daytona-runner.log

Stop service:

sudo systemctl stop daytona-runner

Override with environment variables

The following environment variables can be set to override the default values in the install script:

:::tip Set these variables before running the install script to customize the runner configuration. :::