---
title: "Create a runtime"
method: POST
path: "/v2/runtimes"
tags: ["Runtimes"]
---

# Create a runtime

`POST /v2/runtimes`

## Request

- Base URL: `https://api.runta.com`
- URL: `https://api.runta.com/v2/runtimes`
- Auth: HTTP bearer

## Headers

- `Idempotency-Key` string

## Request body

- union: Fresh runtime creation or checkpoint restoration request.
  - FreshRuntimeCreateRequest: Create a fresh runtime from a Runtime Image.
    - `environment_variables` object: 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.
    - `egress_policy` union: Per-runtime egress gateway policy.
      - DenylistEgressPolicy: Deny matching hosts and allow all other egress destinations.
        - `mode` 'denylist', required
        - `denied_hosts` string[], required: Host names, wildcard patterns, IP addresses, or CIDR ranges to deny.
      - AllowlistEgressPolicy: Allow only matching egress destinations.
        - `mode` 'allowlist', required
        - `allowed_hosts` string[], required: Host names, wildcard patterns, IP addresses, or CIDR ranges to allow.
    - `idle_policy` union: Runtime idle suspension and automatic wakeup policy.
      - DisabledIdlePolicy: Disable automatic idle suspension and wakeup.
        - `mode` 'disabled', required
      - SuspendOnlyIdlePolicy: Automatically suspend an idle runtime, but require an explicit Start to wake it.
        - `mode` 'suspend_only', required
        - `suspend_after_secs` integer, required: Idle duration before automatic suspension.
      - SuspendAndWakeupIdlePolicy: Automatically suspend an idle runtime and wake it on supported activity.
        - `mode` 'suspend_and_wakeup', required
        - `suspend_after_secs` integer, required: Idle duration before automatic suspension.
    - `auto_shutdown_policy` TimeoutPolicy
      - `mode` 'disabled' | 'enabled', required
      - `after_seconds` integer: Required for enabled and forbidden for disabled. An explicit save restarts only this policy’s clock.
    - `auto_delete_policy` TimeoutPolicy
      - `mode` 'disabled' | 'enabled', required
      - `after_seconds` integer: Required for enabled and forbidden for disabled. An explicit save restarts only this policy’s clock.
    - `ingress_specs` PublicIngressSpec[]: Optional ingress specs.
      - `protocol` 'http' | 'https', required: HTTP/HTTPS application-layer ingress protocol.
      - `runtime_port` integer, required: Port inside the runtime VM.
    - `name` string, nullable: Human-readable runtime name.
    - `resources` CreateRuntimeResources: Resource requests and limits for runtime creation.
      - `limits` RuntimeResourceLimits: Runtime resource limits.
        - `memory_mib` integer, required: Maximum memory in MiB.
      - `requests` CreateRuntimeResourceRequests: Resource requests for runtime creation.
        - `memory_mib` integer: Requested baseline memory in MiB.
        - `vcpus` integer: Requested virtual CPUs.
        - `disk_gib` integer: Requested overlay virtual capacity in GiB.
    - `image` CreateRuntimeImageSelection
      - `id` string, required
      - `model_provider_protocol` string, nullable
      - `runtime_sign_in` boolean
      - `model_provider_base_url` string, nullable: HTTPS endpoint the agent is configured against. Omit to use the image's default. Only images advertising allow_custom_base_url accept another endpoint.
      - `model_provider_model` string, nullable: Model the agent is configured to use. Omit to use the image's default.
    - `secret_configuration` RuntimeSecretConfiguration[]: Complete inline secret injection configuration.
      - `secret_id` string, required
      - `environment` SecretEnvironmentInjection[]
        - `name` string, required
        - `value_template` string, required
      - `egress_rules` SecretEgressInjection[]
        - `host_pattern` string, required
        - `path_pattern` string, nullable
        - `action` 'header' | 'query', required: Where an egress secret is injected.
        - `name` string, required
        - `value_template` string, required
      - `files` SecretFileInjection[]
        - `path` string, required: Delivery path, relative to the guest home directory.
        - `value_template` string, required
    - `ssh_key_ids` string[]: Personal SSH key UUIDs to attach atomically.
    - `vnc_enabled` boolean: Start the shared VNC desktop whenever the runtime is running.
    - `repositories` RuntimeRepositorySelection[]: GitHub repositories to check out during runtime setup, in checkout order. The first repository becomes the default workspace. Repositories may span GitHub App installations.
      - `repository_id` integer, required
      - `branch` string, nullable
    - `llm_tool_io_capture_enabled` boolean: Opt in to official LLM HTTP API tool input/output capture.
    - `llm_session_content_capture_enabled` boolean: Explicitly enable capture of user, assistant, and tool conversation content. Disabled by default. Independent from tool-only capture.
    - `tls_passthrough_hosts` string[]: HTTPS host patterns that use opaque TLS tunnels to the original destination, taking precedence over secret injection, LLM capture, token saving, and model routing.
    - `tcp_allowlist` string[]: Exact FQDN:port destinations that may receive raw TCP from the runtime. Empty denies raw TCP. The gateway allows a connection only after the name resolves to that public IPv4 address and port.
    - `llm_token_saving_policy` CreateLlmTokenSavingPolicy: Initial per-runtime LLM tool-output compression settings. Omitted fields default to false.
      - `json_array_enabled` boolean
      - `log_enabled` boolean
      - `search_results_enabled` boolean
      - `git_diff_enabled` boolean
  - CheckpointRuntimeRestoreRequest: Restore a runtime from a checkpoint. Keep the checkpoint’s Runtime Image identity and disk size. A live checkpoint restores guest memory and running processes. It keeps CPU and memory fixed. A cold checkpoint stores only disk state and boots fresh. Use resources to select CPU and memory. Omit resources to use the recorded checkpoint values.
    - `checkpoint_id` string, required: Checkpoint UUID to restore from.
    - `resources` ColdRestoreResources: CPU and memory for a cold checkpoint restore. Omit the object to use the recorded checkpoint values. A cold checkpoint stores only disk state and boots fresh. These values can be smaller or larger. A live checkpoint restores guest memory and running processes. It keeps CPU and memory fixed and rejects this object.
      - `limits` RuntimeResourceLimits: Runtime resource limits.
        - `memory_mib` integer, required: Maximum memory in MiB.
      - `requests` ColdRestoreResourceRequests, required: CPU and baseline memory for a cold checkpoint restore.
        - `memory_mib` integer, required: Baseline memory in MiB. This becomes the restored runtime's current memory. It may be smaller or larger than the checkpoint.
        - `vcpus` integer, required: Virtual CPUs for the restored runtime. This may be smaller or larger than the checkpoint.
    - `egress_policy` union: Per-runtime egress gateway policy.
      - DenylistEgressPolicy: Deny matching hosts and allow all other egress destinations.
        - `mode` 'denylist', required
        - `denied_hosts` string[], required: Host names, wildcard patterns, IP addresses, or CIDR ranges to deny.
      - AllowlistEgressPolicy: Allow only matching egress destinations.
        - `mode` 'allowlist', required
        - `allowed_hosts` string[], required: Host names, wildcard patterns, IP addresses, or CIDR ranges to allow.
    - `idle_policy` union: Runtime idle suspension and automatic wakeup policy.
      - DisabledIdlePolicy: Disable automatic idle suspension and wakeup.
        - `mode` 'disabled', required
      - SuspendOnlyIdlePolicy: Automatically suspend an idle runtime, but require an explicit Start to wake it.
        - `mode` 'suspend_only', required
        - `suspend_after_secs` integer, required: Idle duration before automatic suspension.
      - SuspendAndWakeupIdlePolicy: Automatically suspend an idle runtime and wake it on supported activity.
        - `mode` 'suspend_and_wakeup', required
        - `suspend_after_secs` integer, required: Idle duration before automatic suspension.
    - `auto_shutdown_policy` TimeoutPolicy
      - `mode` 'disabled' | 'enabled', required
      - `after_seconds` integer: Required for enabled and forbidden for disabled. An explicit save restarts only this policy’s clock.
    - `auto_delete_policy` TimeoutPolicy
      - `mode` 'disabled' | 'enabled', required
      - `after_seconds` integer: Required for enabled and forbidden for disabled. An explicit save restarts only this policy’s clock.
    - `ingress_specs` PublicIngressSpec[]: Optional ingress specs.
      - `protocol` 'http' | 'https', required: HTTP/HTTPS application-layer ingress protocol.
      - `runtime_port` integer, required: Port inside the runtime VM.
    - `name` string, nullable: Human-readable runtime name.
    - `secret_configuration` RuntimeSecretConfiguration[]: Complete inline secret injection configuration override. Omit or pass an empty array to inherit the checkpoint snapshot.
      - `secret_id` string, required
      - `environment` SecretEnvironmentInjection[]
        - `name` string, required
        - `value_template` string, required
      - `egress_rules` SecretEgressInjection[]
        - `host_pattern` string, required
        - `path_pattern` string, nullable
        - `action` 'header' | 'query', required: Where an egress secret is injected.
        - `name` string, required
        - `value_template` string, required
      - `files` SecretFileInjection[]
        - `path` string, required: Delivery path, relative to the guest home directory.
        - `value_template` string, required
    - `ssh_key_ids` string[]: Personal SSH key UUIDs to attach atomically.
    - `vnc_enabled` boolean: Start the shared VNC desktop whenever the runtime is running.
    - `repositories` RuntimeRepositorySelection[]: GitHub repository override in checkout order. Omit or pass an empty array to inherit the checkpoint snapshot. The first repository becomes the default workspace.
      - `repository_id` integer, required
      - `branch` string, nullable
    - `llm_tool_io_capture_enabled` boolean: Opt in to official LLM HTTP API tool input/output capture.
    - `llm_session_content_capture_enabled` boolean: Explicitly enable capture of user, assistant, and tool conversation content. Disabled by default. Independent from tool-only capture.
    - `tls_passthrough_hosts` string[]: Complete HTTPS passthrough host override. Matching TLS connections bypass secret injection, LLM capture, token saving, and model routing and connect to the original destination. Omit or pass an empty array to inherit the checkpoint snapshot.
    - `tcp_allowlist` string[]: Complete raw TCP allowlist override. Each entry is an exact FQDN:port. Omit or pass an empty array to inherit the checkpoint snapshot.
    - `llm_token_saving_policy` CreateLlmTokenSavingPolicy: Initial per-runtime LLM tool-output compression settings. Omitted fields default to false.
      - `json_array_enabled` boolean
      - `log_enabled` boolean
      - `search_results_enabled` boolean
      - `git_diff_enabled` boolean

