Sign Up

Runners

List all runners

GET
/runners

Authorization

headerAuthorizationBearer <token>

API Key access

Query Parameters

regionId?string

Filter runners by region ID

Header Parameters

X-Daytona-Organization-ID?string

Use with JWT to specify the organization ID

Response Body

application/json
  1. response
[index: integer]?
curl -X GET 'http://localhost:3000/runners'
[  {    "currentStartedSandboxes": 5,    "appVersion": "v0.0.0-dev",    "memory": 16,    "currentMemoryUsagePercentage": 68.2,    "availabilityScore": 85,    "currentDiskUsagePercentage": 33.8,    "currentCpuUsagePercentage": 45.6,    "createdAt": "2023-10-01T12:00:00Z",    "apiVersion": "0",    "apiUrl": "https://api.runner1.example.com",    "id": "runner123",    "state": "initializing",    "unschedulable": false,    "currentAllocatedDiskGiB": 50000,    "class": "small",    "currentAllocatedMemoryGiB": 8000,    "gpuType": "gpuType",    "sandboxClass": "linux-vm",    "currentAllocatedCpu": 4000,    "updatedAt": "2023-10-01T12:00:00Z",    "proxyUrl": "https://proxy.runner1.example.com",    "cpu": 8,    "gpu": 1,    "currentSnapshotCount": 12,    "version": "0",    "tags": [      "gpu",      "us-east"    ],    "disk": 100,    "domain": "runner1.example.com",    "name": "runner1",    "runnerClass": "container",    "region": "us",    "lastChecked": "2024-10-01T12:00:00Z"  }]

Create runner

POST
/runners

Authorization

headerAuthorizationBearer <token>

API Key access

Header Parameters

X-Daytona-Organization-ID?string

Use with JWT to specify the organization ID

Request Body

application/json
  1. body
regionId*string
name*string
tags?array<string>

Tags to associate with the runner

sandboxClass?|

The sandbox class supported by the runner. Defaults to container when omitted or null.

Default"container"
Value in"container""linux-vm""windows"null

Response Body

application/json
  1. response
id*string

The ID of the runner

apiKey*string

The API key for the runner

curl -X POST 'http://localhost:3000/runners' \  -H 'Content-Type: application/json' \  -d '{  "regionId": "regionId",  "name": "name",  "tags": [    "gpu",    "us-east"  ],  "sandboxClass": "container"}'
{  "apiKey": "dtn_1234567890",  "id": "runner123"}

Get info for authenticated runner

GET
/runners/me

Authorization

headerAuthorizationBearer <token>

API Key access

Response Body

Runner info

application/json
  1. response
id*string

The ID of the runner

domain?string

The domain of the runner

apiUrl?string

The API URL of the runner

proxyUrl?string

The proxy URL of the runner

cpu*number

The CPU capacity of the runner

memory*number

The memory capacity of the runner in GiB

disk*number

The disk capacity of the runner in GiB

gpu?number

The GPU capacity of the runner

gpuType?string

The type of GPU

sandboxClass?string

The sandbox class supported by this runner

Value in"linux-vm""container""windows"
currentCpuUsagePercentage?number

Current CPU usage percentage

currentMemoryUsagePercentage?number

Current RAM usage percentage

currentDiskUsagePercentage?number

Current disk usage percentage

currentAllocatedCpu?number

Current allocated CPU

currentAllocatedMemoryGiB?number

Current allocated memory in GiB

currentAllocatedDiskGiB?number

Current allocated disk in GiB

currentSnapshotCount?number

Current snapshot count

currentStartedSandboxes?number

Current number of started sandboxes

availabilityScore?number

Runner availability score

region*string

The region of the runner

name*string

The name of the runner

state*string

The state of the runner

Value in"initializing""ready""disabled""decommissioned""unresponsive"
lastChecked?string

The last time the runner was checked

unschedulable*boolean

Whether the runner is unschedulable

tags*array<string>

Tags associated with the runner

createdAt*string

The creation timestamp of the runner

updatedAt*string

The last update timestamp of the runner

version*stringDeprecated

The version of the runner (deprecated in favor of apiVersion)

apiVersion*stringDeprecated

The api version of the runner

runnerClass*"container"Deprecated

