Skip to main content
Start with the Runloop Quickstart to use the examples below.
When you create a Devbox using a standard Runloop image, you get a fully functional but generic Linux installation. To prepare things for your workload, you then often need to install tools and libraries, download data, and perform other setup actions. Blueprints allow you to optimize your workflows by specifying these startup actions once, and using them across many Devboxes. When you create a Blueprint, Runloop runs your startup actions and saves the resulting Devbox image. When you later create a Devbox from this Blueprint, it starts with a fully configured environment. By building a blueprint, you get:
  1. Standardization: Define tools, binaries, and configurations your AI agent needs at runtime.
  2. Consistency: Ensure reproducible AI behavior across Devboxes.
  3. Efficiency: Reduce Devbox startup time by pre-installing tools.
  4. Customization: Tailor environments to specific AI-assisted development needs.
When should I use a Blueprint vs. a Snapshot?Snapshots and Blueprints both allow you to run devboxes with customizations. Blueprints are built programmatically and are cacheable using Docker layers, while Snapshots can be created quickly from an existing devbox.Examples:
  • Blueprint: You have a coding agent that is performing a task that requires installing a specific tool. Create a Blueprint with set-up steps for the tool. All Devboxes you launch from that Blueprint will have the environment already set up, and will not incur installation or setup time.
  • Snapshot: You have a coding agent in a devbox considering 3 different ways to complete a task. Create a snapshot of the initial state of the devbox, create 3 parallel devboxes from that snapshot, collate the results, and then choose the best option to continue.

​
Quick Start: Create a Blueprint from a Local Dockerfile

If you already have a Dockerfile for your development environment, you can quickly convert it into a Runloop blueprint using the CLI: 
# From the current directory (uses ./Dockerfile)
rli blueprint from-dockerfile --name my-agent-env

# Specify a custom Dockerfile path
rli blueprint from-dockerfile --name my-agent-env --dockerfile ./docker/Dockerfile

# Specify a custom build context (for COPY/ADD instructions)
rli blueprint from-dockerfile --name my-agent-env --dockerfile ./docker/Dockerfile --build-context .
The CLI automatically uploads your Dockerfile and build context to Runloop, starts the build, and waits for it to complete. The build context is the directory containing files that can be referenced by COPY and ADD instructions in your Dockerfile. Once complete, create a devbox from the blueprint: 
rli devbox create --blueprint my-agent-env --name my-devbox
See the CLI documentation for more blueprint commands and options.

​
Creating a Blueprint

One use case for a blueprint is preinstalling tools your AI agent may want to use. For example, let’s create a simple Blueprint that installs jq, a lightweight command-line JSON processor: 
blueprint = await runloop.blueprint.create(
  name="docs-template",
  launch_parameters={
    "launch_commands": ["sudo apt install -y jq"]
  }
)
devbox = await blueprint.create_devbox()
print(f"Devbox created with ID: {devbox.id}" +
      f"from blueprint {blueprint.id}")
Use the Debian package manager (apt) for installing system packages on the Runloop base image.

​
The Blueprint Build Process

When you create a Blueprint, Runloop builds a custom image containing all of your specified tools and configurations. The status field indicates the current state of your Blueprint:
  • build_complete: Blueprint is ready to use
  • build_failed: Refer to the Blueprint troubleshooting guide
  • queued: Blueprint is in the queue and will start processing as soon as resources are available. If there are more than 32 builds, additional builds will be queued, up to a maximum queue length of 2000.

​
Checking Build Status

After creating a Blueprint, check its build status: 
blueprint = await runloop.blueprint.from_id(blueprint.id)
info = await blueprint.get_info()
print(f"Blueprint status: {info.status}")

# Check logs for build errors
logResult = await blueprint.logs()
for log in logResult.logs:
  print(f"{log.level}: {log.message}")

​
Best Practices

  1. Start Simple: Begin with basic Blueprints and gradually add complexity.
  2. Test Manually Using SSH: You can create a devbox and SSH into it and manually install tools to make sure the commands are correct before layering them into Blueprints.
  3. Lookup Blueprints via blueprint_name instead of blueprint_id to ensure you are using the latest version for a particular name. Use specific Blueprint IDs only when you need version control for particular setups.
  4. Implement setup_commands in your Devbox creation to keep code and dependencies up-to-date.
  5. Regularly update your Blueprints with the latest repository changes.
  6. Delete unused / deprecated Blueprints.
By leveraging Blueprints effectively, you can create optimized, consistent environments for your AI-assisted software engineering tasks, enhancing productivity and reliability in your development process.

​
Next Steps