## Response `201`

Runtime resource created.

- RuntimeResponse: Response envelope.
  - `data` Runtime, required: Runtime response object.
    - `auto_shutdown_at` string, date-time: Current session deadline, absent until running or when disabled.
    - `auto_delete_at` string, date-time: Deletion deadline, absent until shutdown or when disabled.
    - `environment_variables` object: Non-secret environment variables the runtime carries.
    - `display_name` string, required: User-chosen display name.
    - `egress_policy` union, required: Per-runtime egress gateway policy.
      - DenylistEgressPolicy: Deny matching hosts and allow all other egress destinations.
        - `mode` 'denylist', required
        - `denied_hosts` string[], required: Host names, wildcard patterns, IP addresses, or CIDR ranges to deny.
      - AllowlistEgressPolicy: Allow only matching egress destinations.
        - `mode` 'allowlist', required
        - `allowed_hosts` string[], required: Host names, wildcard patterns, IP addresses, or CIDR ranges to allow.
    - `llm_tool_io_capture_enabled` boolean, required: Whether official LLM HTTP API tool input/output capture is enabled.
    - `llm_session_content_capture_enabled` boolean, required: Explicitly enable capture of user, assistant, and tool conversation content. Disabled by default. Independent from tool-only capture.
    - `tls_passthrough_hosts` string[]: HTTPS host patterns using opaque TLS tunnels to the original destination, bypassing secret injection, LLM capture, token saving, and model routing.
    - `tcp_allowlist` string[]: Exact FQDN:port destinations that may receive raw TCP from the runtime. Empty denies raw TCP.
    - `llm_token_saving_policy` LlmTokenSavingPolicy, required: Canonical per-runtime LLM tool-output compression settings.
      - `json_array_enabled` boolean, required
      - `log_enabled` boolean, required
      - `search_results_enabled` boolean, required
      - `git_diff_enabled` boolean, required
    - `idle_policy` union, required: Runtime idle suspension and automatic wakeup policy.
      - DisabledIdlePolicy: Disable automatic idle suspension and wakeup.
        - `mode` 'disabled', required
      - SuspendOnlyIdlePolicy: Automatically suspend an idle runtime, but require an explicit Start to wake it.
        - `mode` 'suspend_only', required
        - `suspend_after_secs` integer, required: Idle duration before automatic suspension.
      - SuspendAndWakeupIdlePolicy: Automatically suspend an idle runtime and wake it on supported activity.
        - `mode` 'suspend_and_wakeup', required
        - `suspend_after_secs` integer, required: Idle duration before automatic suspension.
    - `auto_shutdown_policy` TimeoutPolicy
      - `mode` 'disabled' | 'enabled', required
      - `after_seconds` integer: Required for enabled and forbidden for disabled. An explicit save restarts only this policy’s clock.
    - `auto_delete_policy` TimeoutPolicy
      - `mode` 'disabled' | 'enabled', required
      - `after_seconds` integer: Required for enabled and forbidden for disabled. An explicit save restarts only this policy’s clock.
    - `id` string, required: Stable runtime UUID.
    - `created_at` string, required: RFC3339 timestamp when the control-plane runtime row was created.
    - `updated_at` string, required: RFC3339 timestamp of the last control-plane runtime row mutation.
    - `ingress_specs` PublicIngressSpec[], required: Active ingress specs.
      - `protocol` 'http' | 'https', required: HTTP/HTTPS application-layer ingress protocol.
      - `runtime_port` integer, required: Port inside the runtime VM.
    - `resources` RuntimeResources, required: Runtime resource requests and limits.
      - `current` RuntimeResourceCurrent, required: Current runtime resource allocation.
        - `memory_mib` integer, required: Current memory allocation in MiB.
        - `observed_disk_gib` integer, required: Worker-observed overlay virtual capacity in GiB.
      - `limits` RuntimeResourceLimits, required: Runtime resource limits.
        - `memory_mib` integer, required: Maximum memory in MiB.
      - `requests` RuntimeResourceRequests, required: Runtime resource requests.
        - `memory_mib` integer, required: Requested baseline memory in MiB.
        - `vcpus` integer, required: Requested virtual CPUs.
        - `disk_gib` integer, required: Target overlay virtual capacity in GiB.
    - `image_id` string, required: Stable Runtime Image variant identifier.
    - `status` 'running' | 'paused' | 'shutdown' | 'creating' | 'deleting' | 'error' | 'crashed' | 'suspended' | 'unavailable', required: Runtime state of a runtime.
    - `degraded` boolean, required: Whether a running runtime has lacked a new successful heartbeat for at least 60 seconds.
    - `desired_status` 'running' | 'paused' | 'suspended' | 'shutdown' | 'deleting', required: Control-plane target lifecycle state.
    - `ssh_enabled` boolean, required: Whether this runtime supports SSH access.
    - `vnc_enabled` boolean, required: Whether the shared VNC desktop is configured to run with this runtime.
    - `vnc_ready` boolean, required: Whether the current Worker assignment has published a ready VNC mapping.
    - `vnc_error_code` string, nullable: Bounded machine-readable VNC startup failure code.
    - `vnc_connection` VncGatewayConnection, required: Fixed native VNC gateway connection parameters for runtimes in this zone.
      - `hostname` string, required: Public VNC gateway DNS hostname.
      - `port` integer, required: Public native VNC TCP port.
      - `username` 'runta', required: Username required by the X509Plain handshake.
      - `security_type` 'X509Plain', required: VeNCrypt authentication subtype required by the gateway.
    - `error_code` string, nullable: Bounded machine-readable provisioning failure code.
    - `error_message` string, nullable: Current runtime failure reason, bounded to 4096 UTF-8 bytes. Cleared when the failure recovers.
    - `owner_user_id` string, required: Organization member who owns the runtime.
    - `can_manage` boolean, required: Whether the current caller may perform control operations on this runtime.
    - `revision` integer, required: Monotonic runtime aggregate revision.
    - `secret_configuration` RuntimeSecretConfiguration[], required: Canonical inline secret injection configuration.
      - `secret_id` string, required
      - `environment` SecretEnvironmentInjection[]
        - `name` string, required
        - `value_template` string, required
      - `egress_rules` SecretEgressInjection[]
        - `host_pattern` string, required
        - `path_pattern` string, nullable
        - `action` 'header' | 'query', required: Where an egress secret is injected.
        - `name` string, required
        - `value_template` string, required
      - `files` SecretFileInjection[]
        - `path` string, required: Delivery path, relative to the guest home directory.
        - `value_template` string, required