The class of the runner. Deprecated and always returns "container" for backward compatibility - use sandboxClass instead.

Value in"container"
appVersion?stringDeprecated

The app version of the runner

class?stringDeprecated

Deprecated runner class property

apiKey*string

The API key for the runner

regionType?string

The region type of the runner

Value in"shared""dedicated""custom"
curl -X GET 'http://localhost:3000/runners/me'
{  "currentStartedSandboxes": 5,  "appVersion": "v0.0.0-dev",  "memory": 16,  "currentMemoryUsagePercentage": 68.2,  "apiKey": "dtn_1234567890",  "availabilityScore": 85,  "currentDiskUsagePercentage": 33.8,  "currentCpuUsagePercentage": 45.6,  "createdAt": "2023-10-01T12:00:00Z",  "apiVersion": "0",  "apiUrl": "https://api.runner1.example.com",  "regionType": "shared",  "id": "runner123",  "state": "initializing",  "unschedulable": false,  "currentAllocatedDiskGiB": 50000,  "class": "small",  "currentAllocatedMemoryGiB": 8000,  "gpuType": "gpuType",  "sandboxClass": "linux-vm",  "currentAllocatedCpu": 4000,  "updatedAt": "2023-10-01T12:00:00Z",  "proxyUrl": "https://proxy.runner1.example.com",  "cpu": 8,  "gpu": 1,  "currentSnapshotCount": 12,  "version": "0",  "tags": [    "gpu",    "us-east"  ],  "disk": 100,  "domain": "runner1.example.com",  "name": "runner1",  "runnerClass": "container",  "region": "us",  "lastChecked": "2024-10-01T12:00:00Z"}

Get snapshot refs for authenticated runner

GET
/runners/me/snapshots

Authorization

headerAuthorizationBearer <token>

API Key access

Response Body

Snapshot refs the runner is expected to have

application/json
  1. response
[index: integer]?string
curl -X GET 'http://localhost:3000/runners/me/snapshots'
[  "string"]

Get runner by sandbox ID

GET
/runners/by-sandbox/{sandboxId}

Authorization

headerAuthorizationBearer <token>

API Key access

Path Parameters

sandboxId*string

Response Body

application/json
  1. response
id*string

The ID of the runner

domain?string

The domain of the runner

apiUrl?string

The API URL of the runner

proxyUrl?string

The proxy URL of the runner

cpu*number

The CPU capacity of the runner

memory*number

The memory capacity of the runner in GiB

disk*number

The disk capacity of the runner in GiB

gpu?number

The GPU capacity of the runner

gpuType?string

The type of GPU

sandboxClass?string

The sandbox class supported by this runner

Value in"linux-vm""container""windows"
currentCpuUsagePercentage?number

Current CPU usage percentage

currentMemoryUsagePercentage?number

Current RAM usage percentage

currentDiskUsagePercentage?number

Current disk usage percentage

currentAllocatedCpu?number

Current allocated CPU

currentAllocatedMemoryGiB?number

Current allocated memory in GiB

currentAllocatedDiskGiB?number

Current allocated disk in GiB

currentSnapshotCount?number

Current snapshot count

currentStartedSandboxes?number

Current number of started sandboxes

availabilityScore?number

Runner availability score

region*string

The region of the runner

name*string

The name of the runner

state*string

The state of the runner

Value in"initializing""ready""disabled""decommissioned""unresponsive"
lastChecked?string

The last time the runner was checked

unschedulable*boolean

Whether the runner is unschedulable

tags*array<string>

Tags associated with the runner

createdAt*string

The creation timestamp of the runner

updatedAt*string

The last update timestamp of the runner

version*stringDeprecated

The version of the runner (deprecated in favor of apiVersion)

apiVersion*stringDeprecated

The api version of the runner

runnerClass*"container"Deprecated

The class of the runner. Deprecated and always returns "container" for backward compatibility - use sandboxClass instead.

Value in"container"
appVersion?stringDeprecated

The app version of the runner

class?stringDeprecated

Deprecated runner class property

apiKey*string

The API key for the runner

regionType?string

The region type of the runner

