Skip to main content
Build a container image from a Dockerfile, register it as a Devbox base image, and optimize it by default. The context directory is uploaded to Namespace’s remote builder and honors .dockerignore.

Usage

Examples

Build an image from the current directory

Use a Dockerfile in a subdirectory

Options

string
required
Set the repository name for the built image, such as devbox/baseimage.
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.
string
default:"Dockerfile"
Set the Dockerfile path relative to the context directory.
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, such as --secrets DB_PASS=my-secret. Secret mappings take precedence over --env entries.
string
Override the image’s default shell, such as /bin/zsh.
string
Set the remote user for Devboxes created from the image.
string
Override the workspace directory. When omitted, /workspaces is used.

Custom images

Write a Dockerfile and use the resulting image.

devbox image list

List registered images.

devbox image wire

Register an image that already exists.
Last modified on August 28, 2026