--- title: "Create and build a Blueprint." method: POST path: "/v1/blueprints" tags: ["Blueprint", "Blueprint-Lifecycle"] --- # Create and build a Blueprint. `POST /v1/blueprints` Starts build of custom defined container Blueprint. The Blueprint will begin in the 'provisioning' step and transition to the 'building' step once it is selected off the build queue., Upon build complete it will transition to 'building_complete' if the build is successful. ## Request body - BlueprintBuildParameters - `name` string, required — Name of the Blueprint. - `dockerfile` string, nullable — Dockerfile contents to be used to build the Blueprint. - `system_setup_commands` string[], nullable — A list of commands to run to set up your system. - `code_mounts` CodeMountParameters[], nullable — A list of code mounts to be included in the Blueprint. - `repo_name` string, required — The name of the repo to mount. By default, code will be mounted at /home/user/{repo_name}. - `repo_owner` string, required — The owner of the repo. - `install_command` string, nullable — Installation command to install and setup repository. - `git_ref` string, nullable — Optional git ref (branch or tag) to checkout. Defaults to the repository default branch. - `token` string, nullable — The authentication token necessary to pull repo. - `launch_parameters` LaunchParameters — 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'. - `launch_commands` string[], nullable — Set of commands to be run at launch time, before the entrypoint process is run. - `resource_size_request` 'X_SMALL' | 'SMALL' | 'MEDIUM' | 'LARGE' | 'X_LARGE' | 'XX_LARGE' | 'CUSTOM_SIZE' — 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. - `available_ports` integer[], nullable — [Deprecated] A list of ports to make available on the Devbox. This field is ignored. - `keep_alive_time_seconds` integer, nullable — Time in seconds after which Devbox will automatically shutdown. Default is 1 hour. Maximum is 48 hours (172800 seconds). - `after_idle` IdleConfigurationParameters - `idle_time_seconds` integer, required — After idle_time_seconds, on_idle action will be taken. - `on_idle` 'shutdown' | 'suspend', required — Action to take after Devbox idle timer is triggered. shutdown: Shutdown the Devbox. suspend: Suspend the Devbox. - `custom_cpu_cores` integer, nullable — Custom CPU cores. Must be 0.5, 1, or a multiple of 2. Max is 16. - `custom_gb_memory` integer, nullable — Custom memory size in GiB. Must be 1 or a multiple of 2. Max is 64GiB. - `custom_disk_size` integer, nullable — Custom disk size in GiB. Must be a multiple of 2. Min is 2GiB, max is 64GiB. - `architecture` 'x86_64' | 'arm64' - `user_parameters` UserParameters — Configuration for the Linux user in the Devbox environment. - `username` string, required — Username for the Linux user. - `uid` integer, required — User ID (UID) for the Linux user. Must be a non-negative integer. - `required_services` string[], nullable — 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` string, nullable — (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` LifecycleConfigurationParameters — Lifecycle configuration for Devbox idle and resume behavior. Configure idle policy via after_idle, resume triggers via resume_triggers, and optional lifecycle hooks via lifecycle_hooks. - `after_idle` IdleConfigurationParameters - `idle_time_seconds` integer, required — After idle_time_seconds, on_idle action will be taken. - `on_idle` 'shutdown' | 'suspend', required — Action to take after Devbox idle timer is triggered. shutdown: Shutdown the Devbox. suspend: Suspend the Devbox. - `resume_triggers` ResumeTriggers — Triggers that can resume a suspended Devbox. - `http` boolean, nullable — When true, HTTP traffic to a suspended Devbox via tunnel will trigger a resume. - `axon_event` boolean, nullable — When true, axon events targeting a suspended Devbox will trigger a resume. - `lifecycle_hooks` LifecycleHooks — Lifecycle hooks for Devbox suspend. suspend_commands run sequentially as the configured Devbox user before the Devbox suspends; failures are logged but do not block suspending. The suspend_deadline_ms budget defaults to 30000 ms, may not exceed 60000 ms, and covers broker drain plus suspend_commands. If the deadline is exceeded, suspend work is abandoned, the timeout is logged, and the Devbox still proceeds to suspend. launch_commands still run on every startup, including after resume. - `suspend_commands` string[], nullable — Commands to run through the suspend path before the Devbox suspends (e.g. cleanup, quiesce daemons). - `suspend_deadline_ms` integer, nullable — Deadline in milliseconds for broker drain and suspend_commands during suspend. Defaults to 30000 ms and may not exceed 60000 ms. If exceeded, suspend work is abandoned, the timeout is logged, and the Devbox still proceeds to suspend by shutting down vmagent and killing the VM. - `provisioning_tier` 'standard' | 'flex' - `file_mounts` object, nullable — (Optional) Map of paths and file contents to write before setup. - `base_blueprint_id` string, nullable — (Optional) ID of previously built blueprint to use as a base blueprint for this build. - `base_blueprint_name` string, nullable — (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` ContainerizedServiceView[], nullable — (Optional) List of containerized services to include in the Blueprint. These services will be pre-pulled during the build phase for optimized startup performance. - `name` string, required — The name of the container service. - `image` string, required — The image of the container service. - `credentials` Credentials - `username` string, required — The username of the container service. - `password` string, required — The password of the container service. - `env` object, nullable — The environment variables of the container service. - `port_mappings` string[], nullable — The port mappings of the container service. Port mappings are in the format of :. - `options` string, nullable — Additional Docker container create options. - `metadata` object, nullable — (Optional) User defined metadata for the Blueprint. - `build_args` object, nullable — (Optional) Arbitrary Docker build args to pass during build. - `secrets` object, nullable — (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` BuildContext — A build context backed by an Object. - `object_id` string, required — The ID of an object, whose contents are to be used as a build context. - `type` 'object', required - `network_policy_id` string, nullable — (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. ## Response `200` OK - BlueprintView — Blueprints are ways to create customized starting points for Devboxes. They allow you to define custom starting points for Devboxes such that environment set up can be cached to improve Devbox boot times. - `id` string, required — The id of the Blueprint. - `name` string, required — The name of the Blueprint. - `status` 'queued' | 'provisioning' | 'building' | 'awaiting_upload' | 'failed' | 'build_complete', required — The status of the Blueprint build. queued: Blueprint is queued waiting for build capacity to become available. provisioning: Allocating and booting the necessary infrastructure resources to create the Blueprint image. building: Building the Blueprint image. awaiting_upload: Blueprint is created and awaiting its image to be pushed out-of-band via docker push. failed: Blueprint image failed to build. See the logs on the dashboard. build_complete: Blueprint image completed build. You can now use the ID to create Devboxes. - `state` 'created' | 'deleted', required - `create_time_ms` integer, required — Creation time of the Blueprint (Unix timestamp milliseconds). - `build_finish_time_ms` integer, nullable — Build completion time of the Blueprint (Unix timestamp milliseconds). - `parameters` BlueprintBuildParameters, required - `name` string, required — Name of the Blueprint. - `dockerfile` string, nullable — Dockerfile contents to be used to build the Blueprint. - `system_setup_commands` string[], nullable — A list of commands to run to set up your system. - `code_mounts` CodeMountParameters[], nullable — A list of code mounts to be included in the Blueprint. - `repo_name` string, required — The name of the repo to mount. By default, code will be mounted at /home/user/{repo_name}. - `repo_owner` string, required — The owner of the repo. - `install_command` string, nullable — Installation command to install and setup repository. - `git_ref` string, nullable — Optional git ref (branch or tag) to checkout. Defaults to the repository default branch. - `token` string, nullable — The authentication token necessary to pull repo. - `launch_parameters` LaunchParameters — 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'. - `launch_commands` string[], nullable — Set of commands to be run at launch time, before the entrypoint process is run. - `resource_size_request` 'X_SMALL' | 'SMALL' | 'MEDIUM' | 'LARGE' | 'X_LARGE' | 'XX_LARGE' | 'CUSTOM_SIZE' — 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. - `available_ports` integer[], nullable — [Deprecated] A list of ports to make available on the Devbox. This field is ignored. - `keep_alive_time_seconds` integer, nullable — Time in seconds after which Devbox will automatically shutdown. Default is 1 hour. Maximum is 48 hours (172800 seconds). - `after_idle` IdleConfigurationParameters - `idle_time_seconds` integer, required — After idle_time_seconds, on_idle action will be taken. - `on_idle` 'shutdown' | 'suspend', required — Action to take after Devbox idle timer is triggered. shutdown: Shutdown the Devbox. suspend: Suspend the Devbox. - `custom_cpu_cores` integer, nullable — Custom CPU cores. Must be 0.5, 1, or a multiple of 2. Max is 16. - `custom_gb_memory` integer, nullable — Custom memory size in GiB. Must be 1 or a multiple of 2. Max is 64GiB. - `custom_disk_size` integer, nullable — Custom disk size in GiB. Must be a multiple of 2. Min is 2GiB, max is 64GiB. - `architecture` 'x86_64' | 'arm64' - `user_parameters` UserParameters — Configuration for the Linux user in the Devbox environment. - `username` string, required — Username for the Linux user. - `uid` integer, required — User ID (UID) for the Linux user. Must be a non-negative integer. - `required_services` string[], nullable — 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` string, nullable — (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` LifecycleConfigurationParameters — Lifecycle configuration for Devbox idle and resume behavior. Configure idle policy via after_idle, resume triggers via resume_triggers, and optional lifecycle hooks via lifecycle_hooks. - `after_idle` IdleConfigurationParameters - `idle_time_seconds` integer, required — After idle_time_seconds, on_idle action will be taken. - `on_idle` 'shutdown' | 'suspend', required — Action to take after Devbox idle timer is triggered. shutdown: Shutdown the Devbox. suspend: Suspend the Devbox. - `resume_triggers` ResumeTriggers — Triggers that can resume a suspended Devbox. - `http` boolean, nullable — When true, HTTP traffic to a suspended Devbox via tunnel will trigger a resume. - `axon_event` boolean, nullable — When true, axon events targeting a suspended Devbox will trigger a resume. - `lifecycle_hooks` LifecycleHooks — Lifecycle hooks for Devbox suspend. suspend_commands run sequentially as the configured Devbox user before the Devbox suspends; failures are logged but do not block suspending. The suspend_deadline_ms budget defaults to 30000 ms, may not exceed 60000 ms, and covers broker drain plus suspend_commands. If the deadline is exceeded, suspend work is abandoned, the timeout is logged, and the Devbox still proceeds to suspend. launch_commands still run on every startup, including after resume. - `suspend_commands` string[], nullable — Commands to run through the suspend path before the Devbox suspends (e.g. cleanup, quiesce daemons). - `suspend_deadline_ms` integer, nullable — Deadline in milliseconds for broker drain and suspend_commands during suspend. Defaults to 30000 ms and may not exceed 60000 ms. If exceeded, suspend work is abandoned, the timeout is logged, and the Devbox still proceeds to suspend by shutting down vmagent and killing the VM. - `provisioning_tier` 'standard' | 'flex' - `file_mounts` object, nullable — (Optional) Map of paths and file contents to write before setup. - `base_blueprint_id` string, nullable — (Optional) ID of previously built blueprint to use as a base blueprint for this build. - `base_blueprint_name` string, nullable — (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` ContainerizedServiceView[], nullable — (Optional) List of containerized services to include in the Blueprint. These services will be pre-pulled during the build phase for optimized startup performance. - `name` string, required — The name of the container service. - `image` string, required — The image of the container service. - `credentials` Credentials - `username` string, required — The username of the container service. - `password` string, required — The password of the container service. - `env` object, nullable — The environment variables of the container service. - `port_mappings` string[], nullable — The port mappings of the container service. Port mappings are in the format of :. - `options` string, nullable — Additional Docker container create options. - `metadata` object, nullable — (Optional) User defined metadata for the Blueprint. - `build_args` object, nullable — (Optional) Arbitrary Docker build args to pass during build. - `secrets` object, nullable — (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` BuildContext — A build context backed by an Object. - `object_id` string, required — The ID of an object, whose contents are to be used as a build context. - `type` 'object', required - `network_policy_id` string, nullable — (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. - `failure_reason` 'out_of_memory' | 'out_of_disk' | 'build_failed' — The cause of the failure of the Blueprint build. out_of_memory: The build has run out of memory. Contact support if this is unexpected. out_of_disk: The build has run out of disk. Contact support if this is unexpected. build_failed: The build has failed. Use the dashboard to look at Blueprint build logs for more info. - `base_blueprint_id` string, nullable — The ID of the base Blueprint. - `containerized_services` ContainerizedServiceView[], nullable — List of ContainerizedServices available in the Blueprint. Services can be explicitly started when creating a Devbox. - `name` string, required — The name of the container service. - `image` string, required — The image of the container service. - `credentials` Credentials - `username` string, required — The username of the container service. - `password` string, required — The password of the container service. - `env` object, nullable — The environment variables of the container service. - `port_mappings` string[], nullable — The port mappings of the container service. Port mappings are in the format of :. - `options` string, nullable — Additional Docker container create options. - `is_public` boolean — Whether this Blueprint is publicly accessible to all users. - `metadata` object, nullable — User defined metadata associated with the blueprint. - `devbox_capabilities` DevboxCapabilities[], nullable — Capabilities that will be available on Devbox. ## Changes - **2026-08-20** `e9dc776053e4` — 1 warning - added the new `awaiting_upload` enum value to the `status` response property for the response status `200` - **2026-06-09** `b4ffb9a8aff3` — 2 info - added the new optional request property `launch_parameters/anyOf[#/components/schemas/LaunchParameters]/provisioning_tier` - added the optional property `parameters/launch_parameters/anyOf[#/components/schemas/LaunchParameters]/provisioning_tier` to the response with the `200` status - **2026-05-27** `d3ddb452754c` — 31 breaking, 28 warning, 14 info - the request property `base_blueprint_id` became not nullable - the request property `base_blueprint_name` became not nullable - the request property `build_args` became not nullable - the request property `build_context` became not nullable - …69 more - **2026-04-13** `5b536a11a713` — 2 info - added the new optional request property `launch_parameters/lifecycle/resume_triggers/axon_event` - added the optional property `parameters/launch_parameters/lifecycle/resume_triggers/axon_event` to the response with the `200` status - …earlier changes not shown [Full history](https://skmtc.dev/runloopai/apis/runloop-api/changes/v1/blueprints/post.md) --- [API](https://skmtc.dev/runloopai/apis/runloop-api.md) · [All operations](https://skmtc.dev/runloopai/apis/runloop-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/runloopai/runloop-api/revisions/e9dc776053e4/schema)