# Sandbox operations

> In-sandbox min helper commands: add packages, search, check configuration, and run tasks from within a sandbox.

Source: https://minimal.dev/docs/reference/sandbox-operations
Last updated: 2026-08-07

`min` helper commands are available within task sandboxes (Linux-only) and
inside [sessions](https://minimal.dev/docs/reference/cli-min), which install the same helper as
`/usr/bin/min`.

> **Naming note**: the in-sandbox `min` helper is a different tool from the
> [`min` session CLI](https://minimal.dev/docs/reference/cli-min) that happens to share its name. Inside a
> task sandbox, `min` always refers to the helper documented here; the session
> CLI is not available there.

## Commands

### `add [FLAG] <PACKAGES...>` {#add}

Installs tools & dependencies into the running sandbox. The default differs
by sandbox type: in a **session**, `min add <pkg>` with no flag defaults to
`--session`, installing the package live and recording it in the `[session]`
`packages` list of the project's `minimal.toml`; in a **task sandbox**, no
flag installs for the current sandbox only and `minimal.toml` is not
modified. With a flag, the named packages are recorded as a session, runtime,
or build dependency in `minimal.toml`.

| Flag | Description |
|------|-------------|
| `--session` | Also add packages to the `[session]` `packages` list in `minimal.toml` |
| `--runtime` | Also add packages to `stack.runtime_packages` |
| `--build` | Also add packages to `stack.build_packages` |

`min add` is the in-sandbox counterpart of [`mip add`](https://minimal.dev/docs/reference/cli-mip#add); note the flag surfaces differ (`mip add` requires one of `--runtime`, `--build`, or `--task <TASK>`).

`min package add` is the canonical noun-verb spelling; `min add` is an accepted alias.

### `search <TERM>`

Searches for and lists packages related to the search term.

`min package search` is the canonical noun-verb spelling; `min search` is an accepted alias.

### `check [<OPTIONS>] [FILTER_NAMES...]`

Validates minimal configuration including packages & stacks.

| Flag | Description |
|------|-------------|
| `--fix` | Attempt to fix any issues |
| `--packages` | Check packages defined in the codebase |
| `--stacks` | Check stacks defined in the codebase |

If no type flags are specified, all types are checked by default.

If filter names are specified, any package or stack matching a specified name is checked.

`min check` is the in-sandbox equivalent of the [`mip check`](https://minimal.dev/docs/reference/cli-mip#check)
command, with a reduced flag set (no `--skip-checkers`, and no short flag
aliases).

### `run <TASK_NAME> [<ARGS>...]`

Runs the specified task in a new Minimal sandbox. Interactive tasks are not supported.

`min run` is the in-sandbox equivalent of the [`mip run`](https://minimal.dev/docs/reference/cli-mip#run) command.

`min task run` is the canonical noun-verb spelling; the bare `min run` is a legacy alias.

### `package build <PACKAGES...>`

Builds the named packages in a clean room, making them available in the local
cache.

### `package patched-build <PACKAGE>`

Builds the named package in a clean room using potentially-stale dependencies
(the already-cached builds of its dependencies, without rebuilding them first),
and commits the result to the local cache. Useful for quickly iterating on a
single package's build.

### `materialize [--arch <arch>] -o <out-file> <output-name>`

Materializes an output specified in an
[`[outputs.<name>]`](https://minimal.dev/docs/reference/minimal-dot-toml#outputs) section of
`minimal.toml`.

| Flag | Short | Description |
|------|-------|-------------|
| `--output <PATH>` | `-o` | **(required)** The output file to write |
| `--arch <ARCH>` | | Override the architecture used when building the output (e.g. `amd64`, `arm64`); takes precedence over the `arch` field in `minimal.toml` and the host default |