openapi: 3.0.3 info: title: Runloop Devbox API version: '0.1' description: "Create, manage, and interact with Devboxes \u2014 isolated Linux sandbox environments for AI coding agents.\ \ Supports lifecycle (create/snapshot/suspend/resume/shutdown), shell execution, file I/O, networking (tunnels, port forwarding),\ \ PTY sessions, and observability (logs, metrics, executions)." contact: name: Runloop AI Support url: https://runloop.ai email: support@runloop.ai servers: - url: https://api.runloop.ai description: Runloop API variables: {} tags: - name: Devbox - name: Devbox-FileTools - name: Devbox-Lifecycle - name: Devbox-NetworkTools - name: Devbox-ObservabilityTools - name: Devbox-PersistenceTools - name: Devbox-ShellTools paths: /pty/{session_name}: get: tags: - Devbox - Devbox-ShellTools summary: Create or reconnect to a PTY session. description: 'Looks up the PTY session identified by the path session_name and either reconnects to the existing session or creates it if it does not yet exist. The session_name is a client-chosen session identifier, not an opaque server-issued ID. It must be non-empty (1..=256 chars) and use only ASCII letters, digits, ''-'' and ''_''. A newly created PTY session starts an interactive bash shell on the Devbox. Optional cols and rows query parameters apply an initial terminal size before any I/O; they must both be present and in the range 1..=1000 to take effect. The response returns a PtyConnectView containing connect_url (a server-relative path to the WebSocket data plane), idle_ttl_seconds (how long this session is retained after the last client disconnects), and the resulting cols/rows. The interactive byte stream itself is intentionally not modeled in OpenAPI; see the controller-level documentation for the WebSocket close-code conventions. The single-attach contract is enforced when a client opens the WebSocket data plane, not on this bootstrap call: bootstrap always succeeds for a valid session_name, even if another client is currently attached. Rejection of a second concurrent attach happens at WebSocket upgrade time. If the active client disconnects, the session is preserved for the idle TTL so a later connect using the same session_name resumes the same shell. After the TTL expires, after an explicit close control action, or after the underlying Devbox lifecycle replaces the PTY process (such as through suspend/resume), a later request with the same session_name creates a fresh PTY session without the previous shell state. Documentation note: this operation is published from mux strictly as an OpenAPI contract stub for the PTY service control plane. It is not evidence that mux itself serves the interactive PTY transport.' operationId: connectDevboxPtySession parameters: - name: session_name in: path description: The client-chosen PTY session name. Must be 1..=256 ASCII letters, digits, '-' and '_'. Reusing the same name reconnects to the same logical PTY session when it is still available. required: true deprecated: false allowEmptyValue: false schema: type: string - name: cols in: query description: Optional initial terminal width in character cells (1..=1000). Defaults to 80 when omitted. Applied only if both cols and rows are provided; otherwise ignored. required: false deprecated: false allowEmptyValue: false schema: type: integer format: int32 - name: rows in: query description: Optional initial terminal height in character cells (1..=1000). Defaults to 24 when omitted. Applied only if both cols and rows are provided; otherwise ignored. required: false deprecated: false allowEmptyValue: false schema: type: integer format: int32 responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/PtyConnectView' '400': description: Malformed session_name (alphabet or length out of range). '503': description: PTY session could not be spawned (host resource exhaustion). deprecated: false /pty/{session_name}/control: post: tags: - Devbox - Devbox-ShellTools summary: Send a control command to a PTY session. description: 'Applies a PTY control operation to an existing session. The action field selects the operation; the other fields in PtyControlParameters are interpreted only when they are relevant to the chosen action. resize: cols and rows are required and must each be in 1..=1000. A 0 or out-of-range value returns 400. The new winsize is applied to the PTY master and the kernel delivers SIGWINCH to the foreground process group. signal: signal is the POSIX signal name (for example ''SIGTERM'', ''SIGHUP'', ''SIGINT'', ''SIGUSR1''). Unknown signal names return 400. The signal is delivered to the slave''s foreground process group via killpg(2). If the shell has already exited and there is no foreground process group, returns 400. close: terminates the session. Sends SIGHUP to the foreground process group (best-effort; ignored if the shell has already exited) and drops the session from the server''s session cache. A subsequent connect with the same session_name will create a fresh PTY session. Documentation note: this operation is published from mux strictly as an OpenAPI contract stub for the PTY service control plane. It is not evidence that mux itself serves the interactive PTY transport.' operationId: controlDevboxPtySession parameters: - name: session_name in: path description: The client-chosen PTY session name. Must be 1..=256 ASCII letters, digits, '-' and '_'. required: true deprecated: false allowEmptyValue: false schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/PtyControlParameters' required: false responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/PtyControlResultView' '400': description: 'Invalid action parameters: out-of-range cols/rows on resize, unknown signal name on signal, or no foreground process group on signal.' '404': description: PTY session not found. deprecated: false /v1/devboxes: post: tags: - Devbox - 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 get: tags: - Devbox summary: List Devboxes. description: List all Devboxes while optionally filtering by status. operationId: listDevboxes parameters: - name: status in: query description: Filter by status required: false deprecated: false allowEmptyValue: true schema: $ref: '#/components/schemas/DevboxViewStatus' - name: limit in: query description: The limit of items to return. Default is 20. Max is 5000. required: false deprecated: false allowEmptyValue: true schema: type: integer format: int32 - name: starting_after in: query description: Load the next page of data starting after the item with the given ID. required: false deprecated: false allowEmptyValue: true schema: type: string - name: include_total_count in: query description: If true (default), includes total_count in the response. Set to false to skip the count query for better performance on large datasets. required: false deprecated: false allowEmptyValue: true schema: type: boolean responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/DevboxListView' deprecated: false /v1/devboxes/disk_snapshots: get: tags: - Devbox - Devbox-PersistenceTools summary: List disk snapshots of a Devbox. description: List all snapshots of a Devbox while optionally filtering by Devbox ID, source Blueprint ID, and metadata. operationId: getDevboxDiskSnapshotList parameters: - name: devbox_id in: query description: Devbox ID to filter by. required: false deprecated: false allowEmptyValue: true schema: type: string - name: source_blueprint_id in: query description: Source Blueprint ID to filter snapshots by. required: false deprecated: false allowEmptyValue: true schema: type: string - name: metadata[key] in: query description: Filter snapshots by metadata key-value pair. Can be used multiple times for different keys. required: false deprecated: false allowEmptyValue: true schema: type: string - name: metadata[key][in] in: query description: Filter snapshots by metadata key with multiple possible values (OR condition). required: false deprecated: false allowEmptyValue: true schema: type: string - name: limit in: query description: The limit of items to return. Default is 20. Max is 5000. required: false deprecated: false allowEmptyValue: true schema: type: integer format: int32 - name: starting_after in: query description: Load the next page of data starting after the item with the given ID. required: false deprecated: false allowEmptyValue: true schema: type: string - name: include_total_count in: query description: If true (default), includes total_count in the response. Set to false to skip the count query for better performance on large datasets. required: false deprecated: false allowEmptyValue: true schema: type: boolean responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/DevboxDiskSnapshotListView' '404': description: Devbox not found. deprecated: false /v1/devboxes/disk_snapshots/list_public: get: tags: - Devbox - Devbox-PersistenceTools summary: List public disk snapshots. description: List all public disk snapshots that are available to all users. operationId: listPublicSnapshots parameters: - name: devbox_id in: query description: Devbox ID to filter by. required: false deprecated: false allowEmptyValue: true schema: type: string - name: source_blueprint_id in: query description: Source Blueprint ID to filter snapshots by. required: false deprecated: false allowEmptyValue: true schema: type: string - name: metadata[key] in: query description: Filter snapshots by metadata key-value pair. Can be used multiple times for different keys. required: false deprecated: false allowEmptyValue: true schema: type: string - name: metadata[key][in] in: query description: Filter snapshots by metadata key with multiple possible values (OR condition). required: false deprecated: false allowEmptyValue: true schema: type: string - name: limit in: query description: The limit of items to return. Default is 20. Max is 5000. required: false deprecated: false allowEmptyValue: true schema: type: integer format: int32 - name: starting_after in: query description: Load the next page of data starting after the item with the given ID. required: false deprecated: false allowEmptyValue: true schema: type: string - name: include_total_count in: query description: If true (default), includes total_count in the response. Set to false to skip the count query for better performance on large datasets. required: false deprecated: false allowEmptyValue: true schema: type: boolean responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/DevboxDiskSnapshotListView' deprecated: false /v1/devboxes/disk_snapshots/metadata/keys: get: tags: - Devbox - Devbox-PersistenceTools summary: List available snapshot metadata keys. description: Returns a list of all available metadata keys that can be used for filtering snapshots. operationId: getSnapshotMetadataKeys parameters: [] responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/MetadataKeysView' deprecated: false /v1/devboxes/disk_snapshots/metadata/keys/{key}/values: get: tags: - Devbox - Devbox-PersistenceTools summary: List values for a specific snapshot metadata key. description: Returns a list of all values that exist for a specific metadata key across all snapshots. operationId: getSnapshotMetadataValues parameters: - name: key in: path description: The metadata key to get values for. required: true deprecated: false allowEmptyValue: false schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/MetadataValuesView' '400': description: Invalid metadata key provided. deprecated: false /v1/devboxes/disk_snapshots/public/metadata/keys: get: tags: - Devbox - Devbox-PersistenceTools summary: List available public snapshot metadata keys. description: Returns a list of all available metadata keys from public snapshots only that can be used for filtering. operationId: getPublicSnapshotMetadataKeys parameters: [] responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/MetadataKeysView' deprecated: false /v1/devboxes/disk_snapshots/public/metadata/keys/{key}/values: get: tags: - Devbox - Devbox-PersistenceTools summary: List values for a specific public snapshot metadata key. description: Returns a list of all values that exist for a specific metadata key across all public snapshots only. operationId: getPublicSnapshotMetadataValues parameters: - name: key in: path description: The metadata key to get values for from public snapshots. required: true deprecated: false allowEmptyValue: false schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/MetadataValuesView' '400': description: Invalid metadata key provided. deprecated: false /v1/devboxes/disk_snapshots/{id}: post: tags: - Devbox - Devbox-PersistenceTools summary: Update metadata of Disk Snapshot. description: Updates disk snapshot metadata via update vs patch. The entire metadata will be replaced. operationId: updateDiskSnapshot parameters: - name: id in: path description: The Snapshot ID. required: true deprecated: false allowEmptyValue: false schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/DevboxSnapshotRequest' required: false responses: '200': description: Snapshot created successfully. content: application/json: schema: $ref: '#/components/schemas/DevboxDiskSnapshotView' '404': description: Devbox not found. deprecated: false /v1/devboxes/disk_snapshots/{id}/delete: post: tags: - Devbox - Devbox-PersistenceTools summary: Delete a disk snapshot of a Devbox. description: Delete a previously taken disk snapshot of a Devbox. operationId: deleteSnapshot parameters: - name: id in: path description: The ID of the snapshot. required: true deprecated: false allowEmptyValue: false schema: type: string responses: '200': description: Snapshot deleted successfully. content: application/json: schema: $ref: '#/components/schemas/EmptyRecord' '404': description: Snapshot not found. '409': description: Only successfully created snapshots can be deleted. deprecated: false /v1/devboxes/disk_snapshots/{id}/status: get: tags: - Devbox - Devbox-PersistenceTools summary: Query the status of an asynchronous disk snapshot. description: Get the current status of an asynchronous disk snapshot operation, including whether it is still in progress and any error messages if it failed. operationId: queryDiskSnapshotAsync parameters: - name: id in: path description: The Snapshot ID. required: true deprecated: false allowEmptyValue: false schema: type: string responses: '200': description: Snapshot status retrieved successfully. content: application/json: schema: $ref: '#/components/schemas/DevboxSnapshotAsyncStatusView' '404': description: Snapshot not found. deprecated: false /v1/devboxes/metadata/keys: get: tags: - Devbox summary: List available devbox metadata keys. description: Returns a list of all available metadata keys that can be used for filtering devboxes. operationId: getDevboxMetadataKeys parameters: [] responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/MetadataKeysView' deprecated: false /v1/devboxes/metadata/keys/{key}/values: get: tags: - Devbox summary: List values for a specific devbox metadata key. description: Returns a list of all values that exist for a specific metadata key across all devboxes. operationId: getDevboxMetadataValues parameters: - name: key in: path description: The metadata key to get values for. required: true deprecated: false allowEmptyValue: false schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/MetadataValuesView' '400': description: Invalid metadata key provided. deprecated: false /v1/devboxes/{devbox_id}/executions/{execution_id}: get: tags: - Devbox - Devbox-ShellTools summary: Get status of an asynchronous execution on a Devbox. description: Get the latest status of a previously launched asynchronous execuction including stdout/error and the exit code if complete. operationId: queryAsyncCommand parameters: - name: devbox_id in: path description: The Devbox ID required: true deprecated: false allowEmptyValue: false schema: type: string - name: execution_id in: path description: The Execution ID required: true deprecated: false allowEmptyValue: false schema: type: string - name: last_n in: query description: 'Last n lines of standard error / standard out to return (default: 100)' required: false deprecated: false allowEmptyValue: true schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/DevboxAsyncExecutionDetailView' '404': description: Devbox not found. deprecated: false /v1/devboxes/{devbox_id}/executions/{execution_id}/kill: post: tags: - Devbox - Devbox-ShellTools summary: Kill an asynchronous execution currently running on a devbox description: Kill a previously launched asynchronous execution if it is still running by killing the launched process. Optionally kill the entire process group. operationId: killAsyncExecution parameters: - name: devbox_id in: path description: The Devbox ID. required: true deprecated: false allowEmptyValue: false schema: type: string - name: execution_id in: path description: The Async Execution ID. required: true deprecated: false allowEmptyValue: false schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/DevboxKillExecutionRequest' required: false responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/DevboxAsyncExecutionDetailView' '404': description: Devbox or Execution not found. deprecated: false /v1/devboxes/{devbox_id}/executions/{execution_id}/send_std_in: post: tags: - Devbox - Devbox-ShellTools summary: Send Content to Std In for a running execution. description: Send content to the Std In of a running execution. operationId: sendStdIn parameters: - name: devbox_id in: path description: The Devbox ID. required: true deprecated: false allowEmptyValue: false schema: type: string - name: execution_id in: path description: The Async Execution ID. required: true deprecated: false allowEmptyValue: false schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/DevboxSendStdInRequest' required: false responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/DevboxSendStdInResult' '404': description: Devbox or Execution not found. deprecated: false /v1/devboxes/{devbox_id}/executions/{execution_id}/wait_for_status: post: tags: - Devbox - Devbox-ShellTools summary: Wait for an asynchronous execution to reach a specific status. description: Polls the asynchronous execution's status until it reaches one of the desired statuses or times out. Max is 25 seconds. operationId: waitForCommandCompletion parameters: - name: devbox_id in: path description: The Devbox ID. required: true deprecated: false allowEmptyValue: false schema: type: string - name: execution_id in: path description: The Async Execution ID. required: true deprecated: false allowEmptyValue: false schema: type: string - name: last_n in: query description: 'Last n lines of standard error / standard out to return (default: 100)' required: false deprecated: false allowEmptyValue: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/DevboxWaitForCommandRequest' required: false responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/DevboxAsyncExecutionDetailView' '400': description: Invalid status provided or Devbox not in proper state. '404': description: Devbox or Execution not found. '408': description: Timeout waiting for command completion. deprecated: false /v1/devboxes/{id}: post: tags: - Devbox - 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 - 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}/create_pty_tunnel: post: tags: - Devbox - Devbox-NetworkTools summary: Create an ephemeral PTY tunnel for a running Devbox. description: Create an ephemeral authenticated tunnel for terminal access to a running Devbox. This tunnel is not persisted on the Devbox and is generated fresh on each request. The returned auth_token must be passed as a Bearer token in the Authorization header. operationId: createDevboxPtyTunnel 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/PtyTunnelView' '400': description: Devbox is not currently running. '404': description: Devbox not found. deprecated: false /v1/devboxes/{id}/create_ssh_key: post: tags: - Devbox - Devbox-NetworkTools summary: Create an SSH key for a Devbox description: Create an SSH key for a Devbox to enable remote access. operationId: createDevboxSshKey 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/DevboxCreateSshKeyView' '404': description: Devbox not found. deprecated: false /v1/devboxes/{id}/download_file: post: tags: - Devbox - Devbox-FileTools summary: Download binary file contents from Devbox filesystem. description: Download file contents of any type (binary, text, etc) from a specified path on the Devbox. operationId: devboxDownloadFile 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/DevboxDownloadFileParameters' required: false responses: '200': description: OK content: application/octet-stream: schema: format: binary headers: Content-Type: description: application/octet-stream required: true schema: type: string Content-Disposition: description: attachment required: true schema: type: string '404': description: Devbox not found. deprecated: false /v1/devboxes/{id}/enable_tunnel: post: tags: - Devbox - Devbox-NetworkTools summary: Enable a tunnel for a running Devbox. description: 'Enable a V2 tunnel for an existing running Devbox. Tunnels provide encrypted URL-based access to the Devbox without exposing internal IDs. The tunnel URL format is: https://{port}-{tunnel_key}.tunnel.runloop.ai Each Devbox can have one tunnel.' operationId: enableDevboxTunnel 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/TunnelConfig' required: false responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/TunnelView' '400': description: Devbox is not running or already has a tunnel configured. '404': description: Devbox not found. deprecated: false /v1/devboxes/{id}/execute: post: tags: - Devbox - Devbox-ShellTools summary: Execute a command with a known ID, optimistically waiting for completion description: 'Execute a command with a known command ID on a devbox, optimistically waiting for it to complete within the specified timeout. If it completes in time, return the result. If not, return a status indicating the command is still running. Note: attach_stdin parameter is not supported; use execute_async for stdin support.' operationId: executeCommand parameters: - name: id in: path description: The Devbox ID. required: true deprecated: false allowEmptyValue: false schema: type: string - name: last_n in: query description: 'Last n lines of standard error / standard out to return (default: 100)' required: false deprecated: false allowEmptyValue: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/DevboxStartExecutionParameters' required: false responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/DevboxAsyncExecutionDetailView' '404': description: Devbox not found. '408': description: Command timed out. deprecated: false /v1/devboxes/{id}/execute_async: post: tags: - Devbox - Devbox-ShellTools summary: Asynchronously execute a command via the Devbox shell description: Execute the given command in the Devbox shell asynchronously and returns the execution that can be used to track the command's progress. operationId: execAsyncCommand 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/DevboxCreateExecutionParameters' required: false responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/DevboxAsyncExecutionDetailView' '404': description: Devbox not found. deprecated: false /v1/devboxes/{id}/execute_sync: post: tags: - Devbox - Devbox-ShellTools summary: (Deprecated, please use /execute_async) Synchronously execute a shell command on a Devbox description: 'Execute a bash command in the Devbox shell, await the command completion and return the output. Note: attach_stdin parameter is not supported for synchronous execution.' operationId: execSyncCommand 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/DevboxCreateExecutionParameters' required: false responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/DevboxExecutionDetailView' deprecated: true /v1/devboxes/{id}/keep_alive: post: tags: - Devbox - 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}/logs: get: tags: - Devbox - Devbox-ObservabilityTools summary: Get Devbox logs. description: Get all logs from a running or completed Devbox. operationId: listDevboxLogs parameters: - name: id in: path description: The Devbox ID. required: true deprecated: false allowEmptyValue: false schema: type: string - name: execution_id in: query description: ID of execution to filter logs by. required: false deprecated: false allowEmptyValue: true schema: type: string - name: shell_name in: query description: Shell Name to filter logs by. required: false deprecated: false allowEmptyValue: true schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/DevboxLogsListView' '404': description: Devbox not found. deprecated: false /v1/devboxes/{id}/logs/tail: get: tags: - Devbox - Devbox-ObservabilityTools summary: Live Tail Devbox Logs. description: Tail the logs for the given devbox. This will return past log entries and continue streaming from there. The stream will then continue to stream logs until the connection is closed. operationId: tailDevboxLogs parameters: - name: id in: path description: The Devbox ID. required: true deprecated: false allowEmptyValue: false schema: type: string - name: execution_id in: query description: ID of execution to filter logs by. required: false deprecated: false allowEmptyValue: true schema: type: string - name: shell_name in: query description: Shell Name to filter logs by. required: false deprecated: false allowEmptyValue: true schema: type: string responses: '200': description: OK headers: Content-Type: description: text/event-stream schema: type: string '404': description: Devbox not found. deprecated: false /v1/devboxes/{id}/read_file_contents: post: tags: - Devbox - Devbox-FileTools summary: Read text file contents from Devbox filesystem. description: Read file contents from a file on a Devbox as a UTF-8. Note 'downloadFile' should be used for large files (greater than 100MB). Returns the file contents as a UTF-8 string. operationId: devboxReadFileContents 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/DevboxReadFileParameters' required: false responses: '200': description: OK content: text/plain: schema: type: string '404': description: Devbox not found. deprecated: false /v1/devboxes/{id}/remove_tunnel: post: tags: - Devbox - Devbox-NetworkTools summary: Remove a tunnel from the Devbox. description: Remove an existing V2 tunnel from the Devbox. operationId: removeDevboxTunnel 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' '404': description: Devbox not found. deprecated: false /v1/devboxes/{id}/resume: post: tags: - Devbox - 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 - 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}/snapshot_disk: post: tags: - Devbox - Devbox-PersistenceTools summary: Synchronously create a disk snapshot of a running Devbox. description: Create a disk snapshot of a devbox with the specified name and metadata to enable launching future Devboxes with the same disk state. operationId: createDiskSnapshot 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/DevboxSnapshotRequest' required: false responses: '200': description: Snapshot created successfully. content: application/json: schema: $ref: '#/components/schemas/DevboxDiskSnapshotView' '404': description: Devbox not found. deprecated: false /v1/devboxes/{id}/snapshot_disk_async: post: tags: - Devbox - Devbox-PersistenceTools summary: Start an asynchronous disk snapshot of a running Devbox. description: Start an asynchronous disk snapshot of a devbox with the specified name and metadata. The snapshot operation will continue in the background and can be monitored using the query endpoint. operationId: createDiskSnapshotAsync 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/DevboxSnapshotRequest' required: false responses: '200': description: Snapshot operation started successfully. content: application/json: schema: $ref: '#/components/schemas/DevboxDiskSnapshotView' '404': description: Devbox not found. deprecated: false /v1/devboxes/{id}/suspend: post: tags: - Devbox - 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}/upload_file: post: tags: - Devbox - Devbox-FileTools summary: Upload binary file contents to Devbox filesystem. description: Upload file contents of any type (binary, text, etc) to a Devbox. Note this API is suitable for large files (larger than 100MB) and efficiently uploads files via multipart form data. operationId: devboxUploadFile parameters: - name: id in: path description: The Devbox ID. required: true deprecated: false allowEmptyValue: false schema: type: string requestBody: content: multipart/form-data: schema: $ref: '#/components/schemas/FileUpload' required: false responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/EmptyRecord' '404': description: Devbox not found. deprecated: false /v1/devboxes/{id}/usage: get: tags: - Devbox - Devbox-ObservabilityTools summary: Get resource usage for a Devbox. description: Get resource usage metrics for a specific Devbox. Returns CPU, memory, and disk consumption calculated from the Devbox's lifecycle, excluding any suspended periods for CPU and memory. Disk usage includes the full elapsed time since storage is consumed even when suspended. operationId: getDevboxResourceUsage 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/DevboxResourceUsageView' '404': description: Devbox not found. deprecated: false /v1/devboxes/{id}/wait_for_status: post: tags: - Devbox - 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 /v1/devboxes/{id}/write_file_contents: post: tags: - Devbox - Devbox-FileTools summary: Write text file contents to Devbox filesystem. description: Write UTF-8 string contents to a file at path on the Devbox. Note for large files (larger than 100MB), the upload_file endpoint must be used. operationId: devboxWriteFileContents 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/DevboxWriteFileParameters' required: false responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/DevboxExecutionDetailView' '404': description: Devbox not found. deprecated: false components: schemas: 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 Architecture: type: string enum: - x86_64 - arm64 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 BrokerMountProtocol: type: string enum: - acp - claude_json CodeMount: 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. type: type: string enum: - code_mount default: code_mount required: - repo_name - repo_owner - type 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 DevboxAsyncExecutionDetailView: type: object additionalProperties: false properties: devbox_id: type: string description: Devbox id where command was executed. execution_id: type: string description: Ephemeral id of the execution in progress. status: $ref: '#/components/schemas/DevboxExecutionStatus' description: Current status of the execution. shell_name: type: string nullable: true description: Shell name. stdout: type: string nullable: true description: Standard out generated by command. This field will remain unset until the execution has completed. stderr: type: string nullable: true description: Standard error generated by command. This field will remain unset until the execution has completed. exit_status: type: integer format: int32 nullable: true description: Exit code of command execution. This field will remain unset until the execution has completed. stdout_truncated: type: boolean nullable: true description: Indicates whether the stdout was truncated due to size limits. stderr_truncated: type: boolean nullable: true description: Indicates whether the stderr was truncated due to size limits. required: - devbox_id - execution_id - status DevboxCapabilities: type: string enum: - unknown - docker_in_docker DevboxCreateExecutionParameters: type: object additionalProperties: false properties: command: type: string description: The command to execute via the Devbox shell. By default, commands are run from the user home directory unless shell_name is specified. If shell_name is specified the command is run from the directory based on the recent state of the persistent shell. shell_name: type: string nullable: true description: The name of the persistent shell to create or use if already created. When using a persistent shell, the command will run from the directory at the end of the previous command and environment variables will be preserved. attach_stdin: type: boolean nullable: true description: Whether to attach stdin streaming for async commands. Not valid for execute_sync endpoint. Defaults to false if not specified. required: - command 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' nullable: true description: A list of code mounts to be included in the Devbox. Use mounts instead. mounts: type: array items: $ref: '#/components/schemas/Mount' nullable: true description: A list of mounts to be included in the Devbox. tunnel: $ref: '#/components/schemas/TunnelConfig' nullable: true description: (Optional) Configuration for creating a V2 tunnel at Devbox launch time. When specified, a tunnel will be automatically provisioned and the tunnel details will be included in the Devbox response. gateways: type: object additionalProperties: $ref: '#/components/schemas/GatewaySpec' nullable: true description: '(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: type: object additionalProperties: $ref: '#/components/schemas/McpSpec' nullable: true description: '[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''}}' DevboxCreateSshKeyView: type: object additionalProperties: false properties: id: type: string description: The ID of the Devbox. url: type: string description: The host url of the Devbox that can be used for SSH. ssh_private_key: type: string description: The ssh private key, in PEM format. ssh_user: type: string description: The Linux user to use for SSH connections to this Devbox. required: - id - url - ssh_private_key - ssh_user DevboxDiskSnapshotListView: type: object additionalProperties: false properties: snapshots: type: array items: $ref: '#/components/schemas/DevboxDiskSnapshotView' description: List of snapshots matching filter. has_more: type: boolean total_count: type: integer format: int32 nullable: true required: - snapshots - has_more DevboxDiskSnapshotView: type: object additionalProperties: false properties: id: type: string description: The unique identifier of the snapshot. name: type: string nullable: true description: (Optional) The custom name of the snapshot. create_time_ms: type: integer format: int64 description: Creation time of the Snapshot (Unix timestamp milliseconds). metadata: type: object additionalProperties: type: string description: User defined metadata associated with the snapshot. source_devbox_id: type: string description: The source Devbox ID this snapshot was created from. source_blueprint_id: type: string nullable: true description: (Optional) The source Blueprint ID this snapshot was created from. commit_message: type: string nullable: true description: (Optional) The commit message of the snapshot (max 1000 characters). size_bytes: type: integer format: int64 nullable: true description: (Optional) The size of the snapshot in bytes, relative to the base blueprint. required: - id - create_time_ms - metadata - source_devbox_id DevboxDownloadFileParameters: type: object additionalProperties: false properties: path: type: string description: The path on the Devbox filesystem to read the file from. Path is relative to user home directory. required: - path DevboxExecutionDetailView: type: object additionalProperties: false properties: devbox_id: type: string description: Devbox id where command was executed. stdout: type: string description: Standard out generated by command. stderr: type: string description: Standard error generated by command. exit_status: type: integer format: int32 description: Exit status of command execution. shell_name: type: string nullable: true description: Shell name. required: - devbox_id - stdout - stderr - exit_status DevboxExecutionStatus: type: string enum: - queued - running - completed DevboxKillExecutionRequest: type: object additionalProperties: false properties: kill_process_group: type: boolean nullable: true description: 'Whether to kill the entire process group (default: false). If true, kills all processes in the same process group as the target process.' DevboxListView: type: object additionalProperties: false properties: devboxes: type: array items: $ref: '#/components/schemas/DevboxView' description: List of devboxes matching filter. has_more: type: boolean total_count: type: integer format: int32 nullable: true required: - devboxes - has_more DevboxLog: type: object additionalProperties: false properties: cmd_id: type: string nullable: true description: Identifier of the associated command the log is sourced from. level: type: string description: Log line severity level. timestamp_ms: type: integer format: int64 description: Time of log (Unix timestamp milliseconds). shell_name: type: string nullable: true description: The Shell name the cmd executed in. cmd: type: string nullable: true description: The Command Executed message: type: string nullable: true description: Log line message. exit_code: type: integer format: int32 nullable: true description: The Exit Code of the command source: $ref: '#/components/schemas/DevboxLogSource' description: The source of the log. required: - level - timestamp_ms - source DevboxLogSource: type: string enum: - setup_commands - entrypoint - exec - files - stats - kmsg DevboxLogsListView: type: object additionalProperties: false properties: logs: type: array items: $ref: '#/components/schemas/DevboxLog' description: List of logs for the given devbox. required: - logs DevboxReadFileParameters: type: object additionalProperties: false properties: file_path: type: string description: The path on the Devbox filesystem to read the file from. Path is relative to user home directory. required: - file_path DevboxResourceUsageView: type: object additionalProperties: false properties: id: type: string description: The devbox ID. total_active_seconds: type: integer format: int64 description: Total time in seconds the devbox was actively running (excludes time spent suspended). total_elapsed_seconds: type: integer format: int64 description: Total elapsed time in seconds from devbox creation to now (or end time if terminated). Includes all time regardless of devbox state. vcpu_seconds: type: integer format: int64 description: vCPU usage in vCPU-seconds (total_active_seconds multiplied by the number of vCPUs). memory_gb_seconds: type: integer format: int64 description: Memory usage in GB-seconds (total_active_seconds multiplied by memory in GB). disk_gb_seconds: type: integer format: int64 description: Disk usage in GB-seconds (total_elapsed_seconds multiplied by disk size in GB). Disk is billed for elapsed time since storage is consumed even when suspended. start_time_ms: type: integer format: int64 description: The devbox creation time in milliseconds since epoch. end_time_ms: type: integer format: int64 nullable: true description: The devbox end time in milliseconds since epoch, or null if still running. status: type: string description: The current status of the devbox. required: - id - total_active_seconds - total_elapsed_seconds - vcpu_seconds - memory_gb_seconds - disk_gb_seconds - start_time_ms - status DevboxSendStdInRequest: type: object additionalProperties: false properties: text: type: string nullable: true description: Text to send to std in of the running execution. signal: $ref: '#/components/schemas/SignalType' nullable: true description: Signal to send to std in of the running execution. DevboxSendStdInResult: type: object additionalProperties: false properties: devbox_id: type: string description: Devbox id where command is executing. execution_id: type: string description: Execution id that received the stdin. success: type: boolean description: Whether the stdin was successfully sent. required: - devbox_id - execution_id - success DevboxSnapshotAsyncStatusView: type: object additionalProperties: false properties: status: $ref: '#/components/schemas/DevboxSnapshotStatus' description: The current status of the snapshot operation. snapshot: $ref: '#/components/schemas/DevboxDiskSnapshotView' nullable: true description: The snapshot details if the operation completed successfully. error_message: type: string nullable: true description: Error message if the operation failed. required: - status DevboxSnapshotRequest: type: object additionalProperties: false properties: name: type: string nullable: true description: (Optional) A user specified name to give the snapshot metadata: type: object additionalProperties: type: string nullable: true description: (Optional) Metadata used to describe the snapshot commit_message: type: string nullable: true description: (Optional) Commit message associated with the snapshot (max 1000 characters) DevboxSnapshotStatus: type: string enum: - in_progress - error - complete - deleted DevboxStartExecutionParameters: type: object additionalProperties: false properties: command_id: type: string description: The command ID in UUIDv7 string format for idempotency and tracking command: type: string description: The command to execute via the Devbox shell. By default, commands are run from the user home directory unless shell_name is specified. If shell_name is specified the command is run from the directory based on the recent state of the persistent shell. shell_name: type: string nullable: true description: The name of the persistent shell to create or use if already created. When using a persistent shell, the command will run from the directory at the end of the previous command and environment variables will be preserved. optimistic_timeout: type: integer format: int32 nullable: true description: Timeout in seconds to wait for command completion, up to 25 seconds. Defaults to 25 seconds. Operation is not killed. required: - command_id - command 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 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. 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 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. DevboxViewShutdownReason: type: string enum: - api_shutdown - keep_alive_timeout - entrypoint_exit - idle - ttl_expired description: '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. ' x-enum-descriptions: 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. 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. DevboxWaitForCommandRequest: type: object additionalProperties: false properties: statuses: type: array items: $ref: '#/components/schemas/DevboxExecutionStatus' description: The command execution statuses to wait for. At least one status must be provided. The command 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 25 seconds. Defaults to 25 seconds. required: - statuses 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 DevboxWriteFileParameters: type: object additionalProperties: false properties: file_path: type: string description: The path to write the file to on the Devbox. Path is relative to user home directory. contents: type: string description: The UTF-8 string contents to write to the file. required: - file_path - contents EmptyRecord: type: object additionalProperties: false properties: {} 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 FileUpload: type: object additionalProperties: false properties: file: type: string format: binary path: type: string description: The path to write the file to on the Devbox. Path is relative to user home directory. required: - path 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 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 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. 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 InitiatorType: type: string enum: - unknown - api - scenario - scoring_validation 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. 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. 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 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 MetadataKeysView: type: object additionalProperties: false properties: keys: type: array items: type: string MetadataValuesView: type: object additionalProperties: false properties: key: type: string values: type: array items: type: string 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' Number: type: object additionalProperties: false properties: {} ObjectMount: type: object additionalProperties: false properties: object_id: type: string description: The ID of the object to write. object_path: type: string description: 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: type: string enum: - object_mount default: object_mount required: - object_id - object_path - type PtyConnectView: type: object additionalProperties: false properties: session_name: type: string status: type: string protocol_version: type: string connect_url: type: string created: type: boolean attached: type: boolean cols: type: integer format: int32 rows: type: integer format: int32 idle_ttl_seconds: type: integer format: int64 required: - created - attached PtyControlAction: type: string enum: - resize - signal - close PtyControlParameters: type: object additionalProperties: false properties: action: $ref: '#/components/schemas/PtyControlAction' cols: type: integer format: int32 rows: type: integer format: int32 signal: type: string PtyControlResultView: type: object additionalProperties: false properties: session_name: type: string status: type: string PtyTunnelView: type: object additionalProperties: false description: 'An ephemeral PTY tunnel providing authenticated terminal access to a Devbox. These tunnels are not stored on the Devbox and are generated fresh on each request. Usage: https://{port}-{tunnel_key}.tunnel.runloop.ai with Authorization: Bearer {auth_token}' properties: tunnel_key: type: string description: 'The encrypted tunnel key used to construct the tunnel URL. URL format: https://{port}-{tunnel_key}.tunnel.runloop.{domain}' auth_token: type: string description: Bearer token for tunnel authentication. Always required for PTY tunnels. required: - tunnel_key - auth_token ResourceSize: type: string enum: - X_SMALL - SMALL - MEDIUM - LARGE - X_LARGE - XX_LARGE - CUSTOM_SIZE description: '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. ' x-enum-descriptions: 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. ResumeTriggers: type: object additionalProperties: false description: Triggers that can resume a suspended Devbox. properties: http: type: boolean nullable: true description: When true, HTTP traffic to a suspended Devbox via tunnel will trigger a resume. axon_event: type: boolean nullable: true description: When true, axon events targeting a suspended Devbox will trigger a resume. SignalType: type: string enum: - EOF - INTERRUPT TunnelAuthMode: type: string enum: - open - authenticated 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. TunnelView: type: object additionalProperties: false description: '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' properties: tunnel_key: type: string description: 'The encrypted tunnel key used to construct the tunnel URL. URL format: https://{port}-{tunnel_key}.tunnel.runloop.{domain}' auth_mode: $ref: '#/components/schemas/TunnelAuthModeView' description: The authentication mode for the tunnel. auth_token: type: string nullable: true description: Bearer token for tunnel authentication. Only present when auth_mode is 'authenticated'. create_time_ms: type: integer format: int64 description: Creation time of the tunnel (Unix timestamp milliseconds). http_keep_alive: type: boolean description: When true, HTTP traffic through the tunnel counts as activity for idle lifecycle policies, resetting the idle timer. wake_on_http: type: boolean description: When true, HTTP traffic to a suspended devbox will automatically trigger a resume. required: - tunnel_key - auth_mode - create_time_ms - http_keep_alive - wake_on_http 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 securitySchemes: bearerAuth: scheme: bearer type: http security: - bearerAuth: []