---
title: "Create a Computer."
method: POST
path: "/v1/devboxes/computers"
tags: ["Computer"]
---

# Create a Computer.

`POST /v1/devboxes/computers`

Create a Computer and begin the boot process. The Computer will initially launch in the 'provisioning' state while Runloop allocates the necessary infrastructure. It will transition to the 'initializing' state while the booted Computer runs any Runloop or user defined set up scripts. Finally, the Computer will transition to the 'running' state when it is ready for use.

## Request body

- ComputerCreateParameters
  - `name` string, nullable — The name to use for the created computer.
  - `display_dimensions` ComputerDisplayDimensions
    - `display_width_px` integer, required — The width of the display being controlled by the model in pixels.
    - `display_height_px` integer, required — The height of the display being controlled by the model in pixels.

## Response `200`

OK

- ComputerView — A Computer represents an implementation of Anthropic Computer usage on top of Devboxes. It includes the tunnel to the live screen and the underlying DevboxView.
  - `devbox` DevboxView, required — A Devbox represents a virtual development environment. It is an isolated sandbox that can be given to agents and used to run arbitrary code such as AI generated code.
    - `id` string, required — The ID of the Devbox.
    - `name` string, nullable — The name of the Devbox.
    - `status` 'provisioning' | 'initializing' | 'running' | 'suspending' | 'suspended' | 'resuming' | 'failure' | 'shutdown', required — The status of the Devbox. provisioning: Runloop is allocating and booting the necessary infrastructure resources. initializing: Runloop defined boot scripts are running to enable the environment for interaction. running: The Devbox is ready for interaction. suspending: The Devbox disk is being snapshotted as part of suspension. suspended: The Devbox disk is saved and no more active compute is being used for the Devbox. resuming: The Devbox disk is being loaded as part of booting a suspended Devbox. failure: The Devbox failed as part of booting or running user requested actions. shutdown: The Devbox was successfully shutdown and no more active compute is being used.
    - `create_time_ms` integer, required — Creation time of the Devbox (Unix timestamp milliseconds).
    - `end_time_ms` integer, nullable, required — The time the Devbox finished execution (Unix timestamp milliseconds). Present if the Devbox is in a terminal state.
    - `initiator_type` 'unknown' | 'api' | 'scenario' | 'scoring_validation'
    - `initiator_id` string, nullable — The ID of the initiator that created the Devbox.
    - `blueprint_id` string, nullable — The Blueprint ID used in creation of the Devbox, if the devbox was created from a Blueprint.
    - `snapshot_id` string, nullable — The Snapshot ID used in creation of the Devbox, if the devbox was created from a Snapshot.
    - `metadata` object, required — The user defined Devbox metadata.
    - `failure_reason` 'out_of_memory' | 'out_of_disk' | 'execution_failed' — The category of failure experienced by the Devbox. out_of_memory: The Devbox ran out of memory at runtime. Use launch parameters to request a larger resource size. out_of_disk: The Devbox ran out of disk at runtime. Please reach out to support for us to better support your use case. execution_failed: The Devbox failed at runtime. Please use the dashboard to look at the logs of the failure.
    - `shutdown_reason` 'api_shutdown' | 'keep_alive_timeout' | 'entrypoint_exit' | 'idle' — The reason that caused the transition of the Devbox to the shutown state. api_shutdown: The Devbox shutdown due to API request. entrypoint_exit: The Devbox entrypoint program completed. idle: The Devbox shutdown due to configured action on idle configuration.
    - `launch_parameters` LaunchParameters, required — LaunchParameters enable you to customize the resources available to your Devbox as well as the environment set up that should be completed before the Devbox is marked as 'running'.
      - `launch_commands` string[], nullable — Set of commands to be run at launch time, before the entrypoint process is run.
      - `resource_size_request` 'X_SMALL' | 'SMALL' | 'MEDIUM' | 'LARGE' | 'X_LARGE' | 'XX_LARGE' | 'CUSTOM_SIZE' — The size of the Devbox resources for Runloop to allocate. X_SMALL: 0.5 cpu x 1GiB memory x 4GiB disk SMALL: 1 cpu x 2GiB memory x 4GiB disk MEDIUM: 2 cpu x 4GiB memory x 8GiB disk LARGE: 2 cpu x 8GiB memory x 16GiB disk X_LARGE: 4 cpu x 16GiB memory x 16GiB disk XX_LARGE: 8 cpu x 32GiB memory x 16GiB disk CUSTOM_SIZE: To choose a custom size, set this enum and also the custom_cpu_cores, custom_gb_memory, and optionally custom_disk_size in launch parameters. CPU must be 0.5, 1, or a multiple of 2 (max 16). Memory must be 1 or a multiple of 2 (max 64GiB). Disk must be a multiple of 2 (min 2GiB, max 64GiB). The cpu:memory ratio must be between 1:2 and 1:8 inclusive.
      - `keep_alive_time_seconds` integer, nullable — Time in seconds after which Devbox will automatically shutdown. Default is 1 hour. Maximum is 48 hours (172800 seconds).
      - `available_ports` integer[], nullable — A list of ports to make available on the Devbox. Only ports made available will be surfaced to create tunnels via the 'createTunnel' API.
      - `after_idle` IdleConfigurationParameters
        - `idle_time_seconds` integer, required — After idle_time_seconds, on_idle action will be taken.
        - `on_idle` 'shutdown' | 'suspend', required — Action to take after Devbox idle timer is triggered. shutdown: Shutdown the Devbox. suspend: Suspend the Devbox.
      - `custom_cpu_cores` integer, nullable — Custom CPU cores. Must be 0.5, 1, or a multiple of 2. Max is 16.
      - `custom_gb_memory` integer, nullable — Custom memory size in GiB. Must be 1 or a multiple of 2. Max is 64GiB.
      - `custom_disk_size` integer, nullable — Custom disk size in GiB. Must be a multiple of 2. Min is 2GiB, max is 64GiB.
      - `architecture` 'x86_64' | 'arm64'
      - `user_parameters` UserParameters — Configuration for the Linux user in the Devbox environment.
        - `username` string, required — Username for the Linux user.
        - `uid` integer, required — User ID (UID) for the Linux user. Must be a non-negative integer.
      - `required_services` string[], nullable — A list of ContainerizedService names to be started when a Devbox is created. A valid ContainerizedService must be specified in Blueprint to be started.
      - `network_policy_id` string, nullable — (Optional) ID of the network policy to apply to Devboxes launched with these parameters. When set on a Blueprint launch parameters, Devboxes created from it will inherit this policy unless explicitly overridden.
    - `capabilities` DevboxCapabilities[], required — A list of capability groups this devbox has access to. This allows devboxes to be compatible with certain tools sets like computer usage APIs.
    - `state_transitions` DevboxStateTransition[], required — A list of state transitions in order with durations
      - `status` 'provisioning' | 'initializing' | 'running' | 'suspending' | 'suspended' | 'resuming' | 'failure' | 'shutdown' — The status of the Devbox. provisioning: Runloop is allocating and booting the necessary infrastructure resources. initializing: Runloop defined boot scripts are running to enable the environment for interaction. running: The Devbox is ready for interaction. suspending: The Devbox disk is being snapshotted as part of suspension. suspended: The Devbox disk is saved and no more active compute is being used for the Devbox. resuming: The Devbox disk is being loaded as part of booting a suspended Devbox. failure: The Devbox failed as part of booting or running user requested actions. shutdown: The Devbox was successfully shutdown and no more active compute is being used.
      - `transition_time_ms` Number
    - `tunnel` TunnelView — A V2 tunnel provides secure HTTP access to services running on a Devbox. Tunnels allow external clients to reach web servers, APIs, or other HTTP services running inside a Devbox without requiring direct network access. Each tunnel is uniquely identified by an encrypted tunnel_key and can be configured for either open (public) or authenticated access. Usage: https://{port}-{tunnel_key}.tunnel.runloop.ai
      - `tunnel_key` string, required — The encrypted tunnel key used to construct the tunnel URL. URL format: https://{port}-{tunnel_key}.tunnel.runloop.{domain}
      - `auth_mode` 'open' | 'authenticated', required
      - `auth_token` string, nullable — Bearer token for tunnel authentication. Only present when auth_mode is 'authenticated'.
      - `create_time_ms` integer, required — Creation time of the tunnel (Unix timestamp milliseconds).
    - `gateway_specs` object, nullable — [Beta] Gateway specifications configured for this devbox. Map key is the environment variable prefix (e.g., 'GWS_ANTHROPIC').
  - `live_screen_url` string, required — The http tunnel to connect and view the live screen of the computer. You can control the interactivity of the browser by adding or removing 'view_only' query parameter. view_only=1 will allow interaction and view_only=0 will disable interaction.

