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, starts the remote Firecracker image build, and waits for the result.
Custom image builds are currently CLI-first. You need Docker available on the machine running hx image build.

​
Build A Custom Image

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. 
hx create --image-name app-prod

​
List Available Images

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.
Custom images do not pick up the docker defined entrypoint. You must pass in the —entrypoint parameter when building the image to start the command.