flar

FLAR 是 Fast Light Agent Restrictor（快速轻量级代理限制器）。它运行在一种叫做 gars 的岩石上。

它是一个用 Go 编写的简单轻量级 CLI 工具，用于在隔离的 Bubblewrap (bwrap) 沙箱 中安全运行编码代理 CLI（例如 Claude Code、Antigravity、Codex、Copilot 和 Reasonix）。

其目的是即时且无需复杂配置地 bubblewrap 一个 AI 代理，使其只能访问你正在处理的项目。这样可以防止提示注入以及代理可能未经充分审查（或只是运气不好）就引入项目中的库的供应链问题。唯一可访问的敏感信息是代理自身的认证详情和该项目的聊天历史。

大多数代理都有“沙箱”功能，但它相当多孔，代理本身可以扩大可访问的范围。当然，供应链漏洞不受代理沙箱限制。flar 完全不受代理影响，并且严格限制了供应链攻击的爆炸半径。

Bubblewrap 经过充分测试并且积极维护。它被 Flatpack 和许多其他项目用于轻量级容器。flar 的测试远不够充分，我只用了几天而已。

特性

• Bubblewrap 沙箱：使用干净根目录（tmpfs）在无特权的用户命名空间中运行代理。系统路径（/usr、/bin、/lib、/lib64 等）从主机只读挂载，确保主机软件包立即可用，无需管理容器镜像。
• 严格文件系统隔离：仅将目标项目目录以读写方式绑定挂载。主机的其余主目录被隐藏，保护 SSH 密钥、shell 配置和个人文件免受提示注入攻击。
• 网络沙箱：
  • 隔离模式（默认）：网络命名空间被解除共享。互联网访问通过主机侧的 HTTP/HTTPS 代理进行隧道传输，该代理在主机上执行 DNS 查找并过滤发往本地/回环 IP 地址的流量。
  • 端口转发：通过将特定端口映射到主机的 localhost，有选择地将本地服务（例如数据库、llama.cpp 模型）暴露到沙箱中。
  • 主机模式：可选共享主机的网络命名空间以实现无限制访问。
• 危险绕过选项：自动注入标志（例如为 Claude/agy 注入 --dangerously-skip-permissions，为 Codex 注入 --dangerously-bypass-approvals-and-sandbox），使代理无需运行时审批中断即可运行。可使用 -ask 禁用。
• 配置复制：自动将主机凭据（如 ~/.claude/、~/.codex/、~/.gemini/ 或 GitHub CLI 配置）复制到沙箱主目录内的临时目录，而不触碰主机配置文件。
• 会话持久化与恢复：当合理安全时（目前是 Claude Code 和 Reasonix），在沙箱内启动的会话会被写回主机，因此 --resume/--continue 可跨运行工作——作用域限定为当前项目，因此没有其他项目的历史记录进入沙箱。否则，对于给定代理和项目，历史记录在首次运行 flar 时会分叉。参见 Session persistence & resume。
• 密钥环桥接（agy）：Antigravity CLI 将其 OAuth 令牌存储在操作系统密钥环中而非文件中。flar 仅提取该单个密钥，并通过一个私有的进程内 Secret Service 在沙箱内提供它——这样代理可以认证而不会暴露你密钥环的其余部分。参见 Credentials。

构建与安装

依赖

确保你的主机系统上已安装 bwrap（Bubblewrap）：

# On Fedora/RHEL
sudo dnf install bubblewrap

# On Debian/Ubuntu
sudo apt install bubblewrap

编译与安装

从源码构建 flar：

go build -o `flar` .

安装：

mv `flar` ~/.local/bin/

用法

在你的项目文件夹中运行 flar，或指定路径：

flar [flags] [path/to/project] [extra agent args/prompts...]

标志

• -m：指定要运行代理（claude、codex、agy、copilot、reasonix）。默认检查可用的主机配置或环境变量。
• -ask：不跳过权限/审批（强制代理请求权限）。
• -network：网络模式：isolated（默认）或 host。
• -allow-port：允许通过隔离网络沙箱的特定本地 TCP 端口（例如 8080、11434）。可多次指定。
• -v：启用详细日志。

