flar

FLAR — это Fast Light Agent Restrictor. Работает на камнях, называемых gars.

Это простой, легковесный CLI-инструмент на Go для запуска CLI-агентов кодирования (таких как Claude Code, Antigravity, Codex, Copilot и Reasonix) безопасно внутри изолированных песочниц Bubblewrap (bwrap).

Цель — мгновенно и без сложной конфигурации обернуть AI-агента в bubblewrap, чтобы он имел доступ только к тому проекту, над которым вы работаете. Это защищает от инъекций промптов, а также от проблем с цепочками поставок в библиотеках, которые агент может загрузить в ваш проект без достаточной проверки (или просто из-за невезения). Единственная доступная конфиденциальная информация — это собственные данные аутентификации агента и история чата для данного проекта.

У большинства агентов есть функция «песочницы», но она довольно пористая, и сам агент может расширить область доступного. И, конечно, уязвимости цепочки поставок не подчиняются песочнице агента. flar полностью непроницаем для агента, а радиус поражения атак на цепочку поставок жёстко ограничен.

Bubblewrap крайне хорошо протестирован и активно поддерживается. Он используется в Flatpack и многих других проектах для лёгких контейнеров. flar гораздо менее протестирован и используется мной в течение пары дней.

Возможности

• Песочница Bubblewrap: Запускает агента в непривилегированном пространстве имён пользователя, используя чистый корневой каталог (tmpfs). Системные пути (/usr, /bin, /lib, /lib64 и т. д.) монтируются только для чтения с хоста, что обеспечивает немедленную доступность пакетов хоста без управления образами контейнеров.
• Строгая изоляция файловой системы: Только целевая директория проекта монтируется с правами чтения-записи. Остальная часть домашней директории хоста скрыта, что защищает ssh-ключи, конфигурации оболочки и личные файлы от атак внедрения промптов.
• Изоляция сети:
  • Изолированный режим (по умолчанию): Пространство имён сети разъединено. Доступ в Интернет туннелируется через HTTP/HTTPS-прокси на стороне хоста, который выполняет DNS-запрос на хосте и фильтрует трафик к локальным/петлевым IP-адресам.
  • Переадресация портов: Выборочно открывайте локальные службы (например, базы данных, модели llama.cpp) в песочницу, сопоставляя определённые порты с localhost хоста.
  • Хост-режим: Опция для совместного использования сетевого пространства имён хоста для неограниченного доступа.
• Опасные опции обхода: Автоматически вставляет флаги (например, --dangerously-skip-permissions для Claude/agy или --dangerously-bypass-approvals-and-sandbox для Codex), чтобы агенты работали без прерываний на утверждение во время выполнения. Можно отключить с помощью -ask.
• Копирование конфигурации: Автоматически копирует учётные данные хоста (например, ~/.claude/, ~/.codex/, ~/.gemini/ или конфигурации GitHub CLI) во временную директорию, смонтированную внутри домашней директории песочницы, не затрагивая файлы конфигурации хоста.
• Сохранение и возобновление сеансов: Когда это достаточно безопасно (в настоящее время для Claude Code и Reasonix) разговоры, начатые внутри песочницы, записываются обратно на хост, так что --resume/--continue работает при повторных запусках — с областью действия только для текущего проекта, чтобы никакая история другого проекта не попадала в песочницу. В противном случае история разветвляется при первом запуске flar для данного агента и проекта. См. Сохранение и возобновление сеансов.
• Мост к связке ключей (agy): CLI Antigravity хранит свой OAuth-токен в связке ключей ОС, а не в файле. flar извлекает только этот один секрет и обслуживает его внутри песочницы через частную, внутрипроцессную службу Secret Service — так что агент аутентифицируется, не раскрывая остальную часть вашей связки ключей. См. Учётные данные.

Сборка и установка

Зависимости

Убедитесь, что bwrap (Bubblewrap) установлен на вашей хост-системе:

# На Fedora/RHEL
sudo dnf install bubblewrap

# На 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. На хосте он извлекает только токен agy (элемент связки ключей service=gemini, username=antigravity) с помощью secret-tool и записывает его в файл с правами 0600 во временную директорию конфигурации.
2. Внутри песочницы он запускает минимальный, самодостаточный Secret Service (flar --internal-secretsvc) на частном Unix-сокете, на который указывает DBUS_SESSION_BUS_ADDRESS. Он обслуживает только этот один токен и ничего больше.

Агент может получить доступ ровно к своему собственному токену — а не к остальной части вашей связки ключей (пароли браузера, секреты других приложений и т. д.). Реализация напрямую использует проводной протокол D-Bus, поэтому ей не нужны gnome-keyring или dbus-daemon внутри песочницы.

Требования и оговорки:

• Для извлечения на стороне хоста требуется secret-tool (libsecret), установленный на хосте. Если он отсутствует или токен не найден, flar пропускает мост, и agy возвращается к обычному запросу входа.
• Любой аутентифицированный агент по определению может прочитать свой собственный токен; атака с внедрением промпта может его извлечь. Это присуще работе с аутентификацией в целом. Мост связки ключей ограничивает раскрытие только этим одним токеном, а не всей вашей связкой.

