ContextQMD
Back to Mise

`mise oci run`

docs/cli/oci/run.md

2026.8.123.2 KB
Original Source
<!-- @generated by usage-cli from usage spec -->

mise oci run

[experimental] Build an OCI image from the current mise.toml and run a command in it

Equivalent to mise oci build followed by docker run / podman run. The built image is loaded into the local container engine (podman pulls the OCI layout natively; docker receives it via docker load) and the given command is executed inside it with stdin/stdout/stderr inherited.

Requires mise settings experimental=true (or MISE_EXPERIMENTAL=1) and one of: podman, docker.

Arguments

  • [-- CMD]… — Command and arguments to run inside the container (after --)

Flags

  • --engine <ENGINE> — Container engine to use (auto, podman, or docker)

    Choices: auto, podman, docker

    Default: auto

  • --from <FROM> — Base image reference for the build (ignored with --image-dir)

  • --image-dir <IMAGE_DIR> — Use an already-built OCI image layout instead of building fresh

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

    See mise oci build --help for details.

  • --keep — Keep the loaded image in the engine's storage after the run

    By default, both the container (--rm) and the loaded image are removed when the command exits, so repeated mise oci run calls don't accumulate images in podman / docker storage. Pass --keep to retain the image under the tag mise used (mise-oci:run-* for docker; the pulled image ID for podman).

  • --mount-point <MOUNT_POINT> — Override in-image mount point (ignored with --image-dir)

  • --no-mise — Don't embed the mise binary (ignored with --image-dir)

  • --owner <UID[:GID]> — UID[:GID] to assign to every tar entry when building (conflicts with --image-dir)

    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.

  • --volume… <HOST:CONTAINER> — Bind-mount a host path (repeatable, HOST:CONTAINER[:MODE])

    Note: unlike docker run -v, there's no -v short flag here because mise reserves -v for --verbose. Use --volume or --mount.

  • -e --env… <KEY=VAL> — Set environment variable in the container (repeatable, KEY=VAL)

  • -i --interactive — Run interactively (pass -i to the engine)

  • -t --tty — Allocate a TTY (pass -t to the engine)

  • -w --workdir <WORKDIR> — Working directory inside the container

  • -h --help — Print help

Examples:

Build the current mise.toml and drop into bash:
$ mise oci run -it -- bash

Run a one-shot command with env + volume (note: `-v` is reserved
for --verbose, so use `--volume`):
$ mise oci run -e DEBUG=1 --volume $PWD:/work -w /work -- npm test

Re-use a previously built layout (skip the build step):
$ mise oci build -o ./img && mise oci run --image-dir ./img -- node -e 'console.log(process.version)'

Engines:

Prefers podman (loads OCI layouts natively). Falls back to docker
(loaded via docker load). Pass --engine podman or --engine docker to override.