Sign in
Devbox
Devbox-Lifecycle

Create a Devbox.

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.

post/v1/devboxes

Request body

namestring nullable

(Optional) A user specified name to give the Devbox.

environment_variablesobject nullable

(Optional) Environment variables used to configure your Devbox.

secretsobject 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_mountsobject nullable

Map of paths and file contents to write before setup. Use mounts instead.

entrypointstring 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_idstring 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_namestring 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.

snapshot_idstring nullable

Snapshot ID to use for the Devbox. Only one of (Snapshot ID, Blueprint ID, Blueprint name) should be specified.

metadataobject nullable

User defined metadata to attach to the devbox for organization.

gatewaysobject 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'}}

mcpobject 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

OK

idstring required

The ID of the Devbox.

namestring 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_msinteger required

Creation time of the Devbox (Unix timestamp milliseconds).

end_time_msinteger 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_idstring nullable

The ID of the initiator that created the Devbox.

blueprint_idstring nullable

The Blueprint ID used in creation of the Devbox, if the devbox was created from a Blueprint.

snapshot_idstring nullable

The Snapshot ID used in creation of the Devbox, if the devbox was created from a Snapshot.

metadataobject 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.

capabilitiesDevboxCapabilities[] required

A list of capability groups this devbox has access to.

gateway_specsobject nullable

Gateway specifications configured for this devbox. Map key is the environment variable prefix (e.g., 'GWS_ANTHROPIC').

mcp_specsobject 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.

Changes

