Minimal

容器化开发环境
隔离、可复现的开发沙箱和安全的包管理器，为您的整个团队提供一致的环境，同时让 AI agents 远离本地笔记本电脑。

文档 · 快速入门 · Loadouts · 架构 · 讨论

## Minimal 是什么？ Minimal 是一个声明式的、基于内容寻址的构建系统和开发环境管理器。它可以重复构建基于 Linux 终端的开发沙箱，每个沙箱都根据项目的具体需求配置了相应的工具集和 agents，所有这些都声明在一个单独的 `minimal.toml` 蓝图中。沙箱在 Linux 上通过非特权用户命名空间原生运行，在 macOS 上则运行在轻量级的 libkrun microVM 内，因此相同的环境可以在团队成员的各种机器上无缝迁移。将此蓝图提交到您的代码仓库后，每位团队成员都能获得一个完全一致的环境，该环境将 AI agents 封闭在沙箱内部，使其远离宿主机笔记本电脑。 沙箱内部的可执行文件（如 git、claude-code、编译器、shell 等）由 Minimal 安全的包管理器从每日更新的精选 registry 中分发。由于包是通过内容而非易变的版本标签进行寻址，且构建过程是密封的，因此相同的蓝图在每台机器上都能解析出完全相同的环境。将整个团队迁移到最新工具版本只需执行一次 `min update`，该命令会在原地重新固定蓝图。不再需要过时的配置指南，不再出现版本漂移。 然后，每位开发者的 Loadouts 会在共享工具链的基础上，叠加他们各自偏好的编辑器、终端多路复用器和配置，从而确保所有人的环境保持一致，同时让您保留已经养成的操作习惯。

