> ## 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 wire

> Register an existing image as a Devbox base image.

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

## Usage

```bash theme={null}
devbox image wire <image-ref> [flags]
```

## Examples

### Register an existing image

```bash theme={null}
devbox image wire registry.example.com/team/dev:latest --description "Team development image"
```

### Register an image with startup configuration

```bash theme={null}
devbox image wire registry.example.com/team/dev:latest --user vscode --shell /bin/zsh --port_forward 3000,8080
```

## Options

<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="--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. Secret mappings take precedence over `--env` entries.
</ResponseField>

<ResponseField name="--shell" type="string">
  Override the image's default shell.
</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">
    Learn how Devbox base images are used.
  </Card>

  <Card title="devbox image build" icon="hammer" href="/docs/reference/devbox-cli/image-build">
    Build and register an image from a Dockerfile.
  </Card>

  <Card title="devbox image describe" icon="file-search" href="/docs/reference/devbox-cli/image-describe">
    Inspect registered image metadata.
  </Card>
</Columns>