agentsh

Nota para macOS: A aplicação nativa no macOS via ESF (Endpoint Security Framework) + NE (Network Extension) está em Alpha. Ela funciona de ponta a ponta — eventos de arquivo, processo e rede fluem através da extensão do sistema para o mecanismo de políticas em Go — mas espere arestas e mudanças significativas entre versões. Para uso em produção hoje, recomendamos Linux.

Nota para Windows: Estamos trabalhando para obter a assinatura dos drivers minifilter. Até lá, apenas o modo Windows WSL2 é totalmente compatível para uso em produção.

Gateway de execução seguro e com aplicação de políticas para agentes de IA.

O agentsh fica abaixo do seu agente/ferramentas — interceptando atividades de arquivo, rede, processo e sinal (incluindo árvores de subprocessos), aplicando a política que você define e emitindo eventos de auditoria estruturados.

Nota de plataforma: Linux oferece aplicação total (100% de pontuação de segurança). O ESF+NE do macOS (90% de pontuação) está em Alpha — funcional, mas não pronto para produção. O WSL2 do Windows oferece aplicação total equivalente ao Linux (100% de pontuação); o Windows nativo via driver minifilter + AppContainer (85% de pontuação) está pendente de assinatura do driver. Veja a Matriz de Comparação de Plataformas para detalhes.

---

O que é o agentsh?

• Ponto de execução shell/exec substituível que transforma cada comando (e seus subprocessos) em eventos auditáveis.
• Mecanismo de política por operação: allow, deny, approve (aprovação humana), soft_delete ou redirect.
• Visibilidade completa de E/S:
  • abertura/leitura/escrita/exclusão de arquivos
  • conexão de rede + DNS
  • início/término de processos
  • atividade PTY
  • requisições de API LLM com DLP e rastreamento de uso
  • tráfego de banco de dados da família Postgres através de db_services declarados
  • envio/bloqueio de sinais (aplicado no Linux, auditado no macOS/Windows)
  • consultas a banco de dados via proxy PostgreSQL embutido — classificação e política por declaração
  • rotear chamadas de API HTTP de saída através de serviços declarados (http_services) com regras por método e por caminho, controle de aprovação e aplicação de host com falha fechada
• Dois modos de saída:
  • saída shell amigável para humanos
  • respostas JSON compactas para agentes/ferramentas

---

Por que agentsh?

Fluxos de trabalho de agentes eventualmente executam código arbitrário (pip install, make test, python script.py). Os controles tradicionais de "pedir aprovação antes de executar um comando" param no limite da ferramenta e não conseguem ver o que acontece dentro desse comando.

O agentsh aplica a política em tempo de execução, de modo que o trabalho oculto realizado por subprocessos ainda é governado, registrado e (quando necessário) aprovado.

---

Bloqueios significativos: deny → redirect (o superpoder de "direcionamento")

A maioria dos sistemas pode negar uma ação. O agentsh também pode redirecioná-la.

Isso significa que quando um agente tenta a abordagem errada (ou soluções alternativas por força bruta), a política pode direcioná-lo para o caminho correto, trocando o comando e retornando orientação — mantendo o agente no caminho pavimentado e reduzindo tentativas desperdiçadas.

Exemplo: redirecionar curl para um wrapper auditado```yaml command_rules:

• name: redirect-curl commands: [curl, wget] decision: redirect message: "Downloads routed through audited fetch" redirect_to: command: agentsh-fetch args: ["--audit"]

**Exemplo: redirecionar escritas fora do workspace de volta para dentro**```yaml
file_rules:
  - name: redirect-outside-writes
    paths: ["/home/**", "/tmp/**"]
    operations: [write, create]
    decision: redirect
    redirect_to: "/workspace/.scratch"
    message: "Writes outside workspace redirected to /workspace/.scratch"

O agente vê uma operação bem-sucedida (não um erro), mas você controla onde as coisas realmente ocorrem.

---

Containers + agentsh: melhor juntos

Containers isolam a superfície do host; agentsh adiciona visibilidade e política em tempo de execução dentro do container.

• Auditoria por operação (arquivos, rede, comandos) mostra o que aconteceu durante instalações/compilações/testes.
• Aprovações e regras persistem em shells de longa duração e árvores de subprocessos—não apenas no primeiro comando.
• Controles em nível de caminho em workspaces/caches/credenciais montados; containers nativamente não oferecem essa granularidade.
• Mesmo comportamento no host e em containers, para que CI e desenvolvimento local vejam os mesmos resultados de políticas.

---

Início rápido

Instalar

macOS (Homebrew)```bash brew tap canyonroad/tap brew install --cask agentsh

Isto instala o pacote de aplicativos AgentSH com a extensão de sistema ESF+NE. Após a instalação, será solicitado que você aprove a extensão do sistema em **System Settings > General > Login Items & Extensions**.

**Linux (a partir de um GitHub Release)**

Baixe o `.deb`, `.rpm` ou `.apk` para sua plataforma na [página de releases](https://github.com/erans/agentsh/releases).```bash
# Example for Debian/Ubuntu
sudo dpkg -i agentsh_<VERSION>_linux_amd64.deb

A partir do código fonte (Linux)```bash make build sudo install -m 0755 bin/agentsh bin/agentsh-shell-shim /usr/local/bin

**A partir do código-fonte (macOS)**```bash
# ESF+NE mode (full enforcement — Alpha, requires Xcode 15+)
make build-macos-enterprise

Veja macOS Build Guide para instruções detalhadas de compilação no macOS.

---

Execute localmente```bash

Start the server (optional if using autostart)

./bin/agentsh server --config configs/server-config.yaml

Create a session and run a command (shell output)

SID=$(./bin/agentsh session create --workspace . --json | jq -r .id) ./bin/agentsh exec "$SID" -- ls -la

Structured output for agents

./bin/agentsh exec --output json --events summary "$SID" -- curl https://example.com

---

### Verificar o que é aplicado

`agentsh detect` sonda o host e relata quais primitivas de aplicação estão realmente disponíveis — seccomp, Landlock, FUSE, eBPF, ptrace, cgroups — agrupadas em pontuações de proteção por domínio, além do modo de segurança selecionado. Em hosts restritos (Daytona, E2B, Firecracker-class) onde o listener user-notify do seccomp não pode ser instalado, ele relata o modo que *realmente* aplicará em vez do que o kernel meramente suporta.```bash
agentsh detect              # human-readable protection report
agentsh detect config       # emit a config tuned for this host

Consulte Modos de Segurança para a matriz de modos e parâmetros de ajuste.

---

Diga ao seu agente para usá-lo (AGENTS.md / CLAUDE.md snippet)```md

Shell access

• Run commands via agentsh, not directly in bash/zsh.
• Use: agentsh exec $SID -- <your-command-here>
• For structured output: agentsh exec --output json --events summary $SID -- <your-command-here>
• Get session ID first: SID=$(agentsh session create --workspace . --json | jq -r .id)

---

### Início automático (sem etapa manual do daemon)

Você **não** precisa iniciar `agentsh server` manualmente.

* O primeiro `agentsh exec` (ou qualquer `/bin/sh`/`/bin/bash` com shim) iniciará automaticamente um servidor local usando `configs/server-config.yaml` (ou `AGENTSH_CONFIG`, se definido).
* Esse servidor mantém a camada FUSE e o mecanismo de políticas ativos durante a sessão; comandos subsequentes o reutilizam.
* Defina `AGENTSH_NO_AUTO=1` se quiser gerenciar o ciclo de vida do servidor manualmente.

---

## Uso no Docker (com o shim do shell)