openapi: 3.0.3
info:
title: Runloop agents Blueprint-ObservabilityTools 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: Blueprint-ObservabilityTools
paths:
/v1/blueprints/preview:
post:
tags:
- Blueprint-ObservabilityTools
summary: Preview Dockerfile definition for a Blueprint.
description: Preview building a Blueprint with the specified configuration. You can take the resulting Dockerfile and test out your build using any local docker tooling.
operationId: previewImage
parameters: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BlueprintBuildParameters'
required: false
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/BlueprintPreviewView'
deprecated: true
/v1/blueprints/{id}/logs:
get:
tags:
- Blueprint-ObservabilityTools
summary: Get Blueprint build logs.
description: Get all logs from the building of a Blueprint.
operationId: blueprintLogs
parameters:
- name: id
in: path
description: The ID of the Blueprint
required: true
deprecated: false
allowEmptyValue: false
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/BlueprintBuildLogsListView'
deprecated: false
components:
schemas:
BlueprintBuildParameters:
type: object
additionalProperties: false
properties:
name:
type: string
description: Name of the Blueprint.
dockerfile:
type: string
nullable: true
description: Dockerfile contents to be used to build the Blueprint.
system_setup_commands:
type: array
items:
type: string
nullable: true
description: A list of commands to run to set up your system.
code_mounts:
type: array
items:
$ref: '#/components/schemas/CodeMountParameters'
nullable: true
description: A list of code mounts to be included in the Blueprint.
launch_parameters:
$ref: '#/components/schemas/LaunchParameters'
nullable: true
description: Parameters to configure your Devbox at launch time.
file_mounts:
type: object
additionalProperties:
type: string
nullable: true
description: (Optional) Map of paths and file contents to write before setup.
base_blueprint_id:
type: string
nullable: true
description: (Optional) ID of previously built blueprint to use as a base blueprint for this build.
base_blueprint_name:
type: string
nullable: true
description: (Optional) Name of previously built blueprint to use as a base blueprint for this build. When set, this will load the latest successfully built Blueprint with the given name. Only one of (base_blueprint_id, base_blueprint_name) should be specified.
services:
type: array
items:
$ref: '#/components/schemas/ContainerizedServiceView'
nullable: true
description: (Optional) List of containerized services to include in the Blueprint. These services will be pre-pulled during the build phase for optimized startup performance.
metadata:
type: object
additionalProperties:
type: string
nullable: true
description: (Optional) User defined metadata for the Blueprint.
build_args:
type: object
additionalProperties:
type: string
nullable: true
description: (Optional) Arbitrary Docker build args to pass during build.
secrets:
type: object
additionalProperties:
type: string
nullable: true
description: '(Optional) Map of mount IDs/environment variable names to secret names. Secrets will be available to commands during the build. Secrets are NOT stored in the blueprint image. Example: {"DB_PASS": "DATABASE_PASSWORD"} makes the secret ''DATABASE_PASSWORD'' available as environment variable ''DB_PASS''.'
build_context:
$ref: '#/components/schemas/BuildContext'
nullable: true
description: (Optional) Build context to be attached to the Blueprint build. This context is the source of COPY and ADD directives.
network_policy_id:
type: string
nullable: true
description: (Optional) ID of the network policy to apply during blueprint build. This restricts network access during the build process. This does not affect devboxes created from this blueprint; if you want devboxes created from this blueprint to inherit the network policy, set the network_policy_id on the blueprint launch parameters.
required:
- name
BlueprintBuildLogsListView:
type: object
additionalProperties: false
properties:
blueprint_id:
type: string
description: ID of the Blueprint.
logs:
type: array
items:
$ref: '#/components/schemas/BlueprintBuildLog'
description: List of logs generated during Blueprint build.
required:
- blueprint_id
- logs
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.
Architecture:
type: string
enum:
- x86_64
- arm64
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
Credentials:
type: object
additionalProperties: false
properties:
username:
type: string
description: The username of the container service.
password:
type: string
description: The password of the container service.
required:
- username
- password
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.
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.
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
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.
BlueprintBuildLog:
type: object
additionalProperties: false
properties:
level:
type: string
description: Log line severity level.
timestamp_ms:
type: integer
format: int64
description: Time of log (Unix timestamp milliseconds).
message:
type: string
description: Log line message.
required:
- level
- timestamp_ms
- message
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.
ObjectContext:
type: object
additionalProperties: false
description: A build context backed by an Object.
properties:
object_id:
type: string
description: The ID of an object, whose contents are to be used as a build context.
type:
type: string
enum:
- object
default: object
required:
- object_id
- type
BuildContext:
oneOf:
- $ref: '#/components/schemas/ObjectContext'
discriminator:
propertyName: type
mapping:
object: '#/components/schemas/ObjectContext'
ContainerizedServiceView:
type: object
additionalProperties: false
properties:
name:
type: string
description: The name of the container service.
image:
type: string
description: The image of the container service.
credentials:
$ref: '#/components/schemas/Credentials'
nullable: true
description: The credentials of the container service.
env:
type: object
additionalProperties:
type: string
nullable: true
description: The environment variables of the container service.
port_mappings:
type: array
items:
type: string
nullable: true
description: The port mappings of the container service. Port mappings are in the format of <host_port>:<container_port>.
options:
type: string
nullable: true
description: Additional Docker container create options.
required:
- name
- image
BlueprintPreviewView:
type: object
additionalProperties: false
properties:
dockerfile:
type: string
description: The Dockerfile contents that will built.
required:
- dockerfile
securitySchemes:
bearerAuth:
scheme: bearer
type: http