Value in"shared""dedicated""custom"
curl -X GET 'http://localhost:3000/runners/by-sandbox/string'
{  "currentStartedSandboxes": 5,  "appVersion": "v0.0.0-dev",  "memory": 16,  "currentMemoryUsagePercentage": 68.2,  "apiKey": "dtn_1234567890",  "availabilityScore": 85,  "currentDiskUsagePercentage": 33.8,  "currentCpuUsagePercentage": 45.6,  "createdAt": "2023-10-01T12:00:00Z",  "apiVersion": "0",  "apiUrl": "https://api.runner1.example.com",  "regionType": "shared",  "id": "runner123",  "state": "initializing",  "unschedulable": false,  "currentAllocatedDiskGiB": 50000,  "class": "small",  "currentAllocatedMemoryGiB": 8000,  "gpuType": "gpuType",  "sandboxClass": "linux-vm",  "currentAllocatedCpu": 4000,  "updatedAt": "2023-10-01T12:00:00Z",  "proxyUrl": "https://proxy.runner1.example.com",  "cpu": 8,  "gpu": 1,  "currentSnapshotCount": 12,  "version": "0",  "tags": [    "gpu",    "us-east"  ],  "disk": 100,  "domain": "runner1.example.com",  "name": "runner1",  "runnerClass": "container",  "region": "us",  "lastChecked": "2024-10-01T12:00:00Z"}

Get runners by snapshot ref

GET
/runners/by-snapshot-ref

Authorization

headerAuthorizationBearer <token>

API Key access

Query Parameters

ref*string

Snapshot ref

Response Body

application/json
  1. response
[index: integer]?
curl -X GET 'http://localhost:3000/runners/by-snapshot-ref?ref=string'
[  {    "runnerDomain": "runner.example.com",    "runnerId": "123e4567-e89b-12d3-a456-426614174000",    "runnerSnapshotId": "123e4567-e89b-12d3-a456-426614174000"  }]

Get runner by ID

GET
/runners/{id}

Authorization

headerAuthorizationBearer <token>

API Key access

Path Parameters

id*string

Runner ID

Header Parameters

X-Daytona-Organization-ID?string

Use with JWT to specify the organization ID

Response Body

application/json
  1. response
id*string

The ID of the runner

domain?string

The domain of the runner

apiUrl?string

The API URL of the runner

proxyUrl?string

The proxy URL of the runner

cpu*number

The CPU capacity of the runner

memory*number

The memory capacity of the runner in GiB

disk*number

The disk capacity of the runner in GiB

gpu?number

The GPU capacity of the runner

gpuType?string

The type of GPU

sandboxClass?string

The sandbox class supported by this runner

Value in"linux-vm""container""windows"
currentCpuUsagePercentage?number

Current CPU usage percentage

currentMemoryUsagePercentage?number

Current RAM usage percentage

currentDiskUsagePercentage?number

Current disk usage percentage

currentAllocatedCpu?number

Current allocated CPU

currentAllocatedMemoryGiB?number

Current allocated memory in GiB

currentAllocatedDiskGiB?number

Current allocated disk in GiB

currentSnapshotCount?number

Current snapshot count

currentStartedSandboxes?number

Current number of started sandboxes

availabilityScore?number

Runner availability score

region*string

The region of the runner

name*string

The name of the runner

state*string

The state of the runner

Value in"initializing""ready""disabled""decommissioned""unresponsive"
lastChecked?string

The last time the runner was checked

unschedulable*boolean

Whether the runner is unschedulable

tags*array<string>

Tags associated with the runner

createdAt*string

The creation timestamp of the runner

updatedAt*string

The last update timestamp of the runner

version*stringDeprecated

The version of the runner (deprecated in favor of apiVersion)

apiVersion*stringDeprecated

The api version of the runner

runnerClass*"container"Deprecated

The class of the runner. Deprecated and always returns "container" for backward compatibility - use sandboxClass instead.

Value in"container"
appVersion?stringDeprecated

The app version of the runner

class?stringDeprecated

Deprecated runner class property

