# minimal.dev

> Minimal is a declarative isolation runtime for Claude Code, Gemini, Codex, Pi, and more: run multiple agents safely on your stack, powered by a verified software supply chain.

The package catalog tracks the gominimal/pkgs repository. Every catalog
surface is anchored at a commit sha of that repo — either floating with the
latest commit or pinned to a specific sha (content-addressed).

The sha-pinned JSON endpoints require a signed-in session: they answer 401
without one, and both the 401 and the signed-in payload are private/no-store.
The MCP server has no way to present a session, so passing a sha to an MCP
tool returns an error result. The floating-latest surfaces below stay
anonymous.

## Pages

- [Home](https://minimal.dev/): product overview of Minimal's hermetic build environments
- [Whitepaper](https://minimal.dev/blog/whitepaper): why and how hermetic, reproducible environments work
- [Company](https://minimal.dev/company): team and open roles
- [Packages](https://minimal.dev/pkgs): the packages landing — a spotlighted package, a rotating selection of featured ones, and recent writing on software supply chain security
- [Package search](https://minimal.dev/pkgs/search): browsable catalog of Minimal's curated, hermetically-built packages — search, filter and sort by versions, advisories, dependencies, scorecards
- [Package scores](https://minimal.dev/docs/reference/scorecard): what the OpenSSF Scorecard figure on a package page is — the 0-10 aggregate and raw per-check scores, from OpenSSF's weekly scan or, where OpenSSF does not cover the repository, from Minimal running the Scorecard tool — why some packages have none, and how a maintainer can raise each check or get scanned by OpenSSF
- [Documentation](https://minimal.dev/docs): guides and reference for Minimal — getting started, the dev shell, agent shell, building, and tasks; every page is listed under Documentation below
- [Blog](https://minimal.dev/blog): release recaps and writing on hermetic builds, sessions, and software supply chain security; every post is listed under Blog posts below
- [Changelog](https://minimal.dev/changelog): dated release notes — what shipped, newest first
- [Advisories](https://minimal.dev/pkgs/advisories): every security advisory affecting the package catalog, filterable by severity and status; floats with the latest commit
- [Catalog changes](https://minimal.dev/pkgs/changes): what moved between catalog commits — packages added or removed, version bumps, advisory-count shifts; floats with the latest commit

## Full text

- [/llms-full.txt](https://minimal.dev/llms-full.txt): every documentation page, blog post and changelog entry concatenated into one markdown document, each section naming the page it mirrors

## Documentation

- [Getting started](https://minimal.dev/docs/start/1-getting-started): Quickstart for Minimal: install the CLI, initialize a project, and define your toolchain and dependencies for local-first, sandboxed builds.
- [Install](https://minimal.dev/docs/start/1.5-install): Install Minimal on Linux (x86_64/aarch64) or macOS (Apple Silicon).
- [Migrate to Sessions](https://minimal.dev/docs/start/migrate-to-minimal-session): Migration to the new architecture after v0.5.0 release for Linux and macOS.
- [Initialize a project](https://minimal.dev/docs/start/2-setup): Set up a project with min init, declare your session's tools in minimal.toml, then enter an isolated session with min session activate.
- [Dev shell](https://minimal.dev/docs/start/4-dev-shell): Enter an isolated interactive development session with only your declared tools. Covers customization, host file access, and environment variables.
- [Agent shell](https://minimal.dev/docs/start/5-agents): Run AI coding agents like Claude Code inside an isolated session with declared tools and host credentials.
- [Building](https://minimal.dev/docs/start/3-building): Run builds and tests in sandboxed environments using stacks. Covers extra dependencies, test commands, and build state persistence.
- [Tasks](https://minimal.dev/docs/start/6-tasks): Define named tasks in minimal.toml that run commands in sandboxed environments with specific packages and env vars.
- [Packages](https://minimal.dev/docs/start/7-packages): Add build, runtime, session, and task-specific package dependencies using the min and mip CLIs or minimal.toml.
- [Software supply chain](https://minimal.dev/docs/concepts/software-supply-chain): Layered, composable model for declarative software dependencies, from public registries to organization-internal packages.
- [Sandboxing](https://minimal.dev/docs/concepts/sandboxing): How Minimal isolates all builds and tasks from the host system using hermetic sandboxes.
- [Sessions](https://minimal.dev/docs/concepts/sessions): What a Minimal session is, how a provider creates and hosts one, and how sessions compose from your project config plus loadouts.
- [Loadouts](https://minimal.dev/docs/concepts/loadouts): Loadouts are per-developer, session-level bundles of packages, vars, file patches, and lifecycle hooks that layer your personal environment on top of a project's shared config.
- [Stacks](https://minimal.dev/docs/concepts/stacks): Stacks wire Minimal to build codebases with specific languages and tools. Covers available stacks, usage, and how to define custom ones.
- [Packages](https://minimal.dev/docs/concepts/packages): Packages are reproducible, dependency-aware units of software in Minimal. Covers usage, definition, caching, and hermetic builds.
- [CLI Reference](https://minimal.dev/docs/reference/cli): Overview of the Minimal command-line binaries (min, mip, minimald, and minvmd) and where each is documented.
- [min CLI](https://minimal.dev/docs/reference/cli-min): Reference for the min session CLI: create, attach to, and manage sandboxed development sessions, plus the git-remote-min helper.
- [minimald daemon](https://minimal.dev/docs/reference/cli-minimald): Ops reference for the minimald host daemon: serves sandboxed sessions to the min CLI over SSH-on-UDS.
- [minvmd daemon](https://minimal.dev/docs/reference/cli-minvmd): Ops reference for the minvmd VM daemon: boots and supervises the Linux microVM that hosts minimald.
- [mip CLI](https://minimal.dev/docs/reference/cli-mip): Reference for the mip package/build CLI: build packages, run tasks, materialize outputs, and manage the local cache.
- [minimal.toml](https://minimal.dev/docs/reference/minimal-dot-toml): Schema reference for the minimal.toml configuration file: upstream, stack, defaults, tasks, and outputs sections.
- [Tasks](https://minimal.dev/docs/reference/tasks): Full task schema reference: packages, exec/bash commands, state_key, env_vars, patches, args, and interactive mode.
- [Loadouts](https://minimal.dev/docs/reference/loadouts): Per-developer loadout reference: the loadout TOML schema, config-directory layout, min CLI flags, client config, and how loadouts compose into sessions.
- [Build specs](https://minimal.dev/docs/reference/build-specs): Build spec schema for defining Minimal packages in Nickel: build_deps, runtime_deps, commands, outputs, tests, and metadata.
- [Build reproducibility](https://minimal.dev/docs/reference/reproducibility): How to make Minimal package builds byte-reproducible: the environment the sandbox provides, per-toolchain determinism flags for C/C++, Go, Rust and the Linux kernel, and how to verify.
- [Stacks](https://minimal.dev/docs/reference/stack-specs): Stack spec schema for defining build system stacks in Nickel: packages, build commands, env vars, and project detection rules.
- [Sandbox operations](https://minimal.dev/docs/reference/sandbox-operations): In-sandbox min helper commands: add packages, search, check configuration, and run tasks from within a sandbox.
- [Linux host setup](https://minimal.dev/docs/reference/linux-host-setup): Preparing a Linux host to run minimald: the unprivileged user namespace the session sandbox needs, and the sysctls and AppArmor profile that grant it on Ubuntu 24.04+.
- [Packages API](https://minimal.dev/docs/reference/api): Reference for the read-only /api/pkgs JSON endpoints, the /pkgs markdown mirrors, the /llms.txt index, and the /pkgs/advisories.xml feed.
- [Package scores](https://minimal.dev/docs/reference/scorecard): What the OpenSSF Scorecard figure on a package page is, where it comes from, why some packages have none, and how a maintainer can raise each check — with a prompt for a coding agent.
- [MCP server](https://minimal.dev/docs/reference/mcp): Reference for the hosted Model Context Protocol server at /api/mcp — connecting MCP clients and the nine read-only tools it exposes over the catalog.
- [User policy](https://minimal.dev/docs/reference/user-policy): The user_policy.toml reference: the vars/patches allow-deny-ignore schema, where the file lives, how min gates loadout and project contributions against it, and how interactive prompts write rules back.

## Blog posts

- [September 2026 Release Recap](https://minimal.dev/blog/september-2026-release-recap): Minimal's hermetic software building tools were upgraded in September with package provenance, portable loadouts, sturdier sessions, and 36 new packages.
- [There's no place like ~/](https://minimal.dev/blog/theres-no-place-like-loadouts): Learn more about Minimal's loadouts: declarative, composable, user-specific layers for environment customization. Explore the details and download cozy here.
- [August 2026 Release Recap](https://minimal.dev/blog/august-2026-release-recap): Minimal's hermetic, interconnected software building tools were upgraded in August with session dashboards, lifecycle hooks, and more than 100 package updates.
- [July 2026 Release Recap](https://minimal.dev/blog/july-2026-release-recap): Minimal's hermetic, interconnected software building tools were upgraded in July with new packages, a new macOS start process, and sessions.
- [Now Available: Minimal Sessions!](https://minimal.dev/blog/now-available-minimal-sessions): Minimal now has durable, stateful environments in Sessions. Sessions are hermetic and connected with the rest of your workflows.
- [Secure software artifacts with one command: Minimal](https://minimal.dev/blog/whitepaper): Minimal is a provenance-first build system that embeds security into development naturally rather than adding late-stage gates that slow delivery.

## Docs markdown mirrors

- [/docs/{slug}.md](https://minimal.dev/docs/reference/cli.md): every documentation page listed above has a markdown mirror at its URL plus `.md` — the page body with links resolved to canonical URLs (the example URL is the mirror for the CLI reference)

## Package markdown mirrors

- [/pkgs/{name}.md](https://minimal.dev/pkgs/jq.md): every package detail page at /pkgs/{name} has a markdown mirror at /pkgs/{name}.md — version, install command, direct + transitive advisories, dependencies, scorecard, and links, anchored at the latest commit (the example URL is the mirror for the jq package)
- [/sitemap.xml](https://minimal.dev/sitemap.xml): package-name enumeration — lists every /pkgs/{name} page URL alongside the site's other pages, so it is how to expand the {name} placeholder above and in the JSON API below; floats with the latest commit

## Package JSON API

- [/api/pkgs/bundle/latest.json](https://minimal.dev/api/pkgs/bundle/latest.json): 302 redirect to the sha-pinned listing bundle for the latest commit; cache max-age=60. The redirect is anonymous, but its target requires a signed-in session, so following it without one returns 401
- [/api/pkgs/bundle/{sha}.json](https://minimal.dev/api/pkgs/bundle/{sha}.json): listing-tier projection of every package at a commit; sha-pinned, REQUIRES A SIGNED-IN SESSION (401 without one), private/no-store
- [/api/pkgs/bundle/{sha}/full.json](https://minimal.dev/api/pkgs/bundle/{sha}/full.json): full composed record for every package at a commit, including the transitive-advisory rollup — everything at a snapshot in one request; sha-pinned, REQUIRES A SIGNED-IN SESSION (401 without one), private/no-store
- [/api/pkgs/{name}.json](https://minimal.dev/api/pkgs/jq.json): full per-package record; floats with the latest commit (max-age=60, s-maxage=3600, stale-while-revalidate)
- [/api/pkgs/{name}/sbom.json](https://minimal.dev/api/pkgs/jq/sbom.json): CycloneDX 1.5 SBOM with the transitive build+runtime closure and vulnerabilities (append ?format=spdx for SPDX 2.3); floats with the latest commit
- [/api/pkgs/{name}/attestation.json](https://minimal.dev/api/pkgs/jq/attestation.json): build provenance per architecture (amd64, arm64) for the artifact the latest commit ships — artifact sha256, whether a signed attestation (DSSE / in-toto / SLSA provenance v1 format) exists, builder, source commit, run id, resolved dependencies, and per-signature check results; floats with the latest commit
- [/api/pkgs/bundle/{sha}/{name}/attestation.json](https://minimal.dev/api/pkgs/bundle/{sha}/{name}/attestation.json): the same build provenance for what a given commit shipped; sha-pinned, REQUIRES A SIGNED-IN SESSION (401 without one), private/no-store
- [/api/pkgs/bundle/{sha}/{name}/sbom.json](https://minimal.dev/api/pkgs/bundle/{sha}/{name}/sbom.json): same SBOM pinned to a commit for reproducible point-in-time output; sha-pinned, REQUIRES A SIGNED-IN SESSION (401 without one), private/no-store
- [/api/pkgs/bundle/{sha}/{name}/versions.json](https://minimal.dev/api/pkgs/bundle/{sha}/{name}/versions.json): version-history timeline for a package at a commit; sha-pinned, REQUIRES A SIGNED-IN SESSION (401 without one), private/no-store
- [/api/pkgs/bundle/{sha}/{name}/deps.json](https://minimal.dev/api/pkgs/bundle/{sha}/{name}/deps.json): direct dependencies with version, license, and advisory rollup at a commit; sha-pinned, REQUIRES A SIGNED-IN SESSION (401 without one), private/no-store
- [/api/pkgs/{name}/badge.svg](https://minimal.dev/api/pkgs/jq/badge.svg): shields-style SVG badge for the package's OpenSSF Scorecard score (append ?metric=advisories for the active-advisory count); floats with the latest commit
- [/api/pkgs/recent-commits.json](https://minimal.dev/api/pkgs/recent-commits.json): recent commits on gominimal/pkgs:main with subjects; floats with the live tip
- [/api/pkgs/bundle/{sha}/diff/{base}.json](https://minimal.dev/api/pkgs/bundle/{sha}/diff/{base}.json): catalog diff from base (older) to sha (newer) — packages added/removed, upgrades, advisory deltas; pair-addressed, REQUIRES A SIGNED-IN SESSION (401 without one), private/no-store
- [/api/pkgs/openapi.json](https://minimal.dev/api/pkgs/openapi.json): OpenAPI 3.1 description of every endpoint above, schemas generated from the served wire shapes

## MCP server

- [/api/mcp](https://minimal.dev/api/mcp): hosted Model Context Protocol server (streamable HTTP, anonymous, read-only) exposing the catalog as typed tools — search_packages, get_package, get_package_versions, get_advisories, get_dependencies, get_sbom, get_attestation, list_catalog_commits, diff_catalog. Attach with `claude mcp add --transport http minimal-pkgs https://minimal.dev/api/mcp`, or point any MCP client at the URL. Tool results delegate to the JSON API above, so they carry the same schemas. diff_catalog and any call passing a sha require authentication this server cannot present, and return an error result.

## Feeds

- [/pkgs/advisories.xml](https://minimal.dev/pkgs/advisories.xml): Atom feed of security advisories across the catalog, newest first; floats with the latest commit