Create a runtime

POST

/v2/runtimes

const url = 'https://api.runta.me/v2/runtimes';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"environment_variables":{},"egress_policy":{"mode":"denylist","denied_hosts":[]},"idle_policy":{"mode":"disabled"},"ingress_specs":[],"name":"example","resources":{"requests":{"vcpus":1,"memory_mib":1024},"limits":{"memory_mib":1024}},"image":{"id":"example","model_provider_protocol":"example","runtime_sign_in":false,"model_provider_base_url":"example","model_provider_model":"example"},"secret_configuration":[],"ssh_key_ids":[],"vnc_enabled":false,"repositories":[],"llm_tool_io_capture_enabled":false,"llm_token_saving_policy":{"json_array_enabled":false,"log_enabled":false,"search_results_enabled":false,"git_diff_enabled":false}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://api.runta.me/v2/runtimes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "environment_variables": {}, "egress_policy": { "mode": "denylist", "denied_hosts": [] }, "idle_policy": { "mode": "disabled" }, "ingress_specs": [], "name": "example", "resources": { "requests": { "vcpus": 1, "memory_mib": 1024 }, "limits": { "memory_mib": 1024 } }, "image": { "id": "example", "model_provider_protocol": "example", "runtime_sign_in": false, "model_provider_base_url": "example", "model_provider_model": "example" }, "secret_configuration": [], "ssh_key_ids": [], "vnc_enabled": false, "repositories": [], "llm_tool_io_capture_enabled": false, "llm_token_saving_policy": { "json_array_enabled": false, "log_enabled": false, "search_results_enabled": false, "git_diff_enabled": false } }'

Authorizations

BearerAuth

Parameters

Header Parameters

Idempotency-Key

string

>= 1 characters <= 255 characters

Optional caller-generated key reused across retries of one logical runtime creation.

Request Body^required

Runtime creation request.

application/json

One of:

object
object

Create a fresh runtime from a Runtime Image.

object

environment_variables

Non-secret environment variables the runtime carries. Names must match [A-Za-z_][A-Za-z0-9_]* and be at most 128 UTF-8 bytes. Names Runta sets itself are reserved: the RUNTA_ prefix, the runtime CA variables, the managed repository credentials, and the canonical names of the provider secret presets. Values must be at most 8192 UTF-8 bytes each and 65536 in total, and must not contain NUL, CR, or LF.

object

<= 64 properties

key

additional properties

string

egress_policy

Initial egress policy.

object

One of:

object
object

Deny matching hosts and allow all other egress destinations.

object

mode

required

string

Allowed values: denylist

denied_hosts

required

Host names or wildcard patterns to deny.

Array<string>

<= 128 items

idle_policy

Initial idle policy. Omit to use disabled.

object

One of:

Disable automatic idle suspension and wakeup.

object

mode

required

string

Allowed values: disabled

ingress_specs

Optional ingress specs.

Array<object>

default: <= 16 items

Public ingress forwarding rule.

object

protocol

required

Application-layer protocol.

string

Allowed values: http https

runtime_port

required

Port inside the runtime VM.

integer format: uint16

<= 65535

name

Human-readable runtime name.

string

nullable

resources

Runtime resource requests and limits.

object

limits

Resource limits.

object

memory_mib

required

Maximum memory in MiB.

integer format: uint64

>= 1

requests

Resource requests.

object

memory_mib

Requested baseline memory in MiB.

integer format: uint64

default: 1024 >= 1

vcpus

Requested virtual CPUs.

integer format: uint32

default: 1 >= 1 <= 2147483647

disk_gib

Requested overlay virtual capacity in GiB.

integer format: uint32

>= 16 <= 256

image

Runtime Image selection. Omit on a fresh create to use the default variant.

object

required

string

>= 1 characters

model_provider_protocol

string

nullable

runtime_sign_in

boolean

model_provider_base_url

HTTPS endpoint the agent is configured against. Omit to use the image’s default. Only images advertising allow_custom_base_url accept another endpoint.

string

nullable

model_provider_model

Model the agent is configured to use. Omit to use the image’s default.

string

nullable

secret_configuration

Complete inline secret injection configuration.

Array<object>

default:

Inline injection configuration for one tenant secret.

object

secret_id

required

string

environment

Array<object>

default:

Environment variable populated from a secret.

object

name

required

string

value_template

required

string

egress_rules

Array<object>

default:

HTTP egress credential populated from a secret.

object

host_pattern

required

string

path_pattern

string

nullable

action

required

Where an egress secret is injected.

string

Allowed values: header query

name

required

string

value_template

required

string

files

Array<object>

default:

Managed credential file populated from a secret.

object

path

required

Delivery path, relative to the guest home directory.

string

value_template

required

string

ssh_key_ids

Personal SSH key UUIDs to attach atomically.

Array<string>

default:

vnc_enabled

Start the shared VNC desktop whenever the runtime is running.

