仓库文件导航
isx
给你的 AI 编码代理一台属于它们自己的机器,而不是你的凭据。网站是 isx.run,完整文档也在那里。
终端里的 AI 代理能读取你的 API 密钥、你的 GitHub token、你的 ~/.ssh 以及你检出的每一个仓库。你的 IDE 和构建工具会执行代理写下的任何内容。
isx 接入代理的方式,就像你接入一位新同事:
- 一台真正属于它们自己的机器。每个代理获得一台完整的 Linux 工作站:自己的文件系统、init 系统、网络和进程树。它可以 dnf install、运行 Docker Compose、使用 strace 和嵌套容器,因为它是一个真实的系统,而不是一个应用容器。只需一个标志,就能让代理改用硬件隔离的 KVM 虚拟机,当你需要最强隔离时。
- 零凭据暴露。API 密钥和 token 不会以任何形式进入这台机器。你主机上的一个代理会在代理的请求离开机器时将它们加入请求,因此 claude、pi、gh、git 和 curl 在机器内无需修改即可工作。参见 Credential Isolation。
- 即时分支。像从仓库拉分支一样,从准备好的模板拉分支:即时写时复制克隆。用它、丢弃它、再从干净状态拉分支。
- 完全自主,无需监督。每个代理运行时没有权限提示,并以你指定的身份提交。它没有可泄露的凭据,它运行、安装或删除的东西都在它自己的机器里,而你可以随时丢弃这台机器。
每个代理都在自己的机器里工作,不请求任何批准,因此你可以并行运行许多代理,并构建无人值守运行的自动化。isx 运行在 Linux 和 macOS 上,在你的硬件上,你的仓库和凭据留在那里。
代理是主要用途,但不是唯一用途。同样的可丢弃机器非常适合分诊不可信补丁、复现 bug 报告以及在干净系统上测试。
用 Quarkus 和 Tamboui 构建,由 Incus 系统容器驱动。用 Java 编写,用 GraalVM 编译为原生二进制。isx 以前称为 incus-spawn。
快速开始
需要 Linux,或 macOS 15 (Sequoia) 或更高版本(安装);isx init 会设置其余部分,或者你的编码代理可以为你完成全部设置。
macOS
brew install Sanne/tap/incus-spawn
Fedora / RHEL
sudo dnf install -y 'dnf5-command(copr)' # on RHEL 9: 'dnf-command(copr)'
sudo dnf copr enable sanne/incus-spawn
sudo dnf install incus-spawn
Ubuntu / Debian
curl -fsSL https://sanne.github.io/isx-apt-releases/public.gpg | sudo gpg --yes --dearmor -o /usr/share/keyrings/incus-spawn.gpg
echo "deb [signed-by=/usr/share/keyrings/incus-spawn.gpg] https://sanne.github.io/isx-apt-releases stable main" | sudo tee /etc/apt/sources.list.d/incus-spawn.list
sudo apt update && sudo apt install incus-spawn
其他 Linux
curl -fsSL https://isx.run | sh
JBang
jbang app install isx@Sanne/incus-spawn
jbang app install isx-proxy@Sanne/incus-spawn
这个包名叫 incus-spawn,它会安装 isx 命令。
# One-time host setup (Incus, firewall, auth)
isx init
在全新的 Linux 主机上,isx init 会把你加入 incus-admin 组,并在该组中完成其运行。其他终端会在你下次登录时获得该组,或在每个终端中用 newgrp incus-admin 获得。
模板是你构建一次的机器镜像:一个操作系统、工具和仓库。下面的模板在内置的 tpl-minimal 模板上添加 Claude Code。将它保存为 ~/.config/incus-spawn/images/tpl-agent.yaml,或者运行 isx templates new tpl-agent 并将它粘贴到编辑器中打开的骨架之上:
name: tpl-agent
description: Claude Code on the base OS
parent: tpl-minimal
tools:
- claude
default-action: claude
# Build it (builds missing parent images first)
isx build tpl-agent
分支它:一台即时写时复制的独立机器,其中已打开 Claude Code
isx branch my-first --from tpl-agent
交互式 TUI:你的模板与分支
isx
Claude Code 使用你在 isx init 中设置的 Claude 凭据登录;之后可通过 isx account add claude 再添加一个。Claude Code 永远看不到该凭据:代理会在请求离开实例后,把凭据添加到每个请求中。如果你没有安装 isx init 提供的服务,请在构建前启动它们:在 Linux 上运行 isx proxy start,在 macOS 上运行 isx vm start && isx proxy start。
如需使用其他代理,请将 claude 替换为 codex、pi、opencode、gemini-cli、antigravity、bob 或 copilot;参见 Agents。Pi 和 opencode 也会使用你的 Claude 凭据,除非它们的 provider 指定了另一个 API(Pi、opencode)。要为代理提供一个项目,请添加 repos:(Declarative Repos)。其提交会通过 git fetch 回到你的主机(Git Remotes)。
凭据隔离
代理必须能够自由行动,因此其所在实例不能保有任何值得窃取的内容。API 密钥和令牌绝不会以任何形式进入实例。相反,你主机上的代理(isx proxy)会在代理的请求离开实例时,将真实凭据添加到这些请求中,因此 curl、git、gh、claude 和 pi 可以在实例内原样工作。
工作原理:
- 实例的 DNS 会将拦截的域名解析到代理,并且实例信任代理的证书颁发机构(CA),因此流量无需在工具中做任何设置即可到达代理。
- 代理会将工具发送的占位符凭据替换为真实凭据,并通过 TLS 将请求转发到上游。
- 在实例内部,工具只能看到类似 sk-ant-placeholder 的占位符。该占位符可以满足工具的本地检查,但没有任何服务会把它当作凭据接受。
- 实例内部没有任何东西能产出真实凭据:没有 API、没有端点、没有变量、没有文件。
代理能够以什么身份登录:
| 凭据 | 在实例中使用它的对象 | 你提供给 isx init 的内容 |
|---|---|---|
| Anthropic API key | Claude Code ( claude )、Pi ( pi )、opencode ( opencode ) | 该密钥 |
| Claude Pro or Max | Claude Code ( claude )、Pi ( pi )、opencode ( opencode ) | 来自 claude setup-token 的令牌;代理会添加 OAuth bearer token |
| Vertex AI | Claude Code ( claude )、Pi ( pi )、opencode ( opencode ) | 你的项目和区域;代理会转换每个请求,并使用主机的 GCP 凭据为其签名,这些凭据永远不会进入实例 |
| OpenAI API key | Codex CLI ( codex )、Pi ( pi )、opencode ( opencode ) | 该密钥 |
| Gemini API key | Gemini CLI ( gemini-cli )、Antigravity CLI ( antigravity )、Pi ( pi )、opencode ( opencode ) | 该密钥 |
| IBM API key | Bob Shell ( bob ) | 该密钥 |
| GitHub token | gh 、 git 、 GitHub Copilot CLI ( copilot ) | 该令牌 |
| Atlassian API token | the atlassian-mcp tool,用于 Jira 和 Confluence | 你的账户邮箱和该令牌 |
| A service of your own | 你的工具 YAML 所安装的任何内容 | 其凭据,在 YAML 的 proxy: 块中声明(Proxy Credentials) |
一个凭据可以有多个账户,例如个人和客户的 Claude 订阅,或两个 GitHub 身份。每个模板或实例会选择它使用哪个账户:参见 Credential accounts。Git 必须使用 HTTPS URL,而不是 SSH;gh 默认使用 HTTPS。
对于每个有网络的实例,代理都必须处于运行状态。isx init 会将其安装为服务,在 Linux 上是 systemd,在 macOS 上是 launchd;或者你也可以在独立终端中运行 isx proxy start。isx 会在构建、创建分支或启动 shell 之前检查代理是否可达且兼容。
代理还会在主机上缓存容器镜像层和构建产物,因此同一依赖永远不会被下载两次,并且各 registry 从你的地址看到的请求也会更少(Caching)。
凭据会到达登录环境
文章标题:用于自主 AI 代理的隔离 Linux 工作站
正文: 每次启动都会将占位符替换为该实例与凭据独有的证明令牌,例如由登录配置文件导出的 GH_TOKEN 中的 gho_isx_…。代理只将实例的凭据添加到携带其证明令牌的请求中。这些令牌在停止、启动和重启之间保持不变,因此你配置的嵌套服务可以继续正常工作。
只有在该实例的登录环境中运行的内容才会收到证明令牌,因此嵌套容器不会获得任何令牌,除非你传入一个。纯 Git 是例外:对于发往 github.com 的 HTTPS 请求,isx 安装的凭据助手即使不在登录 shell 中也会出示 GitHub 证明令牌。
Credential proofs 说明了如何共享或撤销证明令牌,以及升级后该怎么做。
Git 配置
配置了 GitHub 令牌后,每个实例都会获得一个现成的 .gitconfig:你的 GitHub 名称和电子邮件、有则使用的私有 @users.noreply.github.com 地址,以及合理的默认值。
- 专用代理账户(推荐):将单独的 GitHub 账户的令牌交给 isx init,这样代理的提交和 PR 就明确属于它自己。
- 你的个人账户:使用你自己的令牌。要在实例中使用你的别名和设置,请将 ~/.gitconfig 作为宿主机资源挂载;挂载的文件优先于生成的配置。
实例内尚不支持提交签名(#271)。要签名,请通过 git 远程将更改获取到宿主机并在那里变基。
分支
分支是从模板创建的实例,就像 git branch 从提交创建分支一样:一个即时的写时复制克隆。它有自己的文件系统,它所做的任何更改都不会到达模板或另一个分支。
存储后端(btrfs、zfs 或 lvm)共享未更改的数据,因此分支仅为其更改的内容使用磁盘空间。如果不存在 btrfs 存储池,isx init 会创建一个。
tpl-agent (stopped template, ~2GB) ├── fix-nasty-bug (running, uses ~50MB extra) ├── review-pr-423 (running, uses ~30MB extra) └── experiment (stopped, uses ~10MB extra)
安装软件包、搞坏东西,完成后销毁分支。Sudo 无需密码即可使用,shell 会将终端标题设置为 isx:<name>,因此你始终知道自己处于哪个实例中。
分支可以拥有的内容,按需提供:
- GUI 和音频直通:带 GPU 加速的 Wayland 和 PipeWire,仅限 Linux。
- 受限网络:参见网络模式。
- 收件箱:宿主机目录的只读挂载,用于向实例提供文件。
- 与其模板不同的其他凭据账户。
- CPU、内存和磁盘的资源限制,从宿主机检测并可覆盖。
TUI(不带参数运行 isx)是类似 Midnight Commander 风格的模板和分支视图。它有用于分支、重命名和构建的对话框,F3 查看实例详情,F9 用于工具操作。
没有功能键时,按数字代替:1 到 0 代表 F1 到 F10,Alt 加数字代表 Shift 加该功能键。在 macOS 上,一旦终端将 Option 作为 Meta 发送,Alt 就是 Option。
存储用量条和每行磁盘使用量显示什么在填充存储池。大小是近似值(~):基础模板携带共享的基础镜像,每个分支只携带自己的数据。按 C 回收空间,或在 macOS 上用 isx vm resize <size> 扩展磁盘。
模板预装你的基线工具和仓库。集成通过相同的工具系统安装:VS Code Remote、JetBrains Gateway 和代理技能。
网络模式
每个分支以三种网络模式之一运行:
| 模式 | 标志 | 含义 |
|---|---|---|
| 完整互联网 | (默认) | 通过 NAT 无限制访问,通过代理登录 |
| 仅代理 | --proxy-only | 出站流量仅到达代理;宿主机强制执行限制,因此实例中的 root 无法移除它 |
| 气隙 | --airgap | 完全没有网络设备,也没有 pci 或 usb 直通 |
Git 远程
用于自主 AI 代理的隔离 Linux 工作站
实例是隔离的,但在其中完成的工作必须传递到你的宿主机。isx 使用 git 的远程辅助协议,因此普通的 git fetch、git push 和 git pull 可以在宿主机仓库与实例中的仓库之间工作:
Inside the instance, the agent makes some commits...
Back on the host:
git fetch fix-auth git diff main..fix-auth/main # review exactly what it did git cherry-pick fix-auth/main # take what you like
这就是预期的审查工作流:你审查的代码就是你取用的代码,无论代理之后做什么。你操作的是已获取的提交,git 通过其内容的哈希来标识它们,而绝不是代理仍可更改的活动目录。FAQ 说明了为什么有意不提供读写的项目挂载。
### isx:// URL
远程使用 isx:// URL 方案,其中 ~ 展开为 /home/agentuser:
git remote add fix-auth isx://fix-auth/~/quarkus git fetch fix-auth git diff main..fix-auth/main
实例内的绝对路径跟在双斜杠之后,如 isx://fix-auth//home/agentuser/quarkus。实例必须处于运行状态,git 操作才能工作。
### 自动远程
在 ~/.config/incus-spawn/config.yaml 中配置 host-paths 后,isx 会为你管理远程:
Base directories where your repos live on the host
Subdirectories are scanned recursively (up to 4 levels deep),
so ~/projects finds ~/projects/java/my-repo, ~/projects/go/another-repo, etc.
If a repo name appears in multiple locations, the checkout whose remote matches is used;
add an explicit repo-paths entry when more than one matches
host-paths:
- ~/projects
- ~/workspace
Explicit overrides for repos in non-standard locations or to resolve ambiguity
repo-paths: quarkus: ~/work/quarkus hibernate: /opt/hibernate
isx branch 会为每个在实例中有匹配的宿主机仓库添加一个以实例命名的远程。同一仓库的 SSH 和 HTTPS URL 视为相同。isx destroy 会再次移除该远程。
## 模板
模板是你用 YAML 一次性准备的机器镜像:操作系统、包、工具和仓库。模板之间可以继承,构建一个模板时会先构建任何缺失的父模板:
name: tpl-maven description: JDK + Maven parent: tpl-minimal packages:
- java-25-openjdk-devel
tools:
- maven-3
tpl-minimal 基于 Fedora,是内置的。你自己的模板放在 ~/.config/incus-spawn/images/ 中,或项目的 .incus-spawn/images/ 中。isx templates new <name> 会打开一个列出所有字段的骨架,isx templates edit <name> 会验证你保存的内容。
isx build tpl-maven # builds missing parents first isx build tpl-maven --with-parents # rebuilds it and its parents from scratch isx build --out-of-sync # rebuilds what changed since it was built
Templates 列出了所有字段:构建时克隆的仓库、工作目录和默认操作、宿主机资源、基础镜像更新和 VM 模板。
代理
代理是模板 tools: 列表中的一个工具,为无人值守工作而设置。它通过代理使用你在 isx init 中配置的账户登录,该菜单将每个凭据列在拥有它的工具下,因此 Pi、opencode、Antigravity CLI 和 Copilot 没有自己的条目:
| 代理 | 工具 | 登录方式 |
|---|---|---|
| Claude Code | claude | Anthropic API key、Claude Pro/Max 或 Vertex AI |
| Codex CLI | codex | OpenAI API key |
| Pi | pi | Claude 的凭据、OpenAI key 或 Gemini key |
| opencode | opencode | Claude 的凭据、OpenAI key 或 Gemini key |
| Gemini CLI | gemini-cli | Gemini API key |
| Antigravity CLI | antigravity | Gemini API key |
| Bob Shell | bob | IBM API key |
| GitHub Copilot CLI | copilot | gh 使用的 GitHub token |
Agents 包含每个代理的参数(模型、推理强度、提供商)、代理技能,以及 isx 为代理编写的关于其实例的说明。
工具
文章标题:用于自主 AI agent 的隔离 Linux 工作站
正文: 模板由工具构成。gh、herdr、maven-3、orca、podman、sshd、VS Code 和 IntelliJ 远程后端、tmux 和 zmx 随 isx 一起提供;isx tools list -v 会列出全部工具。你自己的工具是位于 ~/.config/incus-spawn/tools/ 或项目的 .incus-spawn/tools/ 中的 YAML 文件:包、命令、环境变量、TUI 操作,以及代理为你的某个服务添加的凭据。参见 Tools。
通过 MCP 委派
你主机上的 agent(例如 Claude Code)可以通过 isx mcp 控制 isx:从你批准的模板分支出实例,在其中运行构建和测试,并把整个任务交给实例内的编码 agent。isx mcp 默认关闭,因为它把这种控制权交给 agent;isx init 会询问是否设置它。
从主机上的 agent 进行委派说明了这样的 agent 能做什么、不能做什么,以及如何把协调 agent 运行在它自己的实例中,并用 isx branch --mcp-client 分支出来。从程序驱动 isx mcp 是你自己编写的、用于控制 isx mcp 的程序的参考。
配置
isx init 会把你的设置和凭据写入 ~/.config/incus-spawn/config.yaml;你自己的模板和工具放在它旁边,位于 images/ 和 tools/ 中。一个凭据可以有多个账户,例如个人和客户的 Claude 订阅,每个模板或实例选择它使用哪个账户。配置涵盖文件、凭据账户和下载缓存。
安装
isx 运行于 Linux,以及 macOS 15 (Sequoia) 或更高版本。不支持 Windows。
Linux:isx init 使用你的包管理器安装 Incus。当主机既没有 firewalld 也没有 UFW 时,它还会安装并启用 firewalld,因为代理的重定向需要防火墙。
macOS:isx init 会配置一个轻量级 Linux VM,由 isx 自带的启动器 isx-vm 在需要时运行。isx vm start|stop|restart|status|resize|reset|console|check-version 管理该 VM,其参考文档说明了当 VM 停止响应时该怎么做。支持 Apple Silicon,不支持 Intel Mac:v0.4.2 和 v0.5.0-dev.2 是为它们构建的最后版本。
在 macOS 上,isx 只运行容器。以下仅限 Linux:
- VM 实例(type: vm、--type vm)和 KVM 直通(--kvm、type: kvm)。isx 在 macOS 上会在创建任何东西之前拒绝它们,并且分支 type: kvm 模板时不带 KVM。
- GUI 和音频直通(Wayland 和 PipeWire)。
- 主机资源的 overlay 模式:改用 readonly 或 copy。
在 TLS 检查(重新签名 HTTPS 的企业代理)之后,isx 会为自身下载和代理的上游连接信任主机的 CA 存储。
- 在 Linux 上,这是系统证书包:/etc/pki/ca-trust、/etc/ssl/certs。
- 在 macOS 上,这是 /etc/ssl/cert.pem 加上管理员或 MDM 在系统钥匙串中为 SSL 信任的每个证书,检查 agent 正是在那里安装其 CA。管理员在那里拒绝的证书,或你在登录钥匙串中标记为“Never Trust”的证书,都不会从任何来源被信任,包含它的链或交叉签名副本也不会被信任。
- 仅在登录钥匙串中被信任的 CA 不会被使用,因为 isx 把信任哪些 CA 的选择留给管理员。请在全系统范围内信任它,然后重启代理:
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain ca.pem isx proxy restart
isx doctor 会列出 isx 信任的钥匙串 CA。
| 安装方式(快速开始) | 更新方式 |
|---|---|
| Homebrew | brew upgrade incus-spawn |
| DNF:Fedora 43 及更高版本、RHEL 9 和 10、CentOS Stream 9、AlmaLinux 9、Rocky Linux 9(通过 EPEL) | sudo dnf upgrade |
| APT | sudo apt upgrade |
| curl -fsSL https://isx.run │ sh | 再次执行同一命令 |
| JBang | 再次执行两条 jbang app install 命令 |
curl 脚本会把 isx 和 isx-proxy 原生二进制文件安装到 ~/.local/bin(设置 INSTALL_DIR 可更改位置),无需 JVM,并且只有在每个下载都与该版本的 SHA256SUMS 匹配后才会安装。JBang 安装需要两条命令,并且 jbang 必须保持在你的 PATH 中。
文章标题:为自主 AI 代理准备的隔离 Linux 工作站
正文: 源码构建(在检出目录中运行 ./install.sh)不会改变 Homebrew 安装,因为其他账户可能在使用它,所以你的 PATH 中排在前面的那个 isx,就是你和你的代理服务所运行的那一个。
要卸载,请运行 uninstall.sh:
- 除非传入 --purge,否则它会将你的配置保留在 ~/.config/incus-spawn/ 中,并将缓存保留在 ~/.cache/incus-spawn/ 中。
- 在 macOS 上,除非传入 --delete-instances,否则它会保留 VM 的数据磁盘,其中包含每个实例和模板。
- --binaries-only 只移除二进制文件,用于切换安装渠道,例如从源码构建切换到 Homebrew。
可通过 isx completion <shell> 获得 bash、zsh、fish 和 PowerShell 的 Shell 补全。
使用 vfkit 运行过 isx 虚拟机的 Mac 需要重启一次虚拟机:请参阅 FAQ。
CLI
| Command | Description |
|---|---|
| isx | 启动交互式 TUI |
| isx init | 一次性主机设置 |
| isx build | 构建或重建模板镜像 |
| isx branch | 从模板或实例创建 CoW 克隆 |
| isx shell | 在实例中打开 shell |
| isx start | 启动实例而不打开 shell |
| isx stop | 停止正在运行的实例 |
| isx purpose | 显示或更改实例的用途 |
| isx run | 在实例上运行操作 |
| isx destroy | 销毁实例 |
| isx list | 列出实例,供人阅读或供脚本使用 |
| isx overview | 显示每个实例中完成了什么 |
| isx update-base | 检查并安装基础镜像更新 |
| isx update-all | 更新所有模板中的软件包和仓库 |
| isx templates | 管理模板定义 |
| isx tools | 列出并检查可用的工具定义 |
| isx account | 添加凭据,并显示或更改实例使用的账户 |
| isx project | 管理项目模板 |
| isx proxy | 管理 MITM 身份验证代理 |
| isx doctor | 运行健康检查并提供修复问题的选项 |
| isx clean | 移除缓存数据、状态或配置 |
| isx reset | 重置到干净状态 |
| isx vm | 管理 VM 设备(仅限 macOS) |
| isx ask | AI 驱动的帮助 |
| isx mcp | 通过 MCP 向本地代理提供 isx |
| isx completion | 打印 shell 补全脚本 |
使用 isx <command> --help 查看任何命令的详细选项。脚本读取 --format=plain 或 --format=json,这些格式保持稳定:请参阅 Scripting isx。
延伸阅读
- FAQ:Codex 中的 URL 点击、剪贴板,以及为什么没有读写项目挂载。
- 与其他沙盒的比较:为什么 isx 实例是一整台机器,以及 nono、Claude Code 的沙盒运行时、NVIDIA OpenShell、dev containers、Docker Sandboxes 和你自己管理的 VM 与它相比如何。
- 与标准 Fedora 安装的不同之处:少数刻意的偏差,主要是为了让每个运行时都信任代理的 CA。
- 愿景:isx 将走向何方,从容器管理器到并行编码代理的任务控制中心。
- DESIGN.md:架构以及每个选择背后的原因。