Devbox
Devbox-Lifecycle

Create a Devbox.

Changed on

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

  • Base URL: https://api.runloop.ai
  • URL: https://api.runloop.ai/v1/devboxes
  • Auth: HTTP bearer

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

  • e9dc776053e4Revision changes
    • info

      added the new pi_json enum value to the request property //////////

    • info

      added the optional property // to the response with the status

  • fe489479c0aaRevision changes
    • warning

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

    • warning

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

    • info

      added the new codex_json enum value to the request property //////////