Skip to main content
Start with the Runloop Quickstart to use the examples below.

​
Creating Blueprints from Public Image Registries

Runloop supports creating Blueprints from public image registries. This is useful when you want to use a specific version of a tool or framework.

​
Docker Hub Images

This process works with any image that is available on Docker Hub. The following example creates a Blueprint from the wordpress image at Docker Hub: 
blueprint = await runloop.blueprint.create(
  name="wordpress-bpt",
  dockerfile="FROM wordpress"
)

​
Public ECR Images

For more information about Docker-in-Docker support and available images, see Running Docker on a Devbox. 
blueprint = await runloop.blueprint.create(
  name="runloop-dnd-bpt",
  dockerfile="FROM runloop:runloop/prod-dnd-arm64"
)

​
Using Secrets in Blueprints

You can securely inject secrets (like API tokens, credentials, or SSH keys) into your blueprint build process. This is useful for accessing private resources during the build, such as cloning private repositories or downloading authenticated packages.

​
Setting Up Secrets

  1. Create secrets in the Settings page of your Runloop Dashboard or via the SDK
  2. Mount secrets when creating a blueprint using the format { env_var_name: secret_name }
  3. Use secrets in either dockerfile or system_setup_commands

​
Example: Using an npm token to install a private package

This example assumes you have an npm token with the read:packages scope. 
blueprint = await runloop.blueprint.create(
  name="npm-token-blueprint",
  dockerfile="FROM ubuntu:22.04\n\nRUN npm install -g npm \nRUN npm install -g npm-cli-login \nRUN npm-cli-login -u \"myusername\" -p \"${NPM_TOKEN}\" -e \"[email protected]\" -r \"https://npm.pkg.github.com\" -s \"@myorg\"",
  secrets={"NPM_TOKEN": "npm-token"}
)

​
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. To avoid unnecessarily downloading full Linux installations, base your Dockerfile on the Runloop base image. Note that you must use the runloop: prefix: 
    FROM runloop:runloop/starter-arm64
    The Runloop base image is public and can be downloaded for local testing.
  2. When you create a Blueprint with your Dockerfile, Runloop will:
    • Use your Dockerfile as the base
    • Apply any launch_parameters.launch_commands specified
    • Set up any code mounts you have defined

​
Composable Blueprints

Runloop supports multistage builds, allowing you to create a Blueprint using another Blueprint as the base. This enables layered configurations where common tooling can be shared across multiple specialized blueprints. 
blueprint = await runloop.blueprint.create(
  name="composed-blueprint",
  base_blueprint_id="bpt_123456789"
)
Alternatively, you can achieve the same result by including a base blueprint using the standard FROM instruction via the Dockerfile parameter to specify the composable Blueprint for building: 
FROM runloop:bpt_123456789

# Rest of Dockerfile

​
Customizing the Base User

You can customize the base user for a Blueprint. SSH and execute commands to Devboxes created from this blueprint will be via the specified user. 
dockerfile = """
FROM ubuntu:22.04
USER root
WORKDIR /root
RUN adduser -uid 9999 newdevboxuser
USER newdevboxuser
"""

blueprint = await runloop.blueprint.create(
  name="bp_custom_user",
  dockerfile=dockerfile,
  launch_parameters={
    "user_parameters": {
      "username": "newdevboxuser",
      "uid": 9999
    },
    "launch_commands": []
  },
)

print(f"Blueprint created with ID: {blueprint.id}")

​
Next Steps