API reference

Image URL

https://images.bottlefire.dev/<image>:<tag>?fs=<filesystem>&distribution=<distribution>&arch=<platform>

image: Docker/OCI image reference (e.g. mcp/playwright, debian, ghcr.io/metasymbolic/my-app).

tag: Image tag (e.g. 1.4.1).

fs: Filesystem type. One of squashfs (default), erofs, ufs.

distribution: Output format. "firecracker" (default) returns a single Linux executable that embeds Firecracker, a kernel, initrd, and the chosen rootfs image; "rootfs" returns a standalone filesystem image.

arch: Platform (e.g. linux/amd64).

Quick help

How to use an image built by Bottlefire

$ ./app --help
Bottlefire microVM Image

Usage: app.elf [OPTIONS]

Options:
      --cpus <CPUS>              Number of CPU cores
      --memory <MEMORY>          Amount of memory (in MB) allocated to the microVM [default: 256]
      --boot-args <BOOT_ARGS>    Kernel command line [default: "console=ttyS0 reboot=k panic=-1"]
      --entrypoint <ENTRYPOINT>  Container entrypoint
      --arg <ARG>                Container arguments
      --env <KEY=VALUE>          Container environment variables
      --verbose                  Enable verbose output
      --cwd <CWD>                Container working directory [default: ]
  -p, --publish <HOST:VM>        Publish host:vm port forward (e.g. -p 8080:8080)
  -v, --volume <HOST:VM[:ro]>    Directory/volume mappings (e.g. -v ./data:/data)
  -h, --help                     Print help

Authentication

Provide an API key in the Authorization header to access images that require subscription.

Authorization: Bearer bottlefire_...

HTTP responses

200: Image returned as binary response.
401: Missing or invalid API key for Pro images.
404: Image not found, or the image is private and the organization associated with the API key does not have the necessary credentials.
423: Image build in progress; try again later.
5xx: Unexpected error.