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 invalidates that tool's layer (a Python bump also invalidates pypi tool layers, which are relocated against it); other tool layers and the base image layers are reused, while the generated /etc/mise/config.toml layer, image config, and manifest are regenerated. The output directory follows the OCI image-layout spec.

Only tools from project config files are packaged, including a monorepo root's config. The global and system configs and a config directly in your home directory, such as ~/mise.toml, are left out unless you pass --include-global.

Build on a Linux host with the image's architecture. Tools are packaged as installed on the host, and so is the running mise binary, at /usr/local/bin/mise, unless you pass --no-mise. asdf plugins are not supported; use a vfox plugin or any other backend for each tool. vfox plugins are copied into the image next to the tools they install.

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 package tools from the global and system configs

    By default mise oci build packages only project config files, including a monorepo root's config. With this flag it also includes the tools, [oci], [bootstrap.packages], and [dotfiles] of the global and system configs and of a config directly in your home directory, so personal tools from ~/.config/mise/config.toml end up in the image.

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

  • --mount-point <MOUNT_POINT> — Where tools install inside the image

    Overrides [oci].mount_point and the oci.default_mount_point setting.

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

  • --no-cache — Rebuild tool layers without reading or writing the local layer cache

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

    Overrides [oci].user_id and [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 ​

Build the project's image into ./mise-oci

mise oci build

Use another base image and record a tag

mise oci build --from ubuntu:24.04 --tag myorg/dev:latest -o ./img

Inspect the result

skopeo inspect oci:./img

Open a shell in it

mise oci run --image-dir ./img -- /bin/sh
MIT LicenseCopyright © 2026jdx.dev