> ## Documentation Index
> Fetch the complete documentation index at: https://namespace.so/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# devbox image build

> Build and register a Devbox base image from a Dockerfile.

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

```bash theme={null}
devbox image build <context-dir> [flags]
```

## Examples

### Build an image from the current directory

```bash theme={null}
devbox image build . --name my-team/golang
```

### Use a Dockerfile in a subdirectory

```bash theme={null}
devbox image build . --name my-team/dev --file ./devbox/Dockerfile
```

## Options

<ResponseField name="--name" type="string" required>
  Set the repository name for the built image, such as `devbox/baseimage`.
</ResponseField>

<ResponseField name="--capabilities" type="string">
  Load image capabilities from a JSON `BlueprintSpec` file. The parser accepts JSON with comments.
</ResponseField>

<ResponseField name="--description" type="string">
  Set a human-readable image description.
</ResponseField>

<ResponseField name="-e, --env" type="stringToString" default="[]">
  Add environment variables as key-value pairs, such as `-e FOO=bar`.
</ResponseField>

<ResponseField name="-f, --file" type="string" default="Dockerfile">
  Set the Dockerfile path relative to the context directory.
</ResponseField>

<ResponseField name="--on_create" type="strings">
  Add commands that run once when a Devbox is first created. Repeat the option to add multiple commands.
</ResponseField>

<ResponseField name="--on_startup" type="strings">
  Add commands that run whenever a Devbox starts. Repeat the option to add multiple commands.
</ResponseField>

<ResponseField name="--optimize" type="boolean" default="true">
  Optimize the image after registration. Pass `--optimize=false` to defer optimization until startup.
</ResponseField>

<ResponseField name="--persistency" type="string" default="whole">
  Set the persistency mode to `whole`, `workspace_dir`, or `none`.
</ResponseField>

<ResponseField name="--port_forward" type="int32Slice" default="[]">
  Configure ports to forward automatically, such as `--port_forward=8080,3000`.
</ResponseField>

<ResponseField name="--secrets" type="stringToString" default="[]">
  Map environment variable names to secret IDs, such as `--secrets DB_PASS=my-secret`. Secret mappings take precedence over `--env` entries.
</ResponseField>

<ResponseField name="--shell" type="string">
  Override the image's default shell, such as `/bin/zsh`.
</ResponseField>

<ResponseField name="--user" type="string">
  Set the remote user for Devboxes created from the image.
</ResponseField>

<ResponseField name="--workspace_dir" type="string">
  Override the workspace directory. When omitted, `/workspaces` is used.
</ResponseField>

## Related topics

<Columns cols={3}>
  <Card title="Custom images" icon="hard-drive" href="/docs/devbox/images">
    Write a Dockerfile and use the resulting image.
  </Card>

  <Card title="devbox image list" icon="list" href="/docs/reference/devbox-cli/image-list">
    List registered images.
  </Card>

  <Card title="devbox image wire" icon="cable" href="/docs/reference/devbox-cli/image-wire">
    Register an image that already exists.
  </Card>
</Columns>