## Other responses

- `401`: Missing, malformed, or rejected bearer token
- `403`: The bearer token is not allowed to perform this action
- `404`: The requested resource was not found
- `409`: The request conflicts with current resource state
- `422`: Validation or application error
- `429`: Rate limit exceeded
- `501`: Operation is not implemented
- `503`: Upstream service is unavailable
- `504`: Upstream request timed out
- `default`: Error response

## Changes

- **2026-11-05** `fb5a0ecd3fc2`: 20 warning, 11 info
  - added the new `FEATURE_TEMPORARILY_DISABLED` enum value to the `error/code` response property for the response status `401`
  - added the new `FEATURE_TEMPORARILY_DISABLED` enum value to the `error/code` response property for the response status `403`
  - added the new `FEATURE_TEMPORARILY_DISABLED` enum value to the `error/code` response property for the response status `404`
  - added the new `FEATURE_TEMPORARILY_DISABLED` enum value to the `error/code` response property for the response status `409`
  - …27 more

[Operation history](https://skmtc.dev/runta/apis/runta-public-rest-api/changes/v2/runtimes/post.md)

---

[API](https://skmtc.dev/runta/apis/runta-public-rest-api.md) - [All operations](https://skmtc.dev/runta/apis/runta-public-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/runta/apis/runta-public-rest-api/revisions/fb5a0ecd3fc2?raw)