Devbox Blueprints

Often you will want to start your devboxes with your own customizations. For example, you may want to always boot with a specific version of a language or framework or set up a specific repository.

Rather than running these commands every time you launch a devbox, you can use a blueprint or snapshot to optimize boot time by saving the state of your devbox after these commands have been run. 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 environments.
3. Efficiency: Reduce Devbox startup time by pre-installing necessary tools.
4. Customization: Tailor environments to specific AI-assisted development needs.

​

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:

​

Using Your Blueprint

Once your Blueprint’s status is build_complete, create a Devbox using it:

​

Creating Blueprints with CodeMounts

​

Basic Configuration

To add a CodeMount to your Blueprint:

This creates a Blueprint named “fe-bot” that includes the “runloop-fe” repository.

​

Private Repository Authentication

For private repositories, include a GitHub Personal Access Token (PAT):

This sets up the necessary environment for immediate use of Git and GitHub tools.

​

The Blueprint Build Process

When you create a Blueprint, Runloop builds a custom image containing all specified tools and configurations.

​

Checking Build Status

After creating a Blueprint, check its status:

Replace {blueprint_id} with the ID returned when you created the Blueprint.

Example response:

{
  "id": "bpt_123",
  "name": "docs-template",
  "status": "build_complete",
  "create_time_ms": 1722264065963,
  "parameters": {
    ...
  }
}

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

​

Advanced Usage: Custom Dockerfiles

For more complex environments, you can use a full Dockerfile as the basis for your Blueprint. This is useful when you need to install multiple tools or perform complex setup operations.

1. Base your Dockerfile on the Runloop base image:

   FROM public.ecr.aws/f7m5a7m8/devbox:prod
   

2. Runloop will:

   • Use your Dockerfile as the base
   • Apply any system_setup_commands specified
   • Set up any defined CodeMounts

​

Keeping Blueprints Updated

Periodically update Blueprints by building a new blueprint with the same name. This ensures that your AI agents always work with the latest code and dependencies.

This creates a new Blueprint version with the same name, allowing for faster updates and efficient resource use.

​

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. Always use blueprint_name instead of blueprint_id to ensure you’re using the latest version. 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.

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.

​

Upcoming Features

Future releases plan to include:

• Multiple repository support in a single Blueprint
• Specific branch specifications
• Git submodules support
• Advanced multi-step build processes