boolean

repositories

GitHub repositories to check out during runtime setup, in checkout order. The first repository becomes the default workspace. Repositories may span GitHub App installations.

Array<object>

default: <= 16 items

object

repository_id

required

integer format: int64

branch

string

nullable

llm_tool_io_capture_enabled

Opt in to official LLM HTTP API tool input/output capture.

boolean

llm_token_saving_policy

Initial LLM tool-output compression policy. Omit to disable every method.

object

json_array_enabled

boolean

log_enabled

boolean

search_results_enabled

boolean

git_diff_enabled

boolean

Responses

201

Runtime resource created.

application/json

Response envelope.

object

data

required

Runtime response object.

object

environment_variables

Non-secret environment variables the runtime carries.

object

<= 64 properties

key

additional properties

string

display_name

required

User-chosen display name.

string

egress_policy

required

Egress policy.

object

One of:

object
object

Deny matching hosts and allow all other egress destinations.

object

mode

required

string

Allowed values: denylist

denied_hosts

required

Host names or wildcard patterns to deny.

Array<string>

<= 128 items

llm_tool_io_capture_enabled

required

Whether official LLM HTTP API tool input/output capture is enabled.

boolean

llm_token_saving_policy

required

Canonical LLM tool-output compression policy.

object

json_array_enabled

required

boolean

log_enabled

required

boolean

search_results_enabled

required

boolean

git_diff_enabled

required

boolean

idle_policy

required

Runtime idle suspension and automatic wakeup policy.

object

One of:

Disable automatic idle suspension and wakeup.

object

mode

required

string

Allowed values: disabled

required

Stable runtime UUID.

string

created_at

required

RFC3339 timestamp when the control-plane runtime row was created.

string

updated_at

required

RFC3339 timestamp of the last control-plane runtime row mutation.

string

ingress_specs

required

Active ingress specs.

Array<object>

Public ingress forwarding rule.

object

protocol

required

Application-layer protocol.

string

Allowed values: http https

runtime_port

required

Port inside the runtime VM.

integer format: uint16

<= 65535

resources

required

Runtime resource state.

object

current

required

Current resource allocation.

object

memory_mib

required

Current memory allocation in MiB.

integer format: uint64

>= 1

observed_disk_gib

required

Worker-observed overlay virtual capacity in GiB.

integer format: uint32

limits

required

Resource limits.

object

memory_mib

required

Maximum memory in MiB.

integer format: uint64

>= 1

requests

required

Resource requests.

object

memory_mib

required

Requested baseline memory in MiB.

integer format: uint64

>= 1

vcpus

required

Requested virtual CPUs.

integer format: uint32

>= 1 <= 2147483647

disk_gib

required

Target overlay virtual capacity in GiB.

integer format: uint32

>= 16 <= 256

image_id

required

Stable Runtime Image variant identifier.

string

status

required

Runtime status.

string

Allowed values: running paused shutdown creating deleting error crashed suspended unavailable

degraded

required

Whether a running runtime has lacked a new successful heartbeat for at least 60 seconds.

boolean

desired_status

required

Control-plane target lifecycle state.

string

Allowed values: running paused suspended shutdown deleting

ssh_enabled

required

Whether this runtime supports SSH access.

boolean

vnc_enabled

required

Whether the shared VNC desktop is configured to run with this runtime.

boolean

vnc_ready

required

Whether the current Worker assignment has published a ready VNC mapping.

boolean

vnc_error_code

Bounded machine-readable VNC startup failure code.

string

nullable

vnc_connection

required

Fixed native VNC gateway connection parameters for this runtime’s zone.

object

hostname

required

Public VNC gateway DNS hostname.

string

>= 1 characters

port

required

Public native VNC TCP port.

integer format: uint16

>= 1 <= 65535

username

required

Username required by the X509Plain handshake.

string

Allowed values: runta

security_type

required

VeNCrypt authentication subtype required by the gateway.

string

Allowed values: X509Plain

error_code

Bounded machine-readable provisioning failure code.

string

nullable

owner_user_id

required

Organization member who owns the runtime.

string

can_manage

required

Whether the current caller may perform control operations on this runtime.

boolean

revision

required

Monotonic runtime aggregate revision.

integer format: uint64

>= 1

secret_configuration

required

Canonical inline secret injection configuration.

Array<object>

Inline injection configuration for one tenant secret.

object

secret_id

required

string

environment

Array<object>

default:

Environment variable populated from a secret.

object

name

required

string

value_template

required

string

egress_rules

Array<object>

default:

HTTP egress credential populated from a secret.

object

host_pattern

required

string

path_pattern

string

nullable

action

required

Where an egress secret is injected.

string

Allowed values: header query

name

required

string

value_template

required

string

files

Array<object>

default:

Managed credential file populated from a secret.

object

path

required

Delivery path, relative to the guest home directory.

string

value_template

required

string

Example

