---
title: "Create a Devbox."
method: POST
path: "/v1/devboxes"
tags: ["Devbox", "Devbox-Lifecycle"]
---

# Create a Devbox.

`POST /v1/devboxes`

Create a Devbox and begin the boot process. Standard Devboxes initially report the 'provisioning' state. FLEX Devboxes initially report the 'queued' state while waiting for infrastructure allocation, then transition to 'provisioning' once assigned to a node. The Devbox transitions to 'initializing' while the booted Devbox runs Runloop or user-defined setup scripts, then to 'running' when it is ready for use.

## Request body

- DevboxCreateParameters
  - `name` string, nullable — (Optional) A user specified name to give the Devbox.
  - `environment_variables` object, nullable — (Optional) Environment variables used to configure your Devbox.
  - `secrets` object, nullable — (Optional) Map of environment variable names to secret names. The secret values will be securely injected as environment variables in the Devbox. Example: {"DB_PASS": "DATABASE_PASSWORD"} sets environment variable 'DB_PASS' to the value of secret 'DATABASE_PASSWORD'.
  - `file_mounts` object, nullable — Map of paths and file contents to write before setup. Use mounts instead.
  - `entrypoint` string, nullable — (Optional) When specified, the Devbox will run this script as its main executable. The devbox lifecycle will be bound to entrypoint, shutting down when the process is complete.
  - `blueprint_id` string, nullable — Blueprint ID to use for the Devbox. If none set, the Devbox will be created with the default Runloop Devbox image. Only one of (Snapshot ID, Blueprint ID, Blueprint name) should be specified.
  - `blueprint_name` string, nullable — Name of Blueprint to use for the Devbox. When set, this will load the latest successfully built Blueprint with the given name. Only one of (Snapshot ID, Blueprint ID, Blueprint name) should be specified.
  - `launch_parameters` LaunchParameters — 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.
    - `available_ports` integer[], nullable — [Deprecated] A list of ports to make available on the Devbox. This field is ignored.
    - `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).
    - `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.
    - `lifecycle` LifecycleConfigurationParameters — Lifecycle configuration for Devbox idle and resume behavior. Configure idle policy via after_idle, resume triggers via resume_triggers, and optional lifecycle hooks via lifecycle_hooks.
      - `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.
      - `resume_triggers` ResumeTriggers — Triggers that can resume a suspended Devbox.
        - `http` boolean, nullable — When true, HTTP traffic to a suspended Devbox via tunnel will trigger a resume.
        - `axon_event` boolean, nullable — When true, axon events targeting a suspended Devbox will trigger a resume.
      - `lifecycle_hooks` LifecycleHooks — Lifecycle hooks for Devbox suspend. suspend_commands run sequentially as the configured Devbox user before the Devbox suspends; failures are logged but do not block suspending. The suspend_deadline_ms budget defaults to 30000 ms, may not exceed 60000 ms, and covers broker drain plus suspend_commands. If the deadline is exceeded, suspend work is abandoned, the timeout is logged, and the Devbox still proceeds to suspend. launch_commands still run on every startup, including after resume.
        - `suspend_commands` string[], nullable — Commands to run through the suspend path before the Devbox suspends (e.g. cleanup, quiesce daemons).
        - `suspend_deadline_ms` integer, nullable — Deadline in milliseconds for broker drain and suspend_commands during suspend. Defaults to 30000 ms and may not exceed 60000 ms. If exceeded, suspend work is abandoned, the timeout is logged, and the Devbox still proceeds to suspend by shutting down vmagent and killing the VM.
    - `provisioning_tier` 'standard' | 'flex'
  - `snapshot_id` string, nullable — Snapshot ID to use for the Devbox. Only one of (Snapshot ID, Blueprint ID, Blueprint name) should be specified.
  - `metadata` object, nullable — User defined metadata to attach to the devbox for organization.
  - `code_mounts` CodeMountParameters[], nullable — A list of code mounts to be included in the Devbox. Use mounts instead.
    - `repo_name` string, required — The name of the repo to mount. By default, code will be mounted at /home/user/{repo_name}.
    - `repo_owner` string, required — The owner of the repo.
    - `install_command` string, nullable — Installation command to install and setup repository.
    - `git_ref` string, nullable — Optional git ref (branch or tag) to checkout. Defaults to the repository default branch.
    - `token` string, nullable — The authentication token necessary to pull repo.
  - `mounts` Mount[], nullable — A list of mounts to be included in the Devbox.
    - union
      - ObjectMount
        - `object_id` string, required — The ID of the object to write.
        - `object_path` string, required — The path to write the object on the Devbox. Use absolute path of object (ie /home/user/object.txt, or directory if archive /home/user/archive_dir)
        - `type` 'object_mount', required
      - AgentMount
        - `agent_id` string, nullable, required — The ID of the agent to mount. Either agent_id or name must be set.
        - `agent_name` string, nullable, required — The name of the agent to mount. Returns the most recent agent with a matching name if no agent id string provided. Either agent id or name must be set
        - `agent_path` string, nullable — Path to mount the agent on the Devbox. Required for git and object agents. Use absolute path (e.g., /home/user/agent)
        - `auth_token` string, nullable — Optional auth token for private repositories. Only used for git agents.
        - `type` 'agent_mount', required
      - CodeMount
        - `repo_name` string, required — The name of the repo to mount. By default, code will be mounted at /home/user/{repo_name}.
        - `repo_owner` string, required — The owner of the repo.
        - `install_command` string, nullable — Installation command to install and setup repository.
        - `git_ref` string, nullable — Optional git ref (branch or tag) to checkout. Defaults to the repository default branch.
        - `token` string, nullable — The authentication token necessary to pull repo.
        - `type` 'code_mount', required
      - FileMount
        - `target` string, required — Target path where the file should be mounted.
        - `content` string, required — Content of the file to mount.
        - `type` 'file_mount', required
      - BrokerMount
        - `axon_id` string, required — The ID of the axon event stream to mount onto the Devbox.
        - `protocol` 'acp' | 'claude_json' | 'codex_json'
        - `agent_binary` string, nullable — Binary to launch the agent (e.g., 'opencode'). Used by protocols that launch a subprocess (acp, claude_json, codex_json).
        - `working_directory` string, nullable — Working directory in which to launch the agent binary. Defaults to the home directory if not specified.
        - `launch_args` string[], nullable — Arguments to pass to the agent command (e.g., ['acp']). Used by protocols that launch a subprocess (acp, claude_json, codex_json).
        - `type` 'broker_mount', required
  - `tunnel` TunnelConfig — Configuration for creating a V2 tunnel. When specified at Devbox creation, a tunnel will be automatically provisioned.
    - `auth_mode` 'open' | 'authenticated'
    - `http_keep_alive` boolean, nullable — When true, HTTP traffic through the tunnel counts as activity for idle lifecycle policies, resetting the idle timer. Defaults to true if not specified.
    - `wake_on_http` boolean, nullable — When true, HTTP traffic to a suspended devbox will automatically trigger a resume. Defaults to false if not specified. Prefer lifecycle.resume_triggers.http on launch_parameters for new integrations. If both are set, lifecycle.resume_triggers.http takes precedence.
  - `gateways` object, nullable — (Optional) Agent gateway specifications for credential proxying. Map key is the environment variable prefix (e.g., 'GWS_ANTHROPIC'). The agent gateway will proxy requests to external APIs using the specified credential without exposing the real API key. Example: {'GWS_ANTHROPIC': {'gateway': 'anthropic', 'secret': 'my_claude_key'}}
  - `mcp` object, nullable — [Beta] (Optional) MCP specifications for MCP server access. Map key is the environment variable name for the MCP token envelope. Each spec links an MCP config to a secret. The devbox will also receive RL_MCP_URL for the MCP hub endpoint. Example: {'MCP_SECRET': {'mcp_config': 'github-readonly', 'secret': 'MY_GITHUB_TOKEN'}}

## Response `200`

OK

- DevboxView — 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` 'scheduled' | 'queued' | 'provisioning' | 'initializing' | 'running' | 'suspending' | 'suspended' | 'resuming' | 'failure' | 'shutdown', required — The status of the Devbox. scheduled: Deprecated. The Devbox is waiting for infrastructure allocation to start. Use queued. queued: The Devbox is waiting for infrastructure allocation to start. 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' | 'reflex'
  - `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' | 'health_check_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. health_check_failed: The Devbox failed its health checks. This may indicate resource utilization is close to the maximum. Consider requesting a larger resource size.
  - `shutdown_reason` 'api_shutdown' | 'keep_alive_timeout' | 'entrypoint_exit' | 'idle' | 'ttl_expired' — 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. ttl_expired: The Devbox shutdown due to TTL expiration.
  - `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.
    - `available_ports` integer[], nullable — [Deprecated] A list of ports to make available on the Devbox. This field is ignored.
    - `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).
    - `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.
    - `lifecycle` LifecycleConfigurationParameters — Lifecycle configuration for Devbox idle and resume behavior. Configure idle policy via after_idle, resume triggers via resume_triggers, and optional lifecycle hooks via lifecycle_hooks.
      - `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.
      - `resume_triggers` ResumeTriggers — Triggers that can resume a suspended Devbox.
        - `http` boolean, nullable — When true, HTTP traffic to a suspended Devbox via tunnel will trigger a resume.
        - `axon_event` boolean, nullable — When true, axon events targeting a suspended Devbox will trigger a resume.
      - `lifecycle_hooks` LifecycleHooks — Lifecycle hooks for Devbox suspend. suspend_commands run sequentially as the configured Devbox user before the Devbox suspends; failures are logged but do not block suspending. The suspend_deadline_ms budget defaults to 30000 ms, may not exceed 60000 ms, and covers broker drain plus suspend_commands. If the deadline is exceeded, suspend work is abandoned, the timeout is logged, and the Devbox still proceeds to suspend. launch_commands still run on every startup, including after resume.
        - `suspend_commands` string[], nullable — Commands to run through the suspend path before the Devbox suspends (e.g. cleanup, quiesce daemons).
        - `suspend_deadline_ms` integer, nullable — Deadline in milliseconds for broker drain and suspend_commands during suspend. Defaults to 30000 ms and may not exceed 60000 ms. If exceeded, suspend work is abandoned, the timeout is logged, and the Devbox still proceeds to suspend by shutting down vmagent and killing the VM.
    - `provisioning_tier` 'standard' | 'flex'
  - `capabilities` DevboxCapabilities[], required — A list of capability groups this devbox has access to.
  - `state_transitions` DevboxStateTransition[], required — A list of state transitions in order with durations
    - `status` 'scheduled' | 'queued' | 'provisioning' | 'initializing' | 'running' | 'suspending' | 'suspended' | 'resuming' | 'failure' | 'shutdown' — The status of the Devbox. scheduled: Deprecated. The Devbox is waiting for infrastructure allocation to start. Use queued. queued: The Devbox is waiting for infrastructure allocation to start. 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. Authenticated tunnels should pass auth_token as X-Runloop-Tunnel-Authorization: Bearer {auth_token}.
    - `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'. Pass as X-Runloop-Tunnel-Authorization: Bearer {auth_token}.
    - `create_time_ms` integer, required — Creation time of the tunnel (Unix timestamp milliseconds).
    - `http_keep_alive` boolean, required — When true, HTTP traffic through the tunnel counts as activity for idle lifecycle policies, resetting the idle timer.
    - `wake_on_http` boolean, required — When true, HTTP traffic to a suspended devbox will automatically trigger a resume.
  - `gateway_specs` object, nullable — Gateway specifications configured for this devbox. Map key is the environment variable prefix (e.g., 'GWS_ANTHROPIC').
  - `mcp_specs` object, nullable — [Beta] MCP specifications configured for this devbox. Map key is the environment variable name for the MCP token envelope. Each spec links an MCP config to a secret for MCP server access through the MCP hub.

---

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