mise-en-place

Appearance

mise oci build ​

[experimental] Build an OCI image from the current mise.toml

Each tool version becomes its own content-addressable OCI layer. Bumping a tool version only invalidates that tool's layer — other tools, the base image, and config are reused unchanged. The output directory conforms to the OCI image-layout spec. Use skopeo inspect oci:./mise-oci to inspect it or mise oci run --image-dir ./mise-oci -- command to load and run it.

Build on Linux with the target architecture: this packages host tool installs and, by default, the running mise binary. --no-mise omits that binary but does not cross-compile tools installed for another OS. asdf/vfox tools are unsupported.

Requires mise settings experimental=true (or MISE_EXPERIMENTAL=1).

Flags ​

  • --copy <HOST_PATH:IMAGE_PATH> — Copy a host file, directory, or symlink into the image (repeatable, HOST:IMAGE)

  • -o --output <OUTPUT> — Output directory for the OCI image layout

    Default: ./mise-oci

  • --from <FROM> — Base image reference (overrides [oci].from and the oci.default_from setting)

  • --include-global — Also include tools from the global / system config (default: project-only)

    By default mise oci build only packages tools declared in the project's mise config (and any parent configs at-or-below the project root, e.g. a monorepo root config). Personal dev tools in ~/.config/mise/config.toml are excluded so they don't bake into a project image. Pass --include-global to revert to the old "merge all loaded configs" behavior.

  • -t --tag <TAG> — Tag to record in the image index (the org.opencontainers.image.ref.name annotation)

  • --mount-point <MOUNT_POINT> — Where to place tool installs inside the image (default: /mise)

  • --no-mise — Do not embed the currently-running mise binary at /usr/local/bin/mise

  • --owner <UID[:GID]> — UID[:GID] to assign to every tar entry in generated layers

    Overrides [oci].user_id / [oci].group_id. Defaults to 0:0. If GID is omitted, it defaults to UID. This affects file ownership only; [oci].user controls the image USER directive.

  • -h --help — Print help

Examples ​

Run on a Linux host with the target architecture

mise oci build
mise oci build --from ubuntu:24.04 --tag myorg/dev:latest -o ./img
skopeo inspect oci:./img
mise oci run --image-dir ./img -- /bin/sh

Notes:

- The image only contains tools from the project's mise config (and
  any configs at-or-below the project root). Tools from
  `~/.config/mise/config.toml` are not included; pass --include-global
  to package them too.
- asdf and vfox plugins are not supported in v1; use a different backend
  (core, aqua, ubi, github, cargo, npm, go, pipx, spm, http) for each tool.
- The host mise binary is embedded at /usr/local/bin/mise by default;
  build on the same OS/arch as your target image (or pass --no-mise).
MIT LicenseCopyright © 2026jdx.dev