Full example

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 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.

When should I use a Blueprint vs. a Snapshot?

Snapshots and Blueprints both allow you to run devboxes with customizations. Blueprints are fast to boot and cacheable using Docker layers, while Snapshots are a bit slower on boot (reproducing each step taken in the devbox) but 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 and future devboxes will cache the installation to speed up boot and execution 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.

​
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:

curl -X POST 'https://api.runloop.ai/v1/blueprints' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $RUNLOOP_API_KEY" \
  -d '{
  "name": "docs-template",
  "system_setup_commands": ["sudo apt install -y jq"]
}'

Use the Debian package manager (apt) for installing system packages on the Runloop base image.

​
Using Your Blueprint

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

curl -X POST 'https://api.runloop.ai/v1/devboxes' \
  -H "Authorization: Bearer $RUNLOOP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "blueprint_name": "fe-bot",
    "setup_commands": [
      "cd /home/user/runloop-fe && git pull",
      "npm install"
    ]
  }'

​
Creating Blueprints with CodeMounts

​
Basic Configuration

To add a CodeMount to your Blueprint:

curl -X POST 'https://api.runloop.ai/v1/blueprints' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $RUNLOOP_API_KEY" \
  -d '{
    "name": "fe-bot",
    "code_mounts": [{
      "repo_name": "runloop-fe",
      "repo_owner": "runloop"
    }]
  }'

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):

curl -X POST 'https://api.runloop.ai/v1/blueprints' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $RUNLOOP_API_KEY" \
  -d '{
    "name": "fe-bot",
    "code_mounts": [{
      "repo_name": "runloop-fe",
      "repo_owner": "runloop",
      "token": "'"${GH_TOKEN}"'"
    }]
  }'

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:

curl -X GET 'https://api.runloop.ai/v1/blueprints/{blueprint_id}' \
  -H "Authorization: Bearer $RUNLOOP_API_KEY"

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:

​
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

The Runloop base image is public and can be downloaded for local testing.

​
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.

curl -X POST 'https://api.runloop.ai/v1/blueprints' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $RUNLOOP_API_KEY" \
  -d '{
    "name": "fe-bot",
    "code_mounts": [{
      "repo_name": "runloop-fe",
      "repo_owner": "runloop",
      "token": "'"${GH_TOKEN}"'"
    }]
  }'

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

If any of these features are critical for your use case, please let us know.