Create a runtime

POST

/v1/runtimes

const url = 'http://127.0.0.1:8080/v1/runtimes';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"checkpoint_id":"example","environment_variables":{},"egress_policy":{"mode":"denylist","allowed_hosts":[],"denied_hosts":[]},"idle_policy":{"mode":"disabled"},"ingress_specs":[],"name":"example","resources":{"requests":{"vcpus":1,"memory_mib":1024},"limits":{"memory_mib":1024}},"runtime_agent":"example","runtime_agent_post_install_script":"example","runtime_agent_post_config_script":"example","runtime_agent_secret_preset":"example","llm_tool_io_capture_enabled":true,"llm_token_saving_policy":{"json_array_enabled":true,"log_enabled":true,"search_results_enabled":true,"git_diff_enabled":true}}'
};

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

curl --request POST \
  --url http://127.0.0.1:8080/v1/runtimes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "checkpoint_id": "example", "environment_variables": {}, "egress_policy": { "mode": "denylist", "allowed_hosts": [], "denied_hosts": [] }, "idle_policy": { "mode": "disabled" }, "ingress_specs": [], "name": "example", "resources": { "requests": { "vcpus": 1, "memory_mib": 1024 }, "limits": { "memory_mib": 1024 } }, "runtime_agent": "example", "runtime_agent_post_install_script": "example", "runtime_agent_post_config_script": "example", "runtime_agent_secret_preset": "example", "llm_tool_io_capture_enabled": true, "llm_token_saving_policy": { "json_array_enabled": true, "log_enabled": true, "search_results_enabled": true, "git_diff_enabled": true } }'

Authorizations

BearerAuth

Parameters

Header Parameters

X-Runta-Idempotency-Key

string

>= 1 characters <= 128 characters

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

Request Body^required

Runtime creation request.

application/json

Runtime creation request.

object

checkpoint_id

Checkpoint UUID to restore from.

string

nullable

environment_variables

Non-secret environment variables stored visibly on this runtime. Names must match [A-Za-z_][A-Za-z0-9_]* and be at most 128 UTF-8 bytes; Runta-managed, provider, credential, and runtime CA names are reserved. Values must be strings of at most 8192 UTF-8 bytes without NUL, CR, or LF, with at most 65536 value bytes across the map.

object

<= 64 properties

key

additional properties

string

egress_policy

Initial egress policy.

object

mode

required

Egress gateway mode.

string

Allowed values: denylist allowlist

allowed_hosts

required

Host names or wildcard patterns allowed in allowlist mode.

Array<string>

<= 128 items

denied_hosts

required

Host names or wildcard patterns denied in denylist mode.

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: <= 1 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

runtime_agent

Agent manifest key to install/configure after runtime creation.

string

nullable

runtime_agent_post_install_script

Internal post-install script to run with the runtime setup operation.

string

nullable

runtime_agent_post_config_script

Internal script to run after the runtime agent and repository setup complete.

string

nullable

runtime_agent_secret_preset

Internal secret preset selected for this runtime agent invocation.

string

nullable

llm_tool_io_capture_enabled

Capture official LLM HTTP API tool input/output for WatchFox insights. Pass false to opt out.

boolean

default: true

llm_token_saving_policy

Initial LLM tool-output compression policy. Omitted methods default to enabled; pass false to opt out.

object

json_array_enabled

boolean

default: true

log_enabled

boolean

default: true

search_results_enabled

boolean

default: true

git_diff_enabled

boolean

default: true

Responses

200

Response envelope.

application/json

Response envelope.

object

data

required

Runtime response object.

object

display_name

required

User-chosen display name.

string

environment_variables

required

Non-secret environment variables stored visibly on this runtime. Secret-derived variables are excluded. Names and values use the byte limits documented by CreateRuntimeRequest.environment_variables.

object

<= 64 properties

key

additional properties

string

egress_policy

required

Egress policy.

object

mode

required

Egress gateway mode.

string

Allowed values: denylist allowlist

allowed_hosts

required

Host names or wildcard patterns allowed in allowlist mode.

Array<string>

<= 128 items

denied_hosts

required

Host names or wildcard patterns denied in denylist mode.

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

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

agent

Runtime-scoped agent setup metadata.

object

key

required

Agent manifest key.

string

status

required

Agent setup status.

string

Allowed values: queued running succeeded failed

log_path

required

Runtime-local setup log path.

string

error

required

Last setup error, if any.

string

nullable

updated_at

required

RFC3339 timestamp of the last setup state change.

string

nullable

status

required

Runtime status.

string

Allowed values: running paused shutdown creating deleting error crashed suspended

ssh_enabled

required

Whether this runtime supports SSH access.

boolean

Example

{
  "data": {
    "egress_policy": {
      "mode": "denylist"
    },
    "idle_policy": {
      "mode": "disabled"
    },
    "ingress_specs": [
      {
        "protocol": "http"
      }
    ],
    "agent": {
      "status": "queued"
    },
    "status": "running"
  }
}

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

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

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

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

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

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

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

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

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

Example

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

Create a runtime

Authorizations

Parameters

Header Parameters

Request Bodyrequired

Responses

200

Example

401

Example

403

Example

404

Example

409

Example

422

Example

429

Example

503

Example

504

Example

default

Example

Request Body^required