## Changes

- **2026-01-30** `b493cadf2e3b` — 1 warning, 1 info
  - added the new `open` enum value to the `devbox/tunnel/auth_mode` response property for the response status `200`
  - removed the `public_` enum value from the `devbox/tunnel/auth_mode` response property for the response status `200`
- **2026-01-30** `debd1f9a9d59` — 2 info
  - added the optional property `devbox/gateway_specs` to the response with the `200` status
  - added the optional property `devbox/tunnel` to the response with the `200` status
- **2026-01-20** `5bbc26893c51` — 1 warning
  - removed the optional property `devbox/network_policy_id` from the response with the `200` status
- **2026-01-19** `eac4defbf398` — 1 info
  - added the optional property `devbox/network_policy_id` to the response with the `200` status
- **2026-01-19** `8ebd9dbfacb1` — 1 warning, 1 info
  - added the new `scoring_validation` enum value to the `devbox/initiator_type` response property for the response status `200`
  - added the optional property `devbox/launch_parameters/network_policy_id` to the response with the `200` status

[Full history](https://skmtc.dev/runloopai/apis/runloop-api/changes/v1/devboxes/computers/post.md)

---

[API](https://skmtc.dev/runloopai/apis/runloop-api.md) · [All operations](https://skmtc.dev/runloopai/apis/runloop-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/runloopai/runloop-api/revisions/c8d61a0c8b88/schema)