Identity. An environment is a name within a scope. The local scope belongs to one user and needs no privileges; the system scope is shared by every user on the machine, and only root may create, change, serve or remove its environments (any user may run commands in one). A name is 1 to 64 characters of ASCII letters, digits, -, _ and ., beginning with a letter or digit, unique within its scope. A lookup by name tries the local scope first, so a local environment may shadow a system one of the same name.

Backend. Each environment has one backend, fixed at creation:

When no backend is named, mim chooses native where the host can run it (glibc Linux, Apple Silicon macOS, or NixOS with nix and unprivileged user namespaces), and otherwise a configured container engine or the only one installed. With several engines and no configured choice it asks rather than guessing.

Files. Each scope has a configuration root and a data root:

An environment’s configuration directory holds its settings, its views (Serving), its extra engine flags and the record of its running server. It is small, edited by mim only, and never visible inside the environment. The environment exists exactly when its settings record does.

Its data directory holds everything the environment’s programs see: the Morloc home and state (Overview), the solved toolchain and its lock, the recorded requirements of every program (Environment solving), the home directory of its shell, and its server logs. Downloads that environments can share — compiler releases, the solver binary, mim binaries for other platforms — are stored once per scope in the data root and never modified after they are complete.

The default environment. A command that names no environment acts on the default. Each scope records at most one default, by name. The local default wins if it names an existing environment; otherwise the system default applies. There is no activation step and no variable that selects an environment, so a command means the same thing in every shell.

Running a command. mim run and mim shell execute a command with the environment’s compiler, runtime, toolchain and installed programs first on the PATH and its home as MORLOC_HOME. The working directory is the user’s current directory, mounted at /work in a container, and files written there belong to the invoking user. A container sees only the host variables passed to it explicitly. The command’s exit status becomes `mim’s.

Three variables mark a command as running in a managed environment, and are set together:

The hook is mim itself, in the same binary as the manager. Staging the manager’s own binary into the environment keeps the two at one version.

Before a solve, a build or a native command, mim removes the variables of any other conda, mamba or pixi environment active in the user’s shell. Their activation scripts add compiler flags and library paths, and mixing two package worlds produces binaries that link against both.

Changing an environment. mim update rebuilds an environment and mim modify changes its settings, rebuilding when the toolchain changes. The Morloc version an environment was provisioned with moves only when an update asks for another version explicitly; no other command changes it. A move is refused if an installed module declares a range of Morloc versions that excludes the target. A change either completes or leaves the environment’s settings, requirements and solved toolchain as they were.

Removal. mim rm stops the environment’s server, then removes its configuration, data, image and volumes. It leaves alone directories the user supplied (a host directory mounted as its home) and the shared downloads, so a later mim new does not start from nothing.