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

# Build And Upload A Custom Image

> Package a local Docker image into a Hyperbrowser sandbox image with the CLI

Use a custom image when the built-in base images are close, but not enough. The CLI packages a local Docker image, uploads it, and dispatches the remote Firecracker image build. The build continues asynchronously after the command exits.

<Note>
  Custom image builds are currently CLI-first. You need Docker available on the machine running `hx vm image build`.
</Note>

## Build A Custom Image

```bash theme={null}
build_id=$(hx --json vm image build node:22 my-node | jq -r '.id')
hx vm image wait "$build_id"

hx vm image build myorg/app:latest app-prod
hx vm image build myorg/app:latest app-prod --env NODE_ENV=production --env PORT=3000
hx vm image build myorg/app:latest app-prod --entrypoint 'npm run start'
```

The command does four things:

* Exports your local Docker image.
* Compresses the archive locally.
* Uploads it to the Hyperbrowser artifact store.
* Dispatches the remote image build and returns its build ID.

Use `hx vm image status <build-id>` for a single status check, or `hx vm image wait <build-id>` to poll until the build completes, fails, or is canceled.

## Launch A Sandbox From The Custom Image

After the image build completes, use the registered image name in normal sandbox creation flows.

<CodeGroup>
  ```bash CLI theme={null}
  hx vm create --image-name app-prod
  ```

  ```typescript Node.js theme={null}
  const sandbox = await client.sandboxes.create({
    imageName: "app-prod",
  });
  ```

  ```python Python 1.0+ theme={null}
  sandbox = client.sandboxes.create(
      {
          "image_name": "app-prod",
      }
  )
  ```

  ```python Python (legacy) theme={null}
  from hyperbrowser.models import CreateSandboxParams

  sandbox = client.sandboxes.create(
      CreateSandboxParams(
          image_name="app-prod",
      )
  )
  ```
</CodeGroup>

## List Available Images

```bash theme={null}
hx vm image list
hx --json vm image list
```

Use this to confirm the uploaded image name before launch.

## Image Init Defaults

`hx vm image build` reads Docker-config environment variables and the image's `ENTRYPOINT`/`CMD`, then attaches them as launch-time defaults.

Use `--env KEY=VALUE` to add or override default environment variables.

Use `--entrypoint '...'` to override the detected startup command for sandboxes launched from that image.

<Note>
  Docker-defined environment variables and startup commands are auto-detected by default. Explicit `--env` and `--entrypoint` values take precedence over the detected values.
</Note>


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