openapi: 3.0.3
info:
title: Runloop agents Devbox-Lifecycle API
version: '0.1'
description: Register, version, and mount Agents — packaged agent definitions sourced from Git, npm, pip, or storage objects that can be installed on Devboxes for fast, reproducible agent execution.
contact:
name: Runloop AI Support
url: https://runloop.ai
email: support@runloop.ai
servers:
- url: https://api.runloop.ai
description: Runloop API
variables: {}
security:
- bearerAuth: []
tags:
- name: Devbox-Lifecycle
paths:
/v1/devboxes:
post:
tags:
- Devbox-Lifecycle
summary: Create a Devbox.
description: Create a Devbox and begin the boot process. The Devbox will initially launch in the 'provisioning' state while Runloop allocates the necessary infrastructure. It will transition to the 'initializing' state while the booted Devbox runs any Runloop or user defined set up scripts. Finally, the Devbox will transition to the 'running' state when it is ready for use.
operationId: createDevbox
parameters: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DevboxCreateParameters'
required: false
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/DevboxView'
deprecated: false
/v1/devboxes/{id}:
post:
tags:
- Devbox-Lifecycle
summary: Update a Devbox.
description: Updates a devbox by doing a complete update the existing name,metadata fields. It does not patch partial values.
operationId: updateDevbox
parameters:
- name: id
in: path
description: The Devbox ID.
required: true
deprecated: false
allowEmptyValue: false
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DevboxUpdateParameters'
required: false
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/DevboxView'
deprecated: false
get:
tags:
- Devbox-Lifecycle
summary: Get Devbox details.
description: Get the latest details and status of a Devbox.
operationId: getDevbox
parameters:
- name: id
in: path
description: The Devbox ID.
required: true
deprecated: false
allowEmptyValue: false
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/DevboxView'
deprecated: false
/v1/devboxes/{id}/keep_alive:
post:
tags:
- Devbox-Lifecycle
summary: Reset the idle timer of a running Devbox.
description: Send a 'Keep Alive' signal to a running Devbox that is configured to shutdown on idle so the idle time resets.
operationId: keepAliveDevbox
parameters:
- name: id
in: path
description: The Devbox ID.
required: true
deprecated: false
allowEmptyValue: false
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EmptyRecord'
deprecated: false
/v1/devboxes/{id}/resume:
post:
tags:
- Devbox-Lifecycle
summary: Resume a suspended Devbox
description: Resume a suspended Devbox with the disk state captured as suspend time. Note that any previously running processes or daemons will need to be restarted using the Devbox shell tools.
operationId: resumeDevbox
parameters:
- name: id
in: path
description: The Devbox ID.
required: true
deprecated: false
allowEmptyValue: false
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/DevboxView'
'400':
description: Devbox is not suspended.
'404':
description: Devbox not found.
deprecated: false
/v1/devboxes/{id}/shutdown:
post:
tags:
- Devbox-Lifecycle
summary: Shutdown a running Devbox.
description: Shutdown a running Devbox. This will permanently stop the Devbox. If you want to save the state of the Devbox, you should take a snapshot before shutting down or should suspend the Devbox instead of shutting down. If the Devbox has any in-progress snapshots, the shutdown will be rejected with a 409 Conflict unless force=true is specified.
operationId: shutdownDevbox
parameters:
- name: id
in: path
description: The Devbox ID.
required: true
deprecated: false
allowEmptyValue: false
schema:
type: string
- name: force
in: query
description: If true, force shutdown even if snapshots are in progress. Defaults to false.
required: false
deprecated: false
allowEmptyValue: false
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/DevboxView'
'409':
description: Devbox has in-progress snapshots and cannot be shut down at this time. Use force=true to override.
deprecated: false
/v1/devboxes/{id}/suspend:
post:
tags:
- Devbox-Lifecycle
summary: Suspend a running Devbox
description: Suspend a running Devbox and create a disk snapshot to enable resuming the Devbox later with the same disk. Note this will not snapshot memory state such as running processes.
operationId: suspendDevbox
parameters:
- name: id
in: path
description: The Devbox ID.
required: true
deprecated: false
allowEmptyValue: false
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/DevboxView'
'400':
description: Devbox is not running.
'404':
description: Devbox not found.
deprecated: false
/v1/devboxes/{id}/wait_for_status:
post:
tags:
- Devbox-Lifecycle
summary: Wait for a Devbox to reach one of the specified statuses.
description: Polls the Devbox's status until it reaches one of the desired statuses or times out.
operationId: waitForDevboxStatus
parameters:
- name: id
in: path
description: The Devbox ID.
required: true
deprecated: false
allowEmptyValue: false
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DevboxWaitForStatusRequest'
required: false
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/DevboxView'
'400':
description: Invalid status provided.
'404':
description: Devbox not found.
'408':
description: Timeout waiting for status.
deprecated: false
components:
schemas:
GatewaySpecView:
type: object
additionalProperties: false
properties:
gateway_config_id:
type: string
description: The ID of the gateway config (e.g., gwc_123abc).
secret_id:
type: string
description: The ID of the secret containing the credential.
required:
- gateway_config_id
- secret_id
CodeMountParameters:
type: object
additionalProperties: false
properties:
repo_name:
type: string
description: The name of the repo to mount. By default, code will be mounted at /home/user/{repo_name}.
repo_owner:
type: string
description: The owner of the repo.
install_command:
type: string
nullable: true
description: Installation command to install and setup repository.
git_ref:
type: string
nullable: true
description: Optional git ref (branch or tag) to checkout. Defaults to the repository default branch.
token:
type: string
nullable: true
description: The authentication token necessary to pull repo.
required:
- repo_name
- repo_owner
BrokerMountProtocol:
type: string
enum:
- acp
- claude_json
McpSpecView:
type: object
additionalProperties: false
properties:
mcp_config_id:
type: string
description: The ID of the MCP config (e.g., mcp_123abc).
secret_id:
type: string
description: The ID of the secret containing the credential.
required:
- mcp_config_id
- secret_id
DevboxView:
type: object
additionalProperties: false
description: 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.
properties:
id:
type: string
description: The ID of the Devbox.
name:
type: string
nullable: true
description: The name of the Devbox.
status:
$ref: '#/components/schemas/DevboxViewStatus'
description: The current status of the Devbox.
create_time_ms:
type: integer
format: int64
description: Creation time of the Devbox (Unix timestamp milliseconds).
end_time_ms:
type: integer
format: int64
nullable: true
description: The time the Devbox finished execution (Unix timestamp milliseconds). Present if the Devbox is in a terminal state.
initiator_type:
$ref: '#/components/schemas/InitiatorType'
description: The type of initiator that created the Devbox.
initiator_id:
type: string
nullable: true
description: The ID of the initiator that created the Devbox.
blueprint_id:
type: string
nullable: true
description: The Blueprint ID used in creation of the Devbox, if the devbox was created from a Blueprint.
snapshot_id:
type: string
nullable: true
description: The Snapshot ID used in creation of the Devbox, if the devbox was created from a Snapshot.
metadata:
type: object
additionalProperties:
type: string
description: The user defined Devbox metadata.
failure_reason:
$ref: '#/components/schemas/DevboxViewFailureReason'
nullable: true
description: The failure reason if the Devbox failed, if the Devbox has a 'failure' status.
shutdown_reason:
$ref: '#/components/schemas/DevboxViewShutdownReason'
nullable: true
description: The shutdown reason if the Devbox shutdown, if the Devbox has a 'shutdown' status.
launch_parameters:
$ref: '#/components/schemas/LaunchParameters'
description: The launch parameters used to create the Devbox.
capabilities:
type: array
items:
$ref: '#/components/schemas/DevboxCapabilities'
description: A list of capability groups this devbox has access to.
state_transitions:
type: array
items:
$ref: '#/components/schemas/DevboxStateTransition'
description: A list of state transitions in order with durations
tunnel:
$ref: '#/components/schemas/TunnelView'
nullable: true
description: V2 tunnel information if a tunnel was created at launch time or via the createTunnel API.
gateway_specs:
type: object
additionalProperties:
$ref: '#/components/schemas/GatewaySpecView'
nullable: true
description: Gateway specifications configured for this devbox. Map key is the environment variable prefix (e.g., 'GWS_ANTHROPIC').
mcp_specs:
type: object
additionalProperties:
$ref: '#/components/schemas/McpSpecView'
nullable: true
description: '[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.'
required:
- id
- status
- create_time_ms
- end_time_ms
- metadata
- launch_parameters
- capabilities
- state_transitions
IdleConfigurationParameters:
type: object
additionalProperties: false
properties:
idle_time_seconds:
type: integer
format: int32
description: After idle_time_seconds, on_idle action will be taken.
on_idle:
$ref: '#/components/schemas/IdleAction'
description: Action to take after Devbox becomes idle.
required:
- idle_time_seconds
- on_idle
LaunchParameters:
type: object
additionalProperties: false
description: 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'.
properties:
launch_commands:
type: array
items:
type: string
nullable: true
description: Set of commands to be run at launch time, before the entrypoint process is run.
resource_size_request:
$ref: '#/components/schemas/ResourceSize'
nullable: true
description: 'Preset Devbox resources (vCPU, RAM in GiB, ephemeral disk in GiB). If not set, SMALL is used. X_SMALL: 0.5 vCPU, 1 GiB RAM, 4 GiB disk. SMALL: 1 vCPU, 2 GiB RAM, 4 GiB disk. MEDIUM: 2 vCPU, 4 GiB RAM, 8 GiB disk. LARGE: 2 vCPU, 8 GiB RAM, 16 GiB disk. X_LARGE: 4 vCPU, 16 GiB RAM, 16 GiB disk. XX_LARGE: 8 vCPU, 32 GiB RAM, 16 GiB disk. CUSTOM_SIZE: set custom_cpu_cores, custom_gb_memory, and optionally custom_disk_size.'
available_ports:
type: array
items:
type: integer
format: int32
nullable: true
description: '[Deprecated] A list of ports to make available on the Devbox. This field is ignored.'
keep_alive_time_seconds:
type: integer
format: int64
nullable: true
description: Time in seconds after which Devbox will automatically shutdown. Default is 1 hour. Maximum is 48 hours (172800 seconds).
after_idle:
$ref: '#/components/schemas/IdleConfigurationParameters'
nullable: true
description: Configure Devbox lifecycle based on idle activity. If after_idle is set, Devbox will ignore keep_alive_time_seconds. If both after_idle and lifecycle.after_idle are set, they must have the same value. Use lifecycle.after_idle instead.
custom_cpu_cores:
type: integer
format: int32
nullable: true
description: Custom CPU cores. Must be 0.5, 1, or a multiple of 2. Max is 16.
custom_gb_memory:
type: integer
format: int32
nullable: true
description: Custom memory size in GiB. Must be 1 or a multiple of 2. Max is 64GiB.
custom_disk_size:
type: integer
format: int32
nullable: true
description: Custom disk size in GiB. Must be a multiple of 2. Min is 2GiB, max is 64GiB.
architecture:
$ref: '#/components/schemas/Architecture'
nullable: true
description: The target architecture for the Devbox. If unset, defaults to x86_64.
user_parameters:
$ref: '#/components/schemas/UserParameters'
nullable: true
description: Specify the user for execution on Devbox. If not set, default `user` will be used.
required_services:
type: array
items:
type: string
nullable: true
description: 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:
type: string
nullable: true
description: (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:
$ref: '#/components/schemas/LifecycleConfigurationParameters'
nullable: true
description: Lifecycle configuration for idle and resume behavior. Configure idle policy via lifecycle.after_idle (if both this and the top-level after_idle are set, they must match) and resume triggers via lifecycle.resume_triggers.
FileMount:
type: object
additionalProperties: false
properties:
target:
type: string
description: Target path where the file should be mounted.
content:
type: string
description: Content of the file to mount.
type:
type: string
enum:
- file_mount
default: file_mount
required:
- target
- content
- type
GatewaySpec:
type: object
additionalProperties: false
description: GatewaySpec links an agent gateway configuration to a secret for credential proxying in a devbox. The agent gateway will proxy requests to external APIs using the specified credential without exposing the real API key.
properties:
gateway:
type: string
description: The gateway config to use. Can be a gateway config ID (gwc_xxx) or name.
secret:
type: string
description: The secret containing the credential. Can be a secret ID or name.
required:
- gateway
- secret
DevboxStateTransition:
type: object
additionalProperties: false
properties:
status:
$ref: '#/components/schemas/DevboxViewStatus'
transition_time_ms:
$ref: '#/components/schemas/Number'
description: The time the status change occurred
DevboxViewFailureReason:
type: string
enum:
- out_of_memory
- out_of_disk
- execution_failed
- health_check_failed
description: '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.
'
x-enum-descriptions:
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.
TunnelAuthModeView:
type: string
enum:
- open
- authenticated
TunnelConfig:
type: object
additionalProperties: false
description: Configuration for creating a V2 tunnel. When specified at Devbox creation, a tunnel will be automatically provisioned.
properties:
auth_mode:
$ref: '#/components/schemas/TunnelAuthMode'
nullable: true
description: Authentication mode for the tunnel. Defaults to 'public' if not specified.
http_keep_alive:
type: boolean
nullable: true
description: 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:
type: boolean
nullable: true
description: 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.
DevboxWaitForStatusRequest:
type: object
additionalProperties: false
properties:
statuses:
type: array
items:
$ref: '#/components/schemas/DevboxViewStatus'
description: The Devbox statuses to wait for. At least one status must be provided. The devbox will be returned as soon as it reaches any of the provided statuses.
timeout_seconds:
type: integer
format: int32
nullable: true
description: (Optional) Timeout in seconds to wait for the status, up to 30 seconds. Defaults to 10 seconds.
required:
- statuses
DevboxViewStatus:
type: string
enum:
- provisioning
- initializing
- running
- suspending
- suspended
- resuming
- failure
- shutdown
description: '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.
'
x-enum-descriptions:
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.
Architecture:
type: string
enum:
- x86_64
- arm64
McpSpec:
type: object
additionalProperties: false
description: '[Beta] McpSpec links an MCP configuration to a secret for MCP server access in a devbox. The MCP hub will proxy requests to upstream MCP servers using the specified credential, with tool-level access control based on the MCP config''s allowed_tools.'
properties:
mcp_config:
type: string
description: The MCP config to use. Can be an MCP config ID (mcp_xxx) or name.
secret:
type: string
description: The secret containing the MCP server credential. Can be a secret ID or name.
required:
- mcp_config
- secret
DevboxUpdateParameters:
type: object
additionalProperties: false
properties:
name:
type: string
nullable: true
description: (Optional) A user specified name to give the Devbox.
metadata:
type: object
additionalProperties:
type: string
nullable: true
description: User defined metadata to attach to the devbox for organization.
DevboxCapabilities:
type: string
enum:
- unknown
- docker_in_docker
EmptyRecord:
type: object
additionalProperties: false
properties: {}
IdleAction:
type: string
enum:
- shutdown
- suspend
description: 'Action to take after Devbox idle timer is triggered.
shutdown: Shutdown the Devbox.
suspend: Suspend the Devbox.
'
x-enum-descriptions:
shutdown: Shutdown the Devbox.
suspend: Suspend the Devbox.
BrokerMount:
type: object
additionalProperties: false
properties:
axon_id:
type: string
description: The ID of the axon event stream to mount onto the Devbox.
protocol:
$ref: '#/components/schemas/BrokerMountProtocol'
nullable: true
description: The protocol used by the broker to deliver events to the agent.
agent_binary:
type: string
nullable: true
description: Binary to launch the agent (e.g., 'opencode'). Used by protocols that launch a subprocess (acp, claude_json).
working_directory:
type: string
nullable: true
description: Working directory in which to launch the agent binary. Defaults to the home directory if not specified.
launch_args:
type: array
items:
type: string
nullable: true
description: Arguments to pass to the agent command (e.g., ['acp']). Used by protocols that launch a subprocess (acp, claude_json).
type:
type: string
enum:
- broker_mount
default: broker_mount
required:
- axon_id
- type
TunnelAuthMode:
type: string
enum:
- open
- authenticated
AgentMount:
type: object
additionalProperties: false
properties:
agent_id:
type: string
nullable: true
description: The ID of the agent to mount. Either agent_id or name must be set.
agent_name:
type: string
nullable: true
description: 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:
type: string
nullable: true
description: Path to mount the agent on the Devbox. Required for git and object agents. Use absolute path (e.g., /home/user/agent)
auth_token:
type: string
nullable: true
description: Optional auth token for private repositories. Only used for git agents.
type:
type: string
enum:
- agent_mount
default: agent_mount
required:
- agent_id
- agent_name
- type
UserParameters:
type: object
additionalProperties: false
description: Configuration for the Linux user in the Devbox environment.
properties:
username:
type: string
description: Username for the Linux user.
uid:
type: integer
format: int32
description: User ID (UID) for the Linux user. Must be a non-negative integer.
required:
- username
- uid
Mount:
oneOf:
- $ref: '#/components/schemas/ObjectMount'
- $ref: '#/components/schemas/AgentMount'
- $ref: '#/components/schemas/CodeMount'
- $ref: '#/components/schemas/FileMount'
- $ref: '#/components/schemas/BrokerMount'
discriminator:
propertyName: type
mapping:
object_mount: '#/components/schemas/ObjectMount'
agent_mount: '#/components/schemas/AgentMount'
code_mount: '#/components/schemas/CodeMount'
file_mount: '#/components/schemas/FileMount'
broker_mount: '#/components/schemas/BrokerMount'
InitiatorType:
type: string
enum:
- unknown
- api
- scenario
- scoring_validation
LifecycleConfigurationParameters:
type: object
additionalProperties: false
description: Lifecycle configuration for Devbox idle and resume behavior. Configure idle policy via after_idle and resume triggers via resume_triggers.
properties:
after_idle:
$ref: '#/components/schemas/IdleConfigurationParameters'
nullable: true
description: Configure Devbox lifecycle based on idle activity. If both this and the top-level after_idle are set, they must have the same value. Prefer this field for new integrations.
resume_triggers:
$ref: '#/components/schemas/ResumeTriggers'
nullable: true
description: Triggers that can resume a suspended Devbox.
DevboxCreateParameters:
type: object
additionalProperties: false
properties:
name:
type: string
nullable: true
description: (Optional) A user specified name to give the Devbox.
environment_variables:
type: object
additionalProperties:
type: string
nullable: true
description: (Optional) Environment variables used to configure your Devbox.
secrets:
type: object
additionalProperties:
type: string
nullable: true
description: '(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:
type: object
additionalProperties:
type: string
nullable: true
description: Map of paths and file contents to write before setup. Use mounts instead.
entrypoint:
type: string
nullable: true
description: (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:
type: string
nullable: true
description: 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:
type: string
nullable: true
description: 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.
repo_connection_id:
type: string
nullable: true
description: Repository connection id the devbox should source its base image from.
launch_parameters:
$ref: '#/components/schemas/LaunchParameters'
nullable: true
description: Parameters to configure the resources and launch time behavior of the Devbox.
snapshot_id:
type: string
nullable: true
description: Snapshot ID to use for the Devbox. Only one of (Snapshot ID, Blueprint ID, Blueprint name) should be specified.
metadata:
type: object
additionalProperties:
type: string
nullable: true
description: User defined metadata to attach to the devbox for organization.
code_mounts:
type: array
items:
$ref: '#/components/schemas/CodeMountParameters'
# --- truncated at 32 KB (39 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/runloop-ai/refs/heads/main/openapi/runloop-ai-devbox-lifecycle-api-openapi.yml