mim builds an environment in one of two ways, called backends.

Both behave the same for writing, building, and serving programs. The difference that matters for deployment is the last step: only a container environment can be frozen into a portable image (Freezing). Since this chapter ends with a freeze, the running example uses Podman:

--engine takes podman, docker, apptainer (or its older name singularity), or none for the native backend. Apptainer is experimental (see Installing Morloc). Leave --engine off and mim picks the native backend on hosts that support it, or the one container engine it finds installed. If it finds several, it asks you to name one. The first choice you make is remembered for later environments.

The name, smiles here, is optional. Without one, the environment is named after the Morloc version it tracks: latest, or v0.105.2 when you pin a version with --morloc-version 0.105.2.

The first mim new is slow. It downloads the Morloc compiler, solves the toolchain, and, for a container environment, builds an image (named localhost/morloc-env:<name>). Later environments reuse the downloaded compiler, and rebuilding with unchanged requirements skips the solve.

Every mim command acts on one environment: the one named with --env, or otherwise the default. The first environment you create becomes the default on its own; --set-default makes any later one the default as it is created. To change it afterwards:

There is no activation step and no environment variable that selects an environment. Keep the default stable and reach for --env when you need another one, so a bare command in your shell history always means the same thing.

An environment lives in one of two scopes:

A local environment belongs to you and needs no privileges. $XDG_CONFIG_HOME and $XDG_DATA_HOME move the two local directories if you set them.

A system environment is shared by every user on the machine. Creating, changing, and removing one requires root, so those commands run under sudo. Using it does not: any user can run and shell in it, and can make it their personal default without sudo.

When a local and a system environment share a name, --env finds the local one. mim info <name> --system describes the system one.

mim run executes one command in an environment, and mim shell opens an interactive shell in it. Everything after -- is the command:

Inside, morloc, the language runtimes, and every program installed in the environment are on the PATH. Your current directory is the working directory: mounted at /work in a container, used as-is on the native backend. A shell’s prompt is tagged with the environment’s name, and exit leaves it.

A container does not see your host’s environment variables. Pass the ones a command needs with --env-var, or a file of them with --env-file:

On a host with SELinux enforcing (Fedora, RHEL), mim relabels the mounted directory with the :z suffix so the container may read it. Relabeling some directories would be unsafe, so mim refuses to run from /, or from /tmp or /var/tmp and anything below them. Run from your home directory itself and it skips the working-directory mount with a warning. Work in a project directory such as ~/smiles-project.

mim modify changes an environment’s settings. Some changes take effect at once; others alter the toolchain and rebuild the environment at its current Morloc version. A rebuild that fails rolls the settings back, so a typo never leaves the environment broken.

Each flag that sets something has a --no- form that clears it, such as --no-conda-packages-file. A package file is the whole list for its source: to add one package, edit the file and pass it again.

mim update rebuilds the environment. Without flags it keeps the Morloc version it has; it never moves the version by surprise.

Moving the Morloc version does not recompile the programs already installed; reinstall them afterwards (Dependency management).

Anything a container engine needs beyond what mim passes on its own — a GPU device, a proxy, a bind mount, a hostname — goes in an engine flag file. It is a YAML document divided by phase, the engine command an environment runs: build (the image build, at new, update, a modify that rebuilds, and freeze), run (run, shell, install), and start (the serving container). Under each phase, an engine section (docker, podman, apptainer) lists the flags that engine gets, and all lists flags every engine gets:

Every section is optional. The schema is strict: an unknown phase or engine name, such as a misspelt podmann:, is an error rather than ignored. Each entry passes through the shell before it reaches the engine, so $HOME, ~, and globs expand, an unquoted space splits an entry into two arguments, and a value containing a space must be quoted as it would be in a shell.

Install the file when creating the environment, or later with modify:

The file is validated and copied whole, comments included, to the environment’s configuration directory as env.flags.yaml, replacing any previous one. mim info <name> names it and shows the flags each phase gets for the environment’s engine. The build section is part of what decides whether the image is up to date, so changing it makes the next update rebuild.

For each command the flags are <phase>.all followed by <phase>.<engine>, then any one-off flags from the command line. Two command-line overrides exist, and neither changes the stored file:

--platform is refused in the file and on the command line, because the environment’s architecture (mim new --arch) decides it and the toolchain was solved for that architecture. The native backend has no engine to pass flags to, so --flagfile and -x are errors there.

mim rm removes environments by name. For a container environment it also stops its server, removes its image, and removes the volume that held its toolchain. If you remove the default, the default is cleared and mim tells you how to set a new one.

mim nuke removes every environment in a scope after asking for confirmation. Pass --yes to skip the question in a script, --system for the system scope, and --images to also delete the base images the environments were built from. Those base images, such as ubuntu:24.04, may be used by other things on your machine.

Neither command touches the Morloc compilers mim has downloaded, its copy of pixi, or the shared package cache, so a later mim new does not start from nothing.