---
title: "Preview Dockerfile definition for a Blueprint."
method: POST
path: "/v1/blueprints/preview"
tags: ["Blueprint", "Blueprint-ObservabilityTools"]
---

# Preview Dockerfile definition for a Blueprint.

`POST /v1/blueprints/preview`

Preview building a Blueprint with the specified configuration. You can take the resulting Dockerfile and test out your build using any local docker tooling.

## 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}s.
    - `repo_owner` string, required — The owner of the repo.
    - `install_command` string, nullable — Installation command to install and setup repository.
    - `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. These must be int values that are a multiple of 2 with a cpu:memory ratio between 2 and 8 inclusive. Min/Max permitted cpu cores, memory, and disk size are 1/16, 2/64, and 2/64 respectively.
    - `keep_alive_time_seconds` integer, nullable — Time in seconds after which Devbox will automatically shutdown. Default is 1 hour.
    - `available_ports` integer[], nullable — A list of ports to make available on the Devbox. Only ports made available will be surfaced to create tunnels via the 'createTunnel' API.
    - `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 resource size, number of cpu cores, must be multiple of 2. Min is 1, max is 16.
    - `custom_gb_memory` integer, nullable — custom memory size, number in GiB, must be a multiple of 2. Min is 2GiB, max is 64GiB.
    - `custom_disk_size` integer, nullable — custom disk size, number 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 positive 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.
  - `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 <host_port>:<container_port>.
    - `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.

## Response `200`

OK

- BlueprintPreviewView
  - `dockerfile` string, required — The Dockerfile contents that will built.

## Changes

- **2025-09-30** `9b2e136aedff` — 1 info
  - added the new optional request property `build_args`

[Change history](https://skmtc.dev/runloopai/apis/runloop-api/changes/v1/blueprints/preview/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/d1cc15eb5ef9/schema)