Dev shell

In Minimal, your dev shell is a session, which is a long-lived, isolated development environment for a project that the min CLI drives. It gives you an interactive shell with only the tools you declare, isolated from your host system. Use it for everyday development and ad-hoc commands. You can also use it to debug or to work interactively with your project’s toolchain.

Launch a shell

From your project directory, activate a session and attach to it in one step:

$ min session activate --attach .

This creates a session for the project and drops you into its interactive shell. The path argument defaults to the current directory, so min session activate --attach on its own works too.

Activation uploads your project files into the session’s workspace, so the shell starts with a copy of your project. Edits you make inside stay in the session. To bring them back to the host, use git push min://<session>. Committing inside the session and pulling from it also works.

What is in the session?

A session’s tools come from the project’s [session] block in minimal.toml. List the packages every contributor needs when working on this codebase:

[session]
packages = ["git", "curl", "ripgrep"]

Inside the session you have access to your project’s source code and these declared tools, but nothing else from the host system. Any loadouts you apply and the packages the project’s stack declares also come in. The session cannot globally install software, read unrelated files, or modify your system. Every developer working on the project gets the same isolated environment.

Customizing your session

Add more tools

Add packages to the project’s [session] block so everyone picks them up:

[session]
packages = ["git", "curl", "ripgrep", "jq", "nano"]

To add a package mid-session, run min add from inside the running session. You do not need to edit config by hand or restart your shell:

$ min add nano

This installs the tool into the running session and records it in the project’s [session] packages list, so the next activation gets it too. See the min in-sandbox commands for the full helper reference.

Access host files

By default, only your project directory is available inside the session. To bring specific host files or directories in, declare patches in the [session] block. Each patch names a source on the host and a dest under the session user’s home directory:

[session]
packages = ["git"]
patches = [
    { source = "~/.gitconfig", dest = "~/.gitconfig" },
    { source = "~/.ssh",       dest = "~/.ssh" },
]

A relative source resolves against the project directory, so source = "config/myrc" names a file in the repository. Activation rejects a source that uses .. to climb out of the project.

Set environment variables

The session starts with a clean environment. By default, host environment variables do not pass through. Set variables explicitly, or inherit them from the host, under [session.vars]:

[session.vars]
EDITOR = "nano"
AWS_PROFILE = { inherit = true }

A string value like EDITOR = "nano" defines a fixed variable. Using { inherit = true } passes through the value from your host environment, which is useful for credentials or configuration that varies per developer.

Inheriting this way is mandatory, not opportunistic. If AWS_PROFILE is not set in your host environment, activation fails rather than starting the session without it:

error: Composition gating failed: could not resolve pending var `AWS_PROFILE`: environment variable not found

Since the project commits minimal.toml, that applies to everyone on the project. Write { inherit = true, default = "..." } instead when the variable is truly optional. A loadout’s [vars] takes the opposite view of the same spelling and only warns. See Where { inherit = true } differs.

Run setup on activation

To run setup steps when a session comes up, declare lifecycle hooks in the [session] block:

[[session.lifecycle_hooks]]
on_activate = { type = "inline", value = "cargo fetch >/dev/null 2>&1 || true" }

Session lifecycle

Exit the shell to detach. The session keeps running in the background. To reattach, list, or remove sessions:

$ min session attach            # reattach to a session (resolves from the current directory)
$ min ls                        # list sessions
$ min session destroy <session> # terminate a session by name or id (or --all)

For running one-shot commands in their own sandbox rather than an interactive session, see Tasks.

Last updated