Enable the runtime VNC desktop

POST

/v2/runtimes/{runtime_id}/vnc/enable

curl --request POST \
  --url 'https://api.runta.me/v2/runtimes/example/vnc/enable?expected_revision=1' \
  --header 'Authorization: Bearer <token>'

• Hosted public API

Authorizations

• BearerAuth

Parameters

Path Parameters

runtime_id

required

string

Query Parameters

expected_revision

required

integer format: uint64

>= 1

Runtime aggregate revision required for optimistic concurrency.

Responses

200

Response envelope.

Media typeapplication/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

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

object

Allow only matching egress destinations.

object

mode

required

string

Allowed values: allowlist

allowed_hosts

required

Host names or wildcard patterns to allow.

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:

object

Disable automatic idle suspension and wakeup.

object

mode

required

string

Allowed values: disabled

object

Automatically suspend an idle runtime, but require an explicit Start to wake it.

object

mode

required

string

Allowed values: suspend_only

suspend_after_secs

required

Idle duration before automatic suspension.

integer format: uint32

>= 1 <= 2147483647

object

Automatically suspend an idle runtime and wake it on supported activity.

object

mode

required

string

Allowed values: suspend_and_wakeup

suspend_after_secs

required

Idle duration before automatic suspension.

integer format: uint32

>= 1 <= 2147483647

id

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

Media typeapplication/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

Media typeapplication/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

Media typeapplication/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

Media typeapplication/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

Media typeapplication/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

Media typeapplication/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

Media typeapplication/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

Media typeapplication/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

Media typeapplication/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

Media typeapplication/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"
  }
}