> ## 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, starts the remote Firecracker image build, and waits for the result.

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

## Build A Custom Image

```bash theme={null}
hx image build node:22 my-node
hx image build myorg/app:latest app-prod
hx image build myorg/app:latest app-prod --env NODE_ENV=production --env PORT=3000
hx 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.
* Starts and polls the remote image build until it 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 create --image-name app-prod
  ```

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

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

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

## List Available Images

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

Use this to confirm the uploaded image name before launch.

## Image Init Defaults

`hx image build` can attach launch-time defaults to the image.

Use `--env KEY=VALUE` to set default environment variables.

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

<Note>
  Custom images do not pick up the docker defined entrypoint or the env. You must pass in the --entrypoint parameter when building the image to start the command, and the --env parameter to set the environment variables.
</Note>