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

**--capabilities** `string`

Load image capabilities from a JSON `BlueprintSpec` file. The parser accepts JSON with comments.

**--description** `string`

Set a human-readable image description.

**-e, --env** `stringToString` (default: \[])

Add environment variables as key-value pairs, such as `-e FOO=bar`.

**--on\_create** `strings`

Add commands that run once when a Devbox is first created. Repeat the option to add multiple commands.

**--on\_startup** `strings`

Add commands that run whenever a Devbox starts. Repeat the option to add multiple commands.

**--optimize** `boolean` (default: true)

Optimize the image after registration. Pass `--optimize=false` to defer optimization until startup.

**--persistency** `string` (default: whole)

Set the persistency mode to `whole`, `workspace_dir`, or `none`.

**--port\_forward** `int32Slice` (default: \[])

Configure ports to forward automatically, such as `--port_forward=8080,3000`.

**--secrets** `stringToString` (default: \[])

Map environment variable names to secret IDs. Secret mappings take precedence over `--env` entries.

**--shell** `string`

Override the image's default shell.

**--user** `string`

Set the remote user for Devboxes created from the image.

**--workspace\_dir** `string`

Override the workspace directory. When omitted, `/workspaces` is used.

## Related topics

> [card] [Custom images](https://namespace.so/docs/devbox/images.md)
>
> Learn how Devbox base images are used.

> [card] [devbox image build](https://namespace.so/docs/reference/devbox-cli/image-build.md)
>
> Build and register an image from a Dockerfile.

> [card] [devbox image describe](https://namespace.so/docs/reference/devbox-cli/image-describe.md)
>
> Inspect registered image metadata.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.