curl -X GET 'http://localhost:3000/runners/string'
{  "currentStartedSandboxes": 5,  "appVersion": "v0.0.0-dev",  "memory": 16,  "currentMemoryUsagePercentage": 68.2,  "availabilityScore": 85,  "currentDiskUsagePercentage": 33.8,  "currentCpuUsagePercentage": 45.6,  "createdAt": "2023-10-01T12:00:00Z",  "apiVersion": "0",  "apiUrl": "https://api.runner1.example.com",  "id": "runner123",  "state": "initializing",  "unschedulable": false,  "currentAllocatedDiskGiB": 50000,  "class": "small",  "currentAllocatedMemoryGiB": 8000,  "gpuType": "gpuType",  "sandboxClass": "linux-vm",  "currentAllocatedCpu": 4000,  "updatedAt": "2023-10-01T12:00:00Z",  "proxyUrl": "https://proxy.runner1.example.com",  "cpu": 8,  "gpu": 1,  "currentSnapshotCount": 12,  "version": "0",  "tags": [    "gpu",    "us-east"  ],  "disk": 100,  "domain": "runner1.example.com",  "name": "runner1",  "runnerClass": "container",  "region": "us",  "lastChecked": "2024-10-01T12:00:00Z"}

Delete runner

DELETE
/runners/{id}

Authorization

headerAuthorizationBearer <token>

API Key access

Path Parameters

id*string

Runner ID

Query Parameters

force?boolean

Delete the runner without waiting for sandboxes already marked for destruction. Requires the runner to have stopped reporting as ready.

Header Parameters

X-Daytona-Organization-ID?string

Use with JWT to specify the organization ID

Response Body

curl -X DELETE 'http://localhost:3000/runners/string'
Empty

Get runner by ID

GET
/runners/{id}/full

Authorization

headerAuthorizationBearer <token>

API Key access

Path Parameters

id*string

Runner ID

Response Body

application/json
  1. response
id*string

The ID of the runner

domain?string

The domain of the runner

apiUrl?string

The API URL of the runner

proxyUrl?string

The proxy URL of the runner

cpu*number

The CPU capacity of the runner

memory*number

The memory capacity of the runner in GiB

disk*number

The disk capacity of the runner in GiB

gpu?number

The GPU capacity of the runner

gpuType?string

The type of GPU

sandboxClass?string

The sandbox class supported by this runner

Value in"linux-vm""container""windows"
currentCpuUsagePercentage?number

Current CPU usage percentage

currentMemoryUsagePercentage?number

Current RAM usage percentage

currentDiskUsagePercentage?number

Current disk usage percentage

currentAllocatedCpu?number

Current allocated CPU

currentAllocatedMemoryGiB?number

Current allocated memory in GiB

currentAllocatedDiskGiB?number

Current allocated disk in GiB

currentSnapshotCount?number

Current snapshot count

currentStartedSandboxes?number

Current number of started sandboxes

availabilityScore?number

Runner availability score

region*string

The region of the runner

name*string

The name of the runner

state*string

The state of the runner

Value in"initializing""ready""disabled""decommissioned""unresponsive"
lastChecked?string

The last time the runner was checked

unschedulable*boolean

Whether the runner is unschedulable

tags*array<string>

Tags associated with the runner

createdAt*string

The creation timestamp of the runner

updatedAt*string

The last update timestamp of the runner

version*stringDeprecated

The version of the runner (deprecated in favor of apiVersion)

apiVersion*stringDeprecated

The api version of the runner

runnerClass*"container"Deprecated

The class of the runner. Deprecated and always returns "container" for backward compatibility - use sandboxClass instead.

Value in"container"
appVersion?stringDeprecated

The app version of the runner

class?stringDeprecated

Deprecated runner class property

apiKey*string

The API key for the runner

regionType?string

The region type of the runner

Value in"shared""dedicated""custom"
curl -X GET 'http://localhost:3000/runners/string/full'
{  "currentStartedSandboxes": 5,  "appVersion": "v0.0.0-dev",  "memory": 16,  "currentMemoryUsagePercentage": 68.2,  "apiKey": "dtn_1234567890",  "availabilityScore": 85,  "currentDiskUsagePercentage": 33.8,  "currentCpuUsagePercentage": 45.6,  "createdAt": "2023-10-01T12:00:00Z",  "apiVersion": "0",  "apiUrl": "https://api.runner1.example.com",  "regionType": "shared",  "id": "runner123",  "state": "initializing",  "unschedulable": false,  "currentAllocatedDiskGiB": 50000,  "class": "small",  "currentAllocatedMemoryGiB": 8000,  "gpuType": "gpuType",  "sandboxClass": "linux-vm",  "currentAllocatedCpu": 4000,  "updatedAt": "2023-10-01T12:00:00Z",  "proxyUrl": "https://proxy.runner1.example.com",  "cpu": 8,  "gpu": 1,  "currentSnapshotCount": 12,  "version": "0",  "tags": [    "gpu",    "us-east"  ],  "disk": 100,  "domain": "runner1.example.com",  "name": "runner1",  "runnerClass": "container",  "region": "us",  "lastChecked": "2024-10-01T12:00:00Z"}