配置文件（.flar.json）

你可以为每个项目在 <project>/.flar.json 或全局在 ~/.config/flar/config.json 中配置选项：

{
  "agent": "claude",
  "ask": false,
  "network": "isolated",
  "allow_ports": [5432, 11434]
}

凭据

因为只挂载了配置的临时副本，代理使用你现有的主机会话进行认证，而不触碰原始文件。大多数代理将会话保存在 flar 直接复制的文件中：

• Claude：~/.claude/（包括 .credentials.json）以及 ~/.claude.json，这是存储引导状态和账户身份的最高层文件。两者都需要；仅凭凭据，Claude 会将沙箱视为全新安装并提示登录。
• Codex / Copilot：~/.codex/、~/.copilot/ 以及 GitHub CLI 配置。

Antigravity（agy）密钥环

agy 是个例外：它不将令牌存储在文件中。它将其保存在操作系统密钥环中，通过 freedesktop Secret Service API 经过 D-Bus 会话总线读取。沙箱没有会话总线，因此简单的设置会失败并显示 authentication failed or timed out。

flar 对此进行了特殊处理：

1. 在主机上，它使用 secret-tool 提取仅 agy 令牌（密钥环项 service=gemini, username=antigravity），并将其写入临时配置目录中的一个 0600 文件。
2. 在沙箱内部，它在一个私有 Unix 套接字上运行一个极简的、自包含的 Secret Service（flar --internal-secretsvc），由 DBUS_SESSION_BUS_ADDRESS 指向。它仅提供该单个令牌，别无其他。

代理只能访问其自身的令牌——而不是你密钥环的其余部分（浏览器密码、其他应用的密钥等）。该实现直接使用 D-Bus 线路协议，因此沙箱内无需 gnome-keyring 或 dbus-daemon。

要求和注意事项：

• 主机端提取需要主机上安装 secret-tool（libsecret）。如果缺失或未找到令牌，flar 会跳过桥接，agy 回退到正常的登录提示。
• 任何经过认证的代理，根据定义，都可以读取其自身的令牌；提示注入攻击可能将其泄露。这是运行已认证代理固有的风险。密钥环桥接将暴露范围限制为该单个令牌，而非整个密钥环。

会话持久化与恢复

因为沙箱挂载的是配置的临时副本，代理写入的任何内容通常会在退出时消失——包括它刚刚进行的对话。flar 将每个代理的对话存储绑定回主机，以便会话持久化并可在以后恢复，同时防止其他项目的历史记录进入沙箱。

• Claude：对话存储在每个项目的目录（~/.claude/projects/<project-slug>/）中。flar 仅将当前项目的目录从主机绑定到复制的配置上，因此 claude --resume 只能看到该项目中的会话，而看不到其他。请注意，这意味着存储在历史记录中的提示注入可能仍然存在风险；如果你恢复了一个包含有效提示注入的会话，并且在 flar 之外运行 claude，爆炸半径会无限扩大。我认为便利性大于风险；对于任何具有此类风险的项目，只需始终在 flar 中运行它。

• Codex CLI：Codex 将会话存储在 ~/.codex/sessions/ 下按日期划分的目录中，并在全局 state_5.sqlite 中建立索引；两者都记录每个线程的 cwd，但磁盘上的目录混合了不同项目。flar 为每个工作区提供一个影子 Codex 主目录，位于 $XDG_STATE_HOME/flar/codex/<project-slug>/ 下，当该变量未设置时回退到 ~/.local/state/flar/codex/<project-slug>/。首次使用时，它仅用匹配的对话文件、SQLite 行和提示历史记录来填充该影子主目录。然后影子主目录作为 ~/.codex 挂载，因此新会话持久化而不将其他项目暴露给 。

~/.copilot/.flar/<project-slug>/