{
  "data": {
    "egress_policy": {
      "mode": "denylist"
    },
    "idle_policy": {
      "mode": "disabled"
    },
    "ingress_specs": [
      {
        "protocol": "http"
      }
    ],
    "status": "running",
    "desired_status": "running",
    "vnc_connection": {
      "username": "runta",
      "security_type": "X509Plain"
    },
    "secret_configuration": [
      {
        "environment": [],
        "egress_rules": [],
        "files": []
      }
    ]
  }
}

Headers

Location

string

Canonical Runtime resource URI.

401

Missing, malformed, or rejected bearer token

application/json

object

error

required

object

code

required

string

Allowed values: already_exists command_failed deadline_exceeded failed_precondition internal invalid_argument not_found permission_denied rate_limited unauthenticated unavailable unimplemented

message

required

string

request_id

required

UUID v7 correlation ID shared with the X-Request-Id response header.

string

Example

{
  "error": {
    "code": "already_exists"
  }
}

403

The bearer token is not allowed to perform this action

application/json

object

error

required

object

code

required

string

Allowed values: already_exists command_failed deadline_exceeded failed_precondition internal invalid_argument not_found permission_denied rate_limited unauthenticated unavailable unimplemented

message

required

string

request_id

required

UUID v7 correlation ID shared with the X-Request-Id response header.

string

Example

{
  "error": {
    "code": "already_exists"
  }
}

404

The requested resource was not found

application/json

object

error

required

object

code

required

string

Allowed values: already_exists command_failed deadline_exceeded failed_precondition internal invalid_argument not_found permission_denied rate_limited unauthenticated unavailable unimplemented

message

required

string

request_id

required

UUID v7 correlation ID shared with the X-Request-Id response header.

string

Example

{
  "error": {
    "code": "already_exists"
  }
}

409

The request conflicts with current resource state

application/json

object

error

required

object

code

required

string

Allowed values: already_exists command_failed deadline_exceeded failed_precondition internal invalid_argument not_found permission_denied rate_limited unauthenticated unavailable unimplemented

message

required

string

request_id

required

UUID v7 correlation ID shared with the X-Request-Id response header.

string

Example

{
  "error": {
    "code": "already_exists"
  }
}

422

Validation or application error

application/json

object

error

required

object

code

required

string

Allowed values: already_exists command_failed deadline_exceeded failed_precondition internal invalid_argument not_found permission_denied rate_limited unauthenticated unavailable unimplemented

message

required

string

request_id

required

UUID v7 correlation ID shared with the X-Request-Id response header.

string

Example

{
  "error": {
    "code": "already_exists"
  }
}

429

Rate limit exceeded

application/json

object

error

required

object

code

required

string

Allowed values: already_exists command_failed deadline_exceeded failed_precondition internal invalid_argument not_found permission_denied rate_limited unauthenticated unavailable unimplemented

message

required

string

request_id

required

UUID v7 correlation ID shared with the X-Request-Id response header.

string

Example

{
  "error": {
    "code": "already_exists"
  }
}

501

Operation is not implemented

application/json

object

error

required

object

code

required

string

Allowed values: already_exists command_failed deadline_exceeded failed_precondition internal invalid_argument not_found permission_denied rate_limited unauthenticated unavailable unimplemented

message

required

string

request_id

required

UUID v7 correlation ID shared with the X-Request-Id response header.

string

Example

{
  "error": {
    "code": "already_exists"
  }
}

503

Upstream service is unavailable

application/json

object

error

required

object

code

required

string

Allowed values: already_exists command_failed deadline_exceeded failed_precondition internal invalid_argument not_found permission_denied rate_limited unauthenticated unavailable unimplemented

message

required

string

request_id

required

UUID v7 correlation ID shared with the X-Request-Id response header.

string

Example

{
  "error": {
    "code": "already_exists"
  }
}

504

Upstream request timed out

application/json

object

error

required

object

code

required

string

Allowed values: already_exists command_failed deadline_exceeded failed_precondition internal invalid_argument not_found permission_denied rate_limited unauthenticated unavailable unimplemented

message

required

string

request_id

required

UUID v7 correlation ID shared with the X-Request-Id response header.

string

Example

{
  "error": {
    "code": "already_exists"
  }
}

default

Error response

application/json

object

error

required

object

code

required

string

Allowed values: already_exists command_failed deadline_exceeded failed_precondition internal invalid_argument not_found permission_denied rate_limited unauthenticated unavailable unimplemented

message

required

string

request_id

required

UUID v7 correlation ID shared with the X-Request-Id response header.

string

Example

{
  "error": {
    "code": "already_exists"
  }
}

Create a runtime

Authorizations

Parameters

Header Parameters

Request Bodyrequired

Responses

201

Example

Headers

401

Example

403

Example

404

Example

409

Example

422

Example

429

Example

501

Example

503

Example

504

Example

default

Example

Request Body^required