Patch runtime resources or policy

PATCH

/v2/runtimes/{runtime_id}

const url = 'https://api.runta.me/v2/runtimes/example?expected_revision=1';
const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"environment_variables":{"additionalProperty":"example"},"display_name":"example","egress_policy":{"mode":"denylist","denied_hosts":["example"]},"ingress_specs":[{"protocol":"http","runtime_port":1}],"idle_policy":{"mode":"disabled"},"llm_tool_io_capture_enabled":true,"vnc_enabled":true,"llm_token_saving_policy":{"json_array_enabled":true,"log_enabled":true,"search_results_enabled":true,"git_diff_enabled":true},"resources":{"limits":{"memory_mib":1},"requests":{"memory_mib":1,"disk_gib":1}},"secret_configuration":[{"secret_id":"example","environment":[],"egress_rules":[],"files":[]}]}'
};

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

curl --request PATCH \
  --url 'https://api.runta.me/v2/runtimes/example?expected_revision=1' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "environment_variables": { "additionalProperty": "example" }, "display_name": "example", "egress_policy": { "mode": "denylist", "denied_hosts": [ "example" ] }, "ingress_specs": [ { "protocol": "http", "runtime_port": 1 } ], "idle_policy": { "mode": "disabled" }, "llm_tool_io_capture_enabled": true, "vnc_enabled": true, "llm_token_saving_policy": { "json_array_enabled": true, "log_enabled": true, "search_results_enabled": true, "git_diff_enabled": true }, "resources": { "limits": { "memory_mib": 1 }, "requests": { "memory_mib": 1, "disk_gib": 1 } }, "secret_configuration": [ { "secret_id": "example", "environment": [], "egress_rules": [], "files": [] } ] }'

Authorizations

BearerAuth

Parameters

Path Parameters

runtime_id

required

Runtime UUID or display name.

string

Runtime UUID or display name.

Query Parameters

expected_revision

required

integer format: uint64

>= 1

Runtime aggregate revision required for optimistic concurrency.

Request Body^required

application/json

Runtime patch request.

object

environment_variables

Complete replacement of the runtime’s non-secret environment variables. An empty object removes every variable; omit to leave unchanged. The same name, value, and reservation rules as creation apply.

object

<= 64 properties

key

additional properties

string

display_name

New user-facing runtime name. The runtime UUID and data-plane identity remain unchanged.

string

>= 1 characters <= 63 characters

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

ingress_specs

Complete replacement ingress configuration. Omit to leave unchanged.

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

idle_policy

Idle policy. Omit to leave unchanged.

object

One of:

Disable automatic idle suspension and wakeup.

object

mode

required

string

Allowed values: disabled

llm_tool_io_capture_enabled

Whether official LLM HTTP API tool input/output capture is enabled. Omit to leave unchanged.

boolean

vnc_enabled

Enable or disable the on-demand shared VNC desktop. Omit to leave unchanged.

boolean

llm_token_saving_policy

Per-method LLM tool-output compression patch. Omit to leave unchanged.

object

json_array_enabled

boolean

log_enabled

boolean

search_results_enabled

boolean

git_diff_enabled

boolean

resources

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

>= 1

disk_gib

New overlay capacity in GiB. Only growth while fully shutdown is supported.

integer format: uint32

>= 16 <= 256

secret_configuration

Complete replacement inline secret configuration. Omit to leave unchanged.

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

Responses

200

Response envelope.

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": []
      }
    ]
  }
}

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"
  }
}

Patch runtime resources or policy

Authorizations

Parameters

Path Parameters

Query Parameters

Request Bodyrequired

Responses

200

Example

401

Example

403

Example

404

Example

409

Example

422

Example

429

Example

501

Example

503

Example

504

Example

default

Example

Request Body^required