Changed in 29 of the 50 revisions of this API.593277

  • e9dc776053e42See the full diff
    • ○

      added the new pi_json enum value to the request property mounts/items/oneOf[BrokerMount]/protocol/anyOf[BrokerMountProtocol]/

      request-property-enum-value-added

    • ○

      added the optional property state_transitions/items/failure_reason to the response with the 200 status

      response-optional-property-added

  • fe489479c0aa21See the full diff
    • ●

      added the new queued enum value to the state_transitions/items/status response property for the response status 200

      response-property-enum-value-added

    • ●

      added the new queued enum value to the status response property for the response status 200

      response-property-enum-value-added

    • ○

      added the new codex_json enum value to the request property mounts/items/oneOf[BrokerMount]/protocol/anyOf[BrokerMountProtocol]/

      request-property-enum-value-added

  • 7715c368e0701See the full diff
    • ●

      removed the request property repo_connection_id

      request-property-removed

    This revision also has 2 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • b4ffb9a8aff32See the full diff
    • ○

      added the new optional request property launch_parameters/anyOf[LaunchParameters]/provisioning_tier

      new-optional-request-property

    • ○

      added the optional property launch_parameters/provisioning_tier to the response with the 200 status

      response-optional-property-added

  • 078a027e147f2See the full diff
    • ●

      added the new scheduled enum value to the state_transitions/items/status response property for the response status 200

      response-property-enum-value-added

    • ●

      added the new scheduled enum value to the status response property for the response status 200

      response-property-enum-value-added

  • d3ddb452754c522029See the full diff
    • ▲

      the request property blueprint_id became not nullable

      request-property-became-not-nullable

    • ▲

      the request property blueprint_name became not nullable

      request-property-became-not-nullable

    • ▲

      the request property code_mounts became not nullable

      request-property-became-not-nullable

    • ▲

      the request property code_mounts/items/git_ref became not nullable

      request-property-became-not-nullable

    • ▲

      the request property code_mounts/items/install_command became not nullable

      request-property-became-not-nullable

    • ▲

      the request property code_mounts/items/token became not nullable

      request-property-became-not-nullable

    • ▲

      the request property entrypoint became not nullable

      request-property-became-not-nullable

    • ▲

      the request property environment_variables became not nullable

      request-property-became-not-nullable

    • ▲

      the request property file_mounts became not nullable

      request-property-became-not-nullable

    • ▲

      the request property gateways became not nullable

      request-property-became-not-nullable

    • ▲

      the request property launch_parameters became not nullable

      request-property-became-not-nullable

    • ▲

      the request property mcp became not nullable

      request-property-became-not-nullable

    • ▲

      the request property metadata became not nullable

      request-property-became-not-nullable

    • ▲

      the request property mounts became not nullable

      request-property-became-not-nullable

    • ▲

      the request property mounts/items/oneOf[AgentMount]/agent_id became not nullable

      request-property-became-not-nullable

    • ▲

      the request property mounts/items/oneOf[AgentMount]/agent_name became not nullable

      request-property-became-not-nullable

    • ▲

      the request property mounts/items/oneOf[AgentMount]/agent_path became not nullable

      request-property-became-not-nullable

    • ▲

      the request property mounts/items/oneOf[AgentMount]/auth_token became not nullable

      request-property-became-not-nullable

    • ▲

      the request property mounts/items/oneOf[BrokerMount]/agent_binary became not nullable

      request-property-became-not-nullable

    • ▲

      the request property mounts/items/oneOf[BrokerMount]/launch_args became not nullable

      request-property-became-not-nullable

    • ▲

      the request property mounts/items/oneOf[BrokerMount]/protocol became not nullable

      request-property-became-not-nullable

    • ▲

      the request property mounts/items/oneOf[BrokerMount]/working_directory became not nullable

      request-property-became-not-nullable

    • ▲

      the request property mounts/items/oneOf[CodeMount]/git_ref became not nullable

      request-property-became-not-nullable

    • ▲

      the request property mounts/items/oneOf[CodeMount]/install_command became not nullable

      request-property-became-not-nullable

    • ▲

      the request property mounts/items/oneOf[CodeMount]/token became not nullable

      request-property-became-not-nullable

    • ▲

      the request property name became not nullable

      request-property-became-not-nullable

    • ▲

      the request property repo_connection_id became not nullable

      request-property-became-not-nullable

    • ▲

      the request property secrets became not nullable

      request-property-became-not-nullable

    • ▲

      the request property snapshot_id became not nullable

      request-property-became-not-nullable

    • ▲

      the request property tunnel became not nullable

      request-property-became-not-nullable

    • ▲

      removed the enum value acp of the request property mounts/items/oneOf[BrokerMount]/protocol

      request-property-enum-value-removed

    • ▲

      removed the enum value claude_json of the request property mounts/items/oneOf[BrokerMount]/protocol

      request-property-enum-value-removed

    • ▲

      the launch_parameters request property type/format changed from object/ to /

      request-property-type-changed

    • ▲

      the mounts/items/oneOf[BrokerMount]/protocol request property type/format changed from string/ to /

      request-property-type-changed

    • ▲

      the tunnel request property type/format changed from object/ to /

      request-property-type-changed

    • ▲

      the failure_reason response's property type/format changed from string/ to / for status 200

      response-property-type-changed

    • ▲

      the launch_parameters/after_idle response's property type/format changed from object/ to / for status 200

      response-property-type-changed

    • ▲

      the launch_parameters/architecture response's property type/format changed from string/ to / for status 200

      response-property-type-changed

    • ▲

      the launch_parameters/lifecycle response's property type/format changed from object/ to / for status 200

      response-property-type-changed

    • ▲

      the launch_parameters/resource_size_request response's property type/format changed from string/ to / for status 200

      response-property-type-changed

    • ▲

      the launch_parameters/user_parameters response's property type/format changed from object/ to / for status 200

      response-property-type-changed

    • ▲

      the shutdown_reason response's property type/format changed from string/ to / for status 200

      response-property-type-changed

    • ▲

      the tunnel response's property type/format changed from object/ to / for status 200

      response-property-type-changed

    • ▲

      removed the required property launch_parameters/after_idle/idle_time_seconds from the response with the 200 status

      response-required-property-removed

    • ▲

      removed the required property launch_parameters/after_idle/on_idle from the response with the 200 status

      response-required-property-removed

    • ▲

      removed the required property launch_parameters/user_parameters/uid from the response with the 200 status

      response-required-property-removed

    • ▲

      removed the required property launch_parameters/user_parameters/username from the response with the 200 status

      response-required-property-removed

    • ▲

      removed the required property tunnel/auth_mode from the response with the 200 status

      response-required-property-removed

    • ▲

      removed the required property tunnel/create_time_ms from the response with the 200 status

      response-required-property-removed

    • ▲

      removed the required property tunnel/http_keep_alive from the response with the 200 status

      response-required-property-removed

    • ▲

      removed the required property tunnel/tunnel_key from the response with the 200 status

      response-required-property-removed

    • ▲

      removed the required property tunnel/wake_on_http from the response with the 200 status

      response-required-property-removed

    • ●

      removed the request property launch_parameters/after_idle

      request-property-removed

    • ●

      removed the request property launch_parameters/architecture

      request-property-removed

    • ●

      removed the request property launch_parameters/available_ports

      request-property-removed

    • ●

      removed the request property launch_parameters/custom_cpu_cores

      request-property-removed

    • ●

      removed the request property launch_parameters/custom_disk_size

      request-property-removed

    • ●

      removed the request property launch_parameters/custom_gb_memory

      request-property-removed

    • ●

      removed the request property launch_parameters/keep_alive_time_seconds

      request-property-removed

    • ●

      removed the request property launch_parameters/launch_commands

      request-property-removed

    • ●

      removed the request property launch_parameters/lifecycle

      request-property-removed

    • ●

      removed the request property launch_parameters/network_policy_id

      request-property-removed

    • ●

      removed the request property launch_parameters/required_services

      request-property-removed

    • ●

      removed the request property launch_parameters/resource_size_request

      request-property-removed

    • ●

      removed the request property launch_parameters/user_parameters

      request-property-removed

    • ●

      removed the request property tunnel/auth_mode

      request-property-removed

    • ●

      removed the request property tunnel/http_keep_alive

      request-property-removed

    • ●

      removed the request property tunnel/wake_on_http

      request-property-removed

    • ●

      removed the optional property launch_parameters/lifecycle/after_idle from the response with the 200 status

      response-optional-property-removed

    • ●

      removed the optional property launch_parameters/lifecycle/resume_triggers from the response with the 200 status

      response-optional-property-removed

    • ●

      removed the optional property tunnel/auth_token from the response with the 200 status

      response-optional-property-removed

    • ●

      added the new reflex enum value to the initiator_type response property for the response status 200

      response-property-enum-value-added

    • ○

      added BrokerMountProtocol subschema #2 to the mounts/items/oneOf[BrokerMount]/protocol request property anyOf list

      request-property-any-of-added

    • ○

      added LaunchParameters subschema #2 to the launch_parameters request property anyOf list

      request-property-any-of-added

    • ○

      added TunnelConfig subschema #2 to the tunnel request property anyOf list

      request-property-any-of-added

    • ○

      added Architecture subschema #2 to the launch_parameters/architecture response property anyOf list for the response status 200

      response-property-any-of-added

    • ○

      added DevboxViewFailureReason subschema #2 to the failure_reason response property anyOf list for the response status 200

      response-property-any-of-added

    • ○

      added DevboxViewShutdownReason subschema #2 to the shutdown_reason response property anyOf list for the response status 200

      response-property-any-of-added

    • ○

      added IdleConfigurationParameters subschema #2 to the launch_parameters/after_idle response property anyOf list for the response status 200

      response-property-any-of-added

    • ○

      added LifecycleConfigurationParameters subschema #2 to the launch_parameters/lifecycle response property anyOf list for the response status 200

      response-property-any-of-added

    • ○

      added ResourceSize subschema #2 to the launch_parameters/resource_size_request response property anyOf list for the response status 200

      response-property-any-of-added

    • ○

      added TunnelView subschema #2 to the tunnel response property anyOf list for the response status 200

      response-property-any-of-added

    • ○

      added UserParameters subschema #2 to the launch_parameters/user_parameters response property anyOf list for the response status 200

      response-property-any-of-added

    • ○

      removed the CUSTOM_SIZE enum value from the launch_parameters/resource_size_request response property for the response status 200

      response-property-enum-value-removed

    • ○

      removed the LARGE enum value from the launch_parameters/resource_size_request response property for the response status 200

      response-property-enum-value-removed

    • ○

      removed the MEDIUM enum value from the launch_parameters/resource_size_request response property for the response status 200

      response-property-enum-value-removed

    • ○

      removed the SMALL enum value from the launch_parameters/resource_size_request response property for the response status 200

      response-property-enum-value-removed

    • ○

      removed the XX_LARGE enum value from the launch_parameters/resource_size_request response property for the response status 200

      response-property-enum-value-removed

    • ○

      removed the X_LARGE enum value from the launch_parameters/resource_size_request response property for the response status 200

      response-property-enum-value-removed

    • ○

      removed the X_SMALL enum value from the launch_parameters/resource_size_request response property for the response status 200

      response-property-enum-value-removed

    • ○

      removed the api_shutdown enum value from the shutdown_reason response property for the response status 200

      response-property-enum-value-removed

    • ○

      removed the arm64 enum value from the launch_parameters/architecture response property for the response status 200

      response-property-enum-value-removed

    • ○

      removed the entrypoint_exit enum value from the shutdown_reason response property for the response status 200

      response-property-enum-value-removed

    • ○

      removed the execution_failed enum value from the failure_reason response property for the response status 200

      response-property-enum-value-removed

    • ○

      removed the health_check_failed enum value from the failure_reason response property for the response status 200

      response-property-enum-value-removed

    • ○

      removed the idle enum value from the shutdown_reason response property for the response status 200

      response-property-enum-value-removed

    • ○

      removed the keep_alive_timeout enum value from the shutdown_reason response property for the response status 200

      response-property-enum-value-removed

    • ○

      removed the out_of_disk enum value from the failure_reason response property for the response status 200

      response-property-enum-value-removed

    • ○

      removed the out_of_memory enum value from the failure_reason response property for the response status 200

      response-property-enum-value-removed

    • ○

      removed the ttl_expired enum value from the shutdown_reason response property for the response status 200

      response-property-enum-value-removed

    • ○

      removed the x86_64 enum value from the launch_parameters/architecture response property for the response status 200

      response-property-enum-value-removed

  • 406ebae7a9b81See the full diff
    • ○

      added the new optional request property mounts/items/oneOf[BrokerMount]/working_directory

      new-optional-request-property

  • 5b536a11a7132See the full diff
    • ○

      added the new optional request property launch_parameters/lifecycle/resume_triggers/axon_event

      new-optional-request-property

    • ○

      added the optional property launch_parameters/lifecycle/resume_triggers/axon_event to the response with the 200 status

      response-optional-property-added

  • f0eb12cf4df41See the full diff
    • ●

      added the new ttl_expired enum value to the shutdown_reason response property for the response status 200

      response-property-enum-value-added

  • a1c7e69cbbf716See the full diff
    • ▲

      removed the enum value codex_app_server of the request property mounts/items/oneOf[BrokerMount]/protocol

      request-property-enum-value-removed

    • ○

      added the new optional request property code_mounts/items/git_ref

      new-optional-request-property

    • ○

      added the new optional request property launch_parameters/lifecycle

      new-optional-request-property

    • ○

      added the new optional request property mounts/items/oneOf[CodeMount]/git_ref

      new-optional-request-property

    • ○

      added the optional property launch_parameters/lifecycle to the response with the 200 status

      response-optional-property-added

    • ○

      removed the browser_usage enum value from the capabilities/items/ response property for the response status 200

      response-property-enum-value-removed

    • ○

      removed the computer_usage enum value from the capabilities/items/ response property for the response status 200

      response-property-enum-value-removed