首次使用时，flar 仅用存储的 cwd 匹配当前工作区的会话填充该影子主目录，复制相关的 SQLite 行以及匹配的 session-state/ 目录。之后，整个影子主目录作为 ~/.copilot 绑定挂载到沙箱内部，因此 copilot --continue 可以仅恢复该工作区的会话，而新会话安全地持久化在那里。

• Antigravity（agy）：与 Copilot 类似，flar 首次在项目中使用时会将会话“分叉”，并且不再与 flar 外部运行的 agy 共享会话。

agy 不会按项目在磁盘上分隔对话。每个项目的所有对话都位于 ~/.gemini/antigravity-cli/ 中的一个扁平存储中（conversations/、brain/、implicit/），仅由 UUID 索引，所属工作区记录在不透明的对话 blob 中。一个近期索引（cache/last_conversations.json）将每个工作区映射到最近对话，这就是 agy --continue 所跟踪的。

如果将那个存储按原样绑定到沙箱中，沙箱中的 agy 可以通过 --continue、交互式选择器或显式 --conversation <ID> 恢复属于不同项目的对话，从而泄露粘贴到其中的任何内容。为防止这种情况，flar 为每个工作区提供一个作用域存储：

~/.gemini/antigravity-cli/.flar/<project-slug>/

该目录作为 conversations/、brain/、implicit/、history.jsonl 和 cache/last_conversations.json 绑定挂载到沙箱内部。因此在项目 A 上打开的沙箱只能看到项目 A 的对话。新会话累积在作用域存储中，并可在下次运行时恢复。

第一次在项目中使用 flar 运行 agy 时，flar 会从你现有的主机历史记录中填充该项目的作用域存储——但仅限 agy 自身归因于此工作区的对话（根据明文 last_conversations.json 和 history.jsonl 确定，绝不通过解析对话 blob）。在该一次性播种之后，作用域存储独立存在：新会话仅存在于作用域存储中，主机端后续的更改不会被拉入。

• Reasonix：与 Claude Code 相同。Reasonix 将每个项目的历史记录保存在自己的子目录中，因此可以像 Claude Code 一样以相同方式绑定挂载，并具有相同的注意事项。

需要注意的后果：

• Copilot CLI：与 agy 类似，作用域影子主目录在初始播种后成为一个独立的、按项目划分的世界。你在 flar 外部使用 Copilot 启动的会话不会后来被拉入 flar，而你在 flar 内部启动的会话会保存回作用域影子主目录，而非主机的全局 Copilot 存储。
• 你在 flar 外部使用 agy 启动的会话（除初始播种外）在 flar 内部不可见，反之亦然。这是有意为之——flar 的 agy 历史记录是一个独立的、按项目划分的世界。
• Codex 遵循相同规则：在一次性播种后，包装和未包装的 Codex 历史记录是独立的。
• agy 自身的索引从未归因于当前工作区的对话不会被播种，这是设计如此。安全的默认做法是不提供它，而不是冒险暴露其他项目的数据。
• 代理拥有的 .flar/ 目录因兼容性原因被排除在配置复制之外，而 flar 拥有的状态位于 $XDG_STATE_HOME/flar/（或 ~/.local/state/flar/），位于代理管理的配置目录之外。

网络安全与本地端口

在隔离网络模式下，代理的环境无法直接访问主机网络接口。

• 互联网访问：通过 HTTP_PROXY 和 HTTPS_PROXY 环境变量自动处理 HTTP/HTTPS 请求（例如连接到 Anthropic 或 Gemini 等云 LLM）。
• 本地主机限制：通过代理发往 localhost 或回环 IP 的请求被阻止。
• 暴露本地服务：要让代理访问本地数据库或本地 LLM（例如 127.0.0.1:11434 上的 Ollama），使用 -allow-port 11434 或 allow_ports 配置指定端口。一个安全的回环转发器会在沙箱内部绑定 127.0.0.1:11434 并将流量代理到主机。