Skip to main content
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.
Custom image builds are currently CLI-first. You need Docker available on the machine running hx vm image build.

​
Build A Custom Image

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.

​
List Available Images

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.
Docker-defined environment variables and startup commands are auto-detected by default. Explicit --env and --entrypoint values take precedence over the detected values.