## 支持的平台 Minimal 可以运行在： - ARM64 架构的 macOS (Apple Silicon) - ARM64 和 x86_64 架构的 Ubuntu 和 Debian Linux，且要求 Linux 内核版本 >= 5.10。对于非 VM 使用场景，必须启用无根（Rootless）用户命名空间创建功能。 目前还不支持上述平台？请在[讨论区](https://github.com/gominimal/minimal/discussions)告诉我们您希望支持的平台。这有助于我们确定开发的优先级。 ## 安装说明 开始之前，请使用以下 shell 命令安装 Minimal： ``` curl --proto "=https" --tlsv1.2 -fsSL 'https://go.minimal.dev/' | sh ``` 此操作将安装稳定版的 Minimal，将 `min` 添加到您的 PATH 中，并为 bash、fish 和 zsh 设置 shell 自动补全。 您可以通过以下命令卸载 Minimal： ``` curl --proto "=https" --tlsv1.2 -fsSL 'https://go.minimal.dev/' | sh -s -- --uninstall ``` ## 快速入门 下面的示例展示了两种最常见的工作流程：在沙箱中启动一个全新的项目，以及加入一个已经有 `minimal.toml` 的现有项目。 ### 使用 Minimal 创建新项目 在此示例中，我们将在 Minimal 沙箱内使用 [Minimal 公共 Registry](https://github.com/gominimal/pkgs/) 提供的工具创建一个新的 git 仓库。该工作流使 agent 免于处理凭证：它使用存储在 macOS keychain 中的细粒度 GitHub 个人访问令牌（PAT），并仅在 agent 退出后才向沙箱展示该令牌。 首先创建一个新的空 GitHub 仓库，然后在 针对该仓库创建一个细粒度的 PAT。使用 `security add-generic-password -s "PAT-foo-repo" -a "my-mac-user-name" -w` 命令将 PAT 存储在您的 keychain 中。 以下展示了如何在沙箱内部填充该仓库的内容： ``` mkdir -p ~/projects/foo cd ~/projects/foo # 创建并更新 minimal.toml 文件 min init min add --session git gh claude-code mermaid-cli kittyview less emacs # 从您的 macOS keychain 复制 GitHub PAT 到剪贴板 security find-generic-password -w -s "PAT-foo-repo" -a "my-mac-user-name" | pbcopy # 启动并进入 sandbox；当前目录的文件树已被复制进去 min session activate --attach . git init # 开发 specs、生成代码等 —— 在这里跳过权限提示是 # 合理的：agent 被封存在 sandbox 中且没有任何 credentials； # agents 可以使用 "min add" 从 registry 添加 build/runtime dependencies claude --dangerously-skip-permissions # 在提交前审查生成的代码 git add -A git commit -m "initial commit" # 现在 AI agent 已经退出，添加 GitHub credential read -sp "paste GitHub PAT now: " GH_TOKEN && export GH_TOKEN # 推送到 github git remote add origin https://github.com//.git git branch -M main git push -u origin main exit ``` ### 在 Minimal 沙箱中开发现有项目 在此示例中，我们将开发一个已经有 `minimal.toml` 的现有 git 仓库，复用上一个示例中存储在 keychain 中的 GitHub PAT，以便 Claude 可以拉取仓库并发起一个 PR。 ``` cd ~/projects/foo # 获取当前分支上的最新文件；我们需要 minimal.toml git pull # 从您的 macOS keychain 复制 GitHub PAT 到剪贴板 security find-generic-password -w -s "PAT-foo-repo" -a "my-mac-user-name" | pbcopy # 不要复制任何文件上去；我们将在 sandbox 内执行 git pull min session activate --attach --sync none . # 注意：导出的 GH_TOKEN 在此 session 中对 Claude 可见 read -sp "paste GitHub PAT now: " GH_TOKEN && export GH_TOKEN # 告诉 claude 去 pull https://github.com//.git # 然后添加新功能、修复 bug 等。 # 然后要求 claude 创建一个 PR claude exit ``` ### 添加包含您首选工具和配置的 Minimal Loadout 项目的 `minimal.toml` 描述了每位贡献者的会话所需的内容；而 **loadout** 则承载了*您*个人希望在基础之上叠加的内容：您的编辑器、终端多路复用器、shell 配置和 dotfiles。Loadouts 是位于 `~/.config/minimal/loadouts/` 目录下的单个 TOML 文件： ``` # ~/.config/minimal/loadouts/dev.toml name = "dev" description = "helix + zellij with my dotfiles" packages = ["helix", "zellij"] patches = [ # Helix: single config files plus a themes directory. { dest = ".config/helix/config.toml", source = "~/dotfiles/helix/config.toml" }, { dest = ".config/helix/languages.toml", source = "~/dotfiles/helix/languages.toml" }, { dest = ".config/helix/themes/", source = "~/dotfiles/helix/themes/**/*.toml" }, # Zellij: single config file plus a layouts directory. { dest = ".config/zellij/config.kdl", source = "~/dotfiles/zellij/config.kdl" }, { dest = ".config/zellij/layouts/", source = "~/dotfiles/zellij/layouts/**/*.kdl" }, ] [vars] EDITOR = "hx" VISUAL = "hx" # 声明以在 session 启动时预热 helix 的 tree-sitter grammar cache。 # 尽力而为；失败不会导致 activation 崩溃。 [[lifecycle_hooks]] on_activate = { type = "inline", value = "hx --grammar fetch >/dev/null 2>&1 || true" } ``` 使用 `min session activate --loadout dev --attach .` 命令应用配置，或者在 `~/.config/minimal/config.toml` 文件中 `[loadouts]` 下的 `default_loadouts` 里列出它，以便让其自动加入每一个会话。执行 `min loadout list` 可查看可用列表。完整的 schema（文件补丁、生命周期 hooks、环境变量继承、组合规则）详见 [loadouts 参考](docs/reference/loadouts.md)。 ## 技术栈 沙箱：纯 Rust 编写的客户端、daemon 和 VM 管理器。沙箱 VM 由 [libkrun](https://github.com/libkrun/libkrun)、定制的 Linux 内核镜像以及 Alpine Linux rootfs 驱动。 [包](https://github.com/gominimal/pkgs/)：在 Minimal 的构建服务器上频繁地基于其官方源（GNU、GitHub、GitLab 等）构建的基于 glibc 的包。 ## 文档 - [架构概述](docs/architecture.md)：各个 crate 如何协同工作 - [CLI 参考](docs/reference/cli.md)：包含每一个 `min` 命令 - [`minimal.toml` 参考](docs/reference/minimal-dot-toml.md)：项目蓝图格式 - [Linux 宿主机配置](docs/reference/linux-host-setup.md)：内核和命名空间要求 - 更多指南请查阅 [docs/](docs/) ## 构建与测试 Minimal 是一个 Cargo workspace，使用 `just` 脚本是构建和测试它最简单的方式：它们会为您应用正确的基于操作系统的范围。这在 macOS 上尤为重要，因为目前还无法构建整个 workspace（`minimald` 的沙箱技术栈仅支持 Linux），因此这些脚本只会限定构建支持的部分。 ``` just ci # the full pre-PR gate: fmt, clippy, cargo-deny, tests, doctests just test # run the test suite just clippy # lint ``` `just --list` 会列出所有的脚本（构建、VM 启动、e2e 测试等）。在 Linux 上，您也可以直接针对整个 workspace 运行 Cargo 命令（`cargo build`、`cargo test`）；在 macOS 上建议优先使用这些脚本，这样您就无需手动限定 crate 的范围。构建生成的二进制文件会输出到 `target/debug/{min,mip,minimald,minvmd}`（或 `target/release/`）。构建整个包 registry 的资源消耗较大：建议使用 8 核及至少 16 GB 内存的配置。请查阅 [AGENTS.md](AGENTS.md#platform-matrix) 了解平台矩阵。 ### Ubuntu 24.04+ 宿主机 会话运行在非特权用户命名空间中，而 Ubuntu 24.04 默认阻止了此操作（`kernel.apparmor_restrict_unprivileged_userns=1`），因此每个会话都会在执行到 `uid_map` 时因为 `Operation not permitted`（操作不允许）而终止。请安装授予 `minimald` `userns` 权限的 AppArmor 配置文件： ``` $> sudo scripts/install-apparmor-profile.sh # installed binary $> sudo scripts/install-apparmor-profile.sh --path "$PWD/target/debug/minimald" # dev build ``` 如果是通过 `curl … | sh` 而非克隆代码库安装的？安装程序会自带此加载器，并在宿主机需要它时给出提示；请运行 `sudo bash ~/.local/share/minimal/apparmor/install-apparmor-profile.sh`。 详见 [docs/reference/linux-host-setup.md](docs/reference/linux-host-setup.md)。 ## 安全性 如果您认为自己发现了安全漏洞，请发邮件至 **security@minimal.dev**，而不是发布公开的 issue。我们非常感谢负责任的漏洞披露，并将迅速给您回复。 ## 开源协议 本项目基于 [Apache License Version 2.0](LICENSE) 获得许可。详情请参阅 [LICENSE](LICENSE) 文件。

标签：NIDS, Python安全, Rust, 包管理器, 可视化界面, 容器化, 开发环境管理, 构建系统, 沙箱隔离, 统一API, 网络流量审计, 通知系统