Сохранение и возобновление сеансов

Поскольку песочница монтирует временную копию вашей конфигурации, всё, что агент туда записывает, обычно исчезает при выходе — включая только что состоявшийся разговор. flar привязывает хранилище транскриптов каждого агента обратно к хосту, чтобы сеансы сохранялись и могли быть возобновлены позже, не допуская попадания истории других проектов в песочницу.

• Claude: транскрипты хранятся в директории для каждого проекта (~/.claude/projects/<project-slug>/). flar монтирует только директорию текущего проекта с хоста поверх скопированной конфигурации, так что claude --resume видит сеансы этого проекта и ничего больше. Учтите, что это означает, что инъекция промпта, сохранённая в истории, всё ещё может представлять риск: если вы возобновите сеанс, содержащий работающую инъекцию промпта, радиус поражения становится бесконечно больше, если вы запустите claude вне flar. Я считаю, что удобство перевешивает риск; для проектов, подверженных такому риску, просто всегда запускайте их в flar.

• Codex CLI: Codex хранит транскрипты в директориях с датами внутри ~/.codex/sessions/ и индексирует их в глобальном state_5.sqlite; оба записывают cwd каждого треда, но директории на диске смешивают проекты. flar выдаёт каждому рабочему пространству теневой домашний каталог Codex в $XDG_STATE_HOME/flar/codex/<project-slug>/, откатываясь к , если эта переменная не установлена. При первом использовании он заполняет этот теневой домашний каталог только соответствующими файлами транскриптов, строками SQLite и записями истории промптов. Затем теневой домашний каталог монтируется как , так что новые сеансы сохраняются, не раскрывая другой проект для .

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

При первом использовании flar заполняет этот теневой домашний каталог только теми сеансами, чей сохранённый cwd соответствует текущему рабочему пространству, копируя как соответствующие строки SQLite, так и соответствующие директории session-state/. После этого весь теневой домашний каталог монтируется как ~/.copilot внутри песочницы, так что copilot --continue может возобновить только сеансы этого рабочего пространства, а новые сеансы безопасно сохраняются там.

• Antigravity (agy): как и в случае с Copilot, сеансы «разветвляются» при первом запуске flar в проекте и больше не используются совместно с agy, запущенным вне flar.

agy не разделяет разговоры по проектам на диске. Все разговоры для всех проектов хранятся в едином плоском хранилище в ~/.gemini/antigravity-cli/ (conversations/, brain/, implicit/), идентифицируемые только UUID, а принадлежащее рабочее пространство записано внутри непрозрачных блоков разговоров. Индекс недавних (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 в проекте он заполняет изолированное хранилище этого проекта из существующей истории хоста — но только теми разговорами, которые сам agy приписывает этому рабочему пространству (определяется по обычному тексту last_conversations.json и history.jsonl, никогда не разбирая блоки разговоров). После этого одноразового заполнения изолированное хранилище становится независимым: новые сеансы живут только в изолированном хранилище, а последующие изменения на стороне хоста не подтягиваются.

• Reasonix: Как и Claude Code. Reasonix хранит историю каждого проекта в своей собственной поддиректории, поэтому может быть смонтирован тем же способом, что и Claude Code, с той же оговоркой.

Последствия, о которых следует знать:

• Copilot CLI: как и с agy, изолированный теневой домашний каталог становится отдельным миром для каждого проекта после начального заполнения. Сеансы, начатые с Copilot вне flar, не подтягиваются в flar позже, а сеансы, начатые внутри flar, сохраняются обратно в изолированный теневой домашний каталог, а не в глобальное хранилище Copilot на хосте.
• Сеансы, начатые с agy вне flar (кроме начального заполнения), не видны внутри flar, и наоборот. Это сделано намеренно — история agy в flar — это отдельный, изолированный по проектам мир.
• Codex следует тому же правилу: после одноразового заполнения истории с flar и без него становятся независимыми.
• Разговор, который собственные индексы agy никогда не приписывали текущему рабочему пространству, не заполняется по замыслу. Безопасное поведение по умолчанию — скрыть его, а не рисковать раскрытием данных другого проекта.
• Директории .flar/, принадлежащие агенту, исключаются из копий конфигурации для совместимости, а состояние, принадлежащее flar, хранится в $XDG_STATE_HOME/flar/ (или ), вне управляемых агентом директорий конфигурации.

Сетевая безопасность и локальные порты

В изолированном сетевом режиме окружение агента не имеет прямого доступа к сетевым интерфейсам хоста.

• Доступ в Интернет: Работает автоматически для HTTP/HTTPS-запросов (например, для подключения к облачным LLM, таким как Anthropic или Gemini) с использованием переменных окружения HTTP_PROXY и HTTPS_PROXY.
• Ограничения на localhost: Запросы к localhost или петлевым IP через прокси блокируются.
• Открытие локальных служб: Чтобы агент мог получить доступ к локальной базе данных или локальной LLM (например, Ollama на 127.0.0.1:11434), укажите порт с помощью -allow-port 11434 или параметра allow_ports в конфигурации. Безопасный пересыльщик петлевого интерфейса привяжет 127.0.0.1:11434 внутри песочницы и будет проксировать трафик на хост.