flar

FLAR é o Fast Light Agent Restrictor (Restritor Rápido e Leve de Agentes). Ele funciona em rochas chamadas gars.

É uma ferramenta CLI simples e leve em Go para executar CLIs de agentes de codificação (como Claude Code, Antigravity, Codex, Copilot e Reasonix) com segurança dentro de sandboxes Bubblewrap (bwrap) isoladas.

O objetivo é, instantaneamente e sem configuração complicada, encapsular um agente de IA com bubblewrap para que ele tenha acesso apenas ao projeto em que você está trabalhando. Isso protege contra injeções de prompt, bem como problemas de cadeia de suprimentos em bibliotecas que o agente possa puxar para o seu projeto sem verificação suficiente (ou apenas por azar). A única informação confidencial acessível são os detalhes de autenticação do próprio agente e o histórico de chat do projeto.

A maioria dos agentes tem um recurso de "sandbox", mas ele é bastante poroso e o próprio agente pode expandir o escopo do que é acessível. E, claro, as vulnerabilidades de cadeia de suprimentos não estão sujeitas à sandbox do agente. flar é totalmente imune ao agente, e o raio de explosão de ataques à cadeia de suprimentos é rigidamente controlado.

O Bubblewrap é extremamente testado e mantido ativamente. É usado pelo Flatpack e muitos outros projetos para contêineres leves. flar é muito menos testado, e usado por mim por alguns dias.

Funcionalidades

• Sandbox Bubblewrap: Executa o agente em um namespace de usuário não privilegiado usando um diretório raiz limpo (tmpfs). Os caminhos do sistema (/usr, /bin, /lib, /lib64, etc.) são montados somente leitura a partir do host, garantindo que os pacotes do host estejam imediatamente disponíveis sem gerenciamento de imagem de contêiner.
• Isolamento Estrito do Sistema de Arquivos: Apenas o diretório do projeto alvo é montado como bind com leitura/escrita. O restante do diretório home do host fica oculto, protegendo chaves ssh, configurações de shell e arquivos pessoais contra ataques de injeção de prompt.
• Isolamento de Rede:
  • Modo Isolado (Padrão): O namespace de rede é descompartilhado. O acesso à Internet é tunelado através de um proxy HTTP/HTTPS do lado do host que realiza a resolução de DNS no host e filtra o tráfego para endereços IP locais/loopback.
  • Redirecionamento de Portas: Exponha seletivamente serviços locais (por exemplo, bancos de dados, modelos llama.cpp) na sandbox mapeando portas específicas para o localhost do host.
  • Modo Host: Opção para compartilhar o namespace de rede do host para acesso irrestrito.
• Opções de Bypass Perigosas: Injeta automaticamente flags (como --dangerously-skip-permissions para Claude/agy ou --dangerously-bypass-approvals-and-sandbox para Codex) para que os agentes sejam executados sem interrupções de aprovação em tempo de execução. Pode ser desabilitado com -ask.
• Cópia de Configuração: Copia automaticamente as credenciais do host (como ~/.claude/, ~/.codex/, ~/.gemini/, ou configurações do GitHub CLI) para um diretório temporário montado dentro do diretório home da sandbox, deixando os arquivos de configuração do host intocados.
• Persistência e Retomada de Sessão: Quando razoavelmente seguro (atualmente Claude Code e Reasonix), as conversas iniciadas dentro de uma sandbox são gravadas de volta no host, para que --resume/--continue funcione entre execuções — limitado ao projeto atual para que nenhum histórico de outro projeto entre na sandbox. Caso contrário, o histórico é bifurcado na primeira execução do flar para um determinado agente e projeto. Consulte Persistência e retomada de sessão.
• Pontes de Chaveiro (agy): A CLI Antigravity armazena seu token OAuth no chaveiro do sistema, não em um arquivo. O flar extrai apenas aquele segredo e o serve dentro da sandbox através de um Serviço de Segredo privado e em processo — para que o agente se autentique sem expor o resto do seu chaveiro. Consulte Credenciais.

Compilar e Instalar

Dependências

Certifique-se de que o bwrap (Bubblewrap) está instalado no seu sistema host:

# No Fedora/RHEL
sudo dnf install bubblewrap

# No Debian/Ubuntu
sudo apt install bubblewrap

Compilar e Instalar

Para compilar o flar a partir do código fonte:

go build -o `flar` .

Para instalar:

mv `flar` ~/.local/bin/

Uso

Execute o flar na pasta do seu projeto ou especifique o caminho:

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

Flags

• -m: Especifica o agente a ser executado (claude, codex, agy, copilot, reasonix). O padrão é verificar as configurações do host ou variáveis de ambiente disponíveis.
• -ask: Não pular permissões/aprovações (forçando o agente a pedir permissão).
• -network: Modo de rede: isolated (padrão) ou host.
• -allow-port: Permitir uma porta TCP local específica (por exemplo, 8080, 11434) através da sandbox de rede isolada. Pode ser especificado várias vezes.
• -v: Ativar log detalhado.

Arquivo de configuração (.flar.json)

Você pode configurar opções por projeto em <projeto>/.flar.json ou globalmente em ~/.config/flar/config.json:

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

Credenciais

Como apenas uma cópia temporária da sua configuração é montada, os agentes são executados autenticados usando sua sessão host existente sem tocar nos originais. A maioria dos agentes mantém sua sessão em arquivos que o flar copia diretamente:

• Claude: ~/.claude/ (incluindo .credentials.json) e ~/.claude.json, o arquivo de nível superior que contém o estado de integração e a identidade da conta. Ambos são necessários; com apenas as credenciais, o Claude trata a sandbox como uma instalação nova e solicita o login.
• Codex / Copilot: ~/.codex/, ~/.copilot/ e a configuração do GitHub CLI.

Chaveiro do Antigravity (agy)

O agy é a exceção: ele não armazena seu token em um arquivo. Ele o mantém no chaveiro do sistema, lido através da API freedesktop Secret Service sobre o barramento de sessão D-Bus. A sandbox não possui barramento de sessão, então uma configuração ingênua falha com authentication failed or timed out.

O flar lida com isso de forma especial:

1. No host, ele extrai apenas o token do agy (item do chaveiro service=gemini, username=antigravity) usando secret-tool e o escreve em um arquivo 0600 no diretório de configuração temporário.
2. Dentro da sandbox, ele executa um Serviço de Segredo mínimo e autocontido (flar --internal-secretsvc) em um socket Unix privado, apontado por DBUS_SESSION_BUS_ADDRESS. Ele serve aquele único token e nada mais.

O agente pode acessar exatamente seu próprio token — não o resto do seu chaveiro (senhas do navegador, segredos de outros aplicativos, etc.). A implementação fala o protocolo de fio D-Bus diretamente, então não precisa de nenhum gnome-keyring ou dbus-daemon dentro da sandbox.

Requisitos e ressalvas:

• A extração do lado do host precisa de secret-tool (libsecret) instalado no host. Se estiver ausente ou o token não for encontrado, o flar pula a ponte e o agy recai para o prompt de login normal.
• Qualquer agente autenticado pode, por definição, ler seu próprio token; um ataque de injeção de prompt poderia exfiltrá-lo. Isso é inerente à execução autenticada em si. A ponte de chaveiro limita a exposição àquele único token, em vez de todo o seu chaveiro.

Persistência e retomada de sessão