Update runner scheduling status

PATCH
/runners/{id}/scheduling

Authorization

headerAuthorizationBearer <token>

API Key access

Path Parameters

id*string

Runner ID

Header Parameters

X-Daytona-Organization-ID?string

Use with JWT to specify the organization ID

Response Body

application/json
  1. response
id*string

The ID of the runner

domain?string

The domain of the runner

apiUrl?string

The API URL of the runner

proxyUrl?string

The proxy URL of the runner

cpu*number

The CPU capacity of the runner

memory*number

The memory capacity of the runner in GiB

disk*number

The disk capacity of the runner in GiB

gpu?number

The GPU capacity of the runner

gpuType?string

The type of GPU

sandboxClass?string

The sandbox class supported by this runner

Value in"linux-vm""container""windows"
currentCpuUsagePercentage?number

Current CPU usage percentage

currentMemoryUsagePercentage?number

Current RAM usage percentage

currentDiskUsagePercentage?number

Current disk usage percentage

currentAllocatedCpu?number

Current allocated CPU

currentAllocatedMemoryGiB?number

Current allocated memory in GiB

currentAllocatedDiskGiB?number

Current allocated disk in GiB

currentSnapshotCount?number

Current snapshot count

currentStartedSandboxes?number

Current number of started sandboxes

availabilityScore?number

Runner availability score

region*string

The region of the runner

name*string

The name of the runner

state*string

The state of the runner

Value in"initializing""ready""disabled""decommissioned""unresponsive"
lastChecked?string

The last time the runner was checked

unschedulable*boolean

Whether the runner is unschedulable

tags*array<string>

Tags associated with the runner

createdAt*string

The creation timestamp of the runner

updatedAt*string

The last update timestamp of the runner

version*stringDeprecated

The version of the runner (deprecated in favor of apiVersion)

apiVersion*stringDeprecated

The api version of the runner

runnerClass*"container"Deprecated

The class of the runner. Deprecated and always returns "container" for backward compatibility - use sandboxClass instead.

Value in"container"
appVersion?stringDeprecated

The app version of the runner

class?stringDeprecated

Deprecated runner class property

curl -X PATCH 'http://localhost:3000/runners/string/scheduling'
{  "currentStartedSandboxes": 5,  "appVersion": "v0.0.0-dev",  "memory": 16,  "currentMemoryUsagePercentage": 68.2,  "availabilityScore": 85,  "currentDiskUsagePercentage": 33.8,  "currentCpuUsagePercentage": 45.6,  "createdAt": "2023-10-01T12:00:00Z",  "apiVersion": "0",  "apiUrl": "https://api.runner1.example.com",  "id": "runner123",  "state": "initializing",  "unschedulable": false,  "currentAllocatedDiskGiB": 50000,  "class": "small",  "currentAllocatedMemoryGiB": 8000,  "gpuType": "gpuType",  "sandboxClass": "linux-vm",  "currentAllocatedCpu": 4000,  "updatedAt": "2023-10-01T12:00:00Z",  "proxyUrl": "https://proxy.runner1.example.com",  "cpu": 8,  "gpu": 1,  "currentSnapshotCount": 12,  "version": "0",  "tags": [    "gpu",    "us-east"  ],  "disk": 100,  "domain": "runner1.example.com",  "name": "runner1",  "runnerClass": "container",  "region": "us",  "lastChecked": "2024-10-01T12:00:00Z"}

Update runner draining status

PATCH
/runners/{id}/draining

Authorization

headerAuthorizationBearer <token>

API Key access

Path Parameters

id*string

Runner ID

Header Parameters

X-Daytona-Organization-ID?string

Use with JWT to specify the organization ID

Response Body

application/json
  1. response
id*string

The ID of the runner

domain?string

The domain of the runner

apiUrl?string

