Skip to main content
Register an existing container image as a Devbox base image, attach Devbox capabilities, and optimize it by default.

Usage

Examples

Register an existing image

Register an image with startup configuration

Options

string
Load image capabilities from a JSON BlueprintSpec file. The parser accepts JSON with comments.
string
Set a human-readable image description.
stringToString
default:"[]"
Add environment variables as key-value pairs, such as -e FOO=bar.
strings
Add commands that run once when a Devbox is first created. Repeat the option to add multiple commands.
strings
Add commands that run whenever a Devbox starts. Repeat the option to add multiple commands.
boolean
default:"true"
Optimize the image after registration. Pass --optimize=false to defer optimization until startup.
string
default:"whole"
Set the persistency mode to whole, workspace_dir, or none.
int32Slice
default:"[]"
Configure ports to forward automatically, such as --port_forward=8080,3000.
stringToString
default:"[]"
Map environment variable names to secret IDs. Secret mappings take precedence over --env entries.
string
Override the image’s default shell.
string
Set the remote user for Devboxes created from the image.
string
Override the workspace directory. When omitted, /workspaces is used.

Custom images

Learn how Devbox base images are used.

devbox image build

Build and register an image from a Dockerfile.

devbox image describe

Inspect registered image metadata.
Last modified on August 28, 2026