The API URL of the runner

proxyUrl?string

The proxy URL of the runner

cpu*number

The CPU capacity of the runner

memory*number

The memory capacity of the runner in GiB

disk*number

The disk capacity of the runner in GiB

gpu?number

The GPU capacity of the runner

gpuType?string

The type of GPU

sandboxClass?string

The sandbox class supported by this runner

Value in"linux-vm""container""windows"
currentCpuUsagePercentage?number

Current CPU usage percentage

currentMemoryUsagePercentage?number

Current RAM usage percentage

currentDiskUsagePercentage?number

Current disk usage percentage

currentAllocatedCpu?number

Current allocated CPU

currentAllocatedMemoryGiB?number

Current allocated memory in GiB

currentAllocatedDiskGiB?number

Current allocated disk in GiB

currentSnapshotCount?number

Current snapshot count

currentStartedSandboxes?number

Current number of started sandboxes

availabilityScore?number

Runner availability score

region*string

The region of the runner

name*string

The name of the runner

state*string

The state of the runner

Value in"initializing""ready""disabled""decommissioned""unresponsive"
lastChecked?string

The last time the runner was checked

unschedulable*boolean

Whether the runner is unschedulable

tags*array<string>

Tags associated with the runner

createdAt*string

The creation timestamp of the runner

updatedAt*string

The last update timestamp of the runner

version*stringDeprecated

The version of the runner (deprecated in favor of apiVersion)

apiVersion*stringDeprecated

The api version of the runner

runnerClass*"container"Deprecated

The class of the runner. Deprecated and always returns "container" for backward compatibility - use sandboxClass instead.

Value in"container"
appVersion?stringDeprecated

The app version of the runner

class?stringDeprecated

Deprecated runner class property

curl -X PATCH 'http://localhost:3000/runners/string/draining'
{  "currentStartedSandboxes": 5,  "appVersion": "v0.0.0-dev",  "memory": 16,  "currentMemoryUsagePercentage": 68.2,  "availabilityScore": 85,  "currentDiskUsagePercentage": 33.8,  "currentCpuUsagePercentage": 45.6,  "createdAt": "2023-10-01T12:00:00Z",  "apiVersion": "0",  "apiUrl": "https://api.runner1.example.com",  "id": "runner123",  "state": "initializing",  "unschedulable": false,  "currentAllocatedDiskGiB": 50000,  "class": "small",  "currentAllocatedMemoryGiB": 8000,  "gpuType": "gpuType",  "sandboxClass": "linux-vm",  "currentAllocatedCpu": 4000,  "updatedAt": "2023-10-01T12:00:00Z",  "proxyUrl": "https://proxy.runner1.example.com",  "cpu": 8,  "gpu": 1,  "currentSnapshotCount": 12,  "version": "0",  "tags": [    "gpu",    "us-east"  ],  "disk": 100,  "domain": "runner1.example.com",  "name": "runner1",  "runnerClass": "container",  "region": "us",  "lastChecked": "2024-10-01T12:00:00Z"}

Runner healthcheck

POST
/runners/healthcheck

Endpoint for version 2 runners to send healthcheck and metrics. Updates lastChecked timestamp and runner metrics.

Authorization

headerAuthorizationBearer <token>

API Key access

Request Body

application/json
  1. body
metrics?

Runner metrics

serviceHealth?array<>

Health status of individual services on the runner

domain?string

Runner domain

proxyUrl?string

Runner proxy URL

apiUrl?string

Runner API URL

appVersion*string

Runner app version

Response Body

Healthcheck received

curl -X POST 'http://localhost:3000/runners/healthcheck' \  -H 'Content-Type: application/json' \  -d '{  "appVersion": "v0.0.0-dev",  "apiUrl": "http://api.daytona.example.com:8080",  "proxyUrl": "http://proxy.daytona.example.com:8080",  "domain": "runner-123.daytona.example.com",  "serviceHealth": [    {      "healthy": false,      "errorReason": "Cannot connect to the runner",      "serviceName": "runner"    },    {      "healthy": false,      "errorReason": "Cannot connect to the runner",      "serviceName": "runner"    }  ],  "metrics": ""}'
Empty

Computersfor Agents

Isolated sandboxes for agent code,
ready in under 100 ms.

Start for Free