agentsh

Nota para macOS: La aplicación nativa de enforcement en macOS mediante ESF (Endpoint Security Framework) + NE (Network Extension) está en Alpha. Funciona de extremo a extremo: los eventos de archivos, procesos y red fluyen a través de la extensión del sistema hasta el motor de políticas Go, pero espera bordes sin pulir y cambios que rompan compatibilidad entre versiones. Para uso en producción hoy, recomendamos Linux.

Nota para Windows: Estamos trabajando para que los controladores minifilter estén firmados. Hasta entonces, solo el modo WSL2 de Windows es totalmente compatible para uso en producción.

Puerta de enlace de ejecución segura y con políticas para agentes de IA.

agentsh se sitúa debajo de tu agente/herramienta: intercepta la actividad de archivos, red, procesos y señales (incluidos los árboles de subprocesos), aplica la política que definas y emite eventos de auditoría estructurados.

Nota de plataforma: Linux ofrece enforcement completo (100 % de puntuación de seguridad). macOS ESF+NE (90 %) está en Alpha: funcional pero no listo para producción. WSL2 de Windows ofrece enforcement completo equivalente a Linux (100 %); Windows nativo mediante controlador minifilter + AppContainer (85 %) está pendiente de la firma del controlador. Consulta la Matriz de comparación de plataformas para más detalles.

---

¿Qué es agentsh?

• Endpoint shell/exec de sustitución directa que convierte cada comando (y sus subprocesos) en eventos auditables.
• Motor de políticas por operación: allow, deny, approve (aprobación humana), soft_delete o redirect.
• Visibilidad total de E/S:
  • apertura/lectura/escritura/eliminación de archivos
  • conexión de red + DNS
  • inicio/fin de procesos
  • actividad PTY
  • solicitudes de API de LLM con DLP y seguimiento de uso
  • tráfico de bases de datos tipo Postgres mediante db_services declarados
  • envío/bloqueo de señales (aplicado en Linux, auditoría en macOS/Windows)
  • consultas de bases de datos a través del proxy PostgreSQL integrado: clasificación y política por sentencia
  • Enrutamiento de llamadas HTTP salientes a la API mediante servicios declarados (http_services) con reglas por método y por ruta, control de aprobación y enforcement de host con fallo cerrado
• Dos modos de salida:
  • salida de shell legible para humanos
  • respuestas JSON compactas para agentes/herramientas

---

¿Por qué agentsh?

Los flujos de trabajo de agentes tarde o temprano ejecutan código arbitrario (pip install, make test, python script.py). Los controles tradicionales de "pedir aprobación antes de ejecutar un comando" se detienen en el límite de la herramienta y no pueden ver lo que sucede dentro de ese comando.

agentsh aplica la política en tiempo de ejecución, de modo que el trabajo oculto realizado por los subprocesos también se gobierna, se registra y (cuando es necesario) se aprueba.

---

Bloqueos significativos: deny → redirect (el superpoder del "direccionamiento")

La mayoría de los sistemas pueden denegar una acción. agentsh también puede redirigirla.

Eso significa que cuando un agente intenta el enfoque incorrecto (o soluciones por fuerza bruta), la política puede guiarlo hacia el camino correcto intercambiando el comando y devolviendo orientación, manteniendo al agente en el camino pavimentado y reduciendo reintentos desperdiciados.

Ejemplo: redirigir curl a un 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"]

**Ejemplo: redirigir las escrituras fuera del workspace de vuelta al interior**```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"

El agente ve una operación exitosa (no un error), pero tú controlas dónde aterrizan realmente las cosas.

---

Contenedores + agentsh: mejor juntos

Los contenedores aíslan la superficie del host; agentsh añade visibilidad y política de ejecución dentro del contenedor.

• La auditoría por operación (archivos, red, comandos) muestra lo que ocurrió durante instalaciones/compilaciones/pruebas.
• Las aprobaciones y reglas persisten a lo largo de shells de larga duración y árboles de subprocesos—no solo en el primer comando.
• Controles a nivel de ruta en workspaces/cachés/credenciales montados; los contenedores no ofrecen de forma nativa ese nivel de granularidad.
• El mismo comportamiento en el host y en los contenedores, por lo que la CI y el desarrollo local ven los mismos resultados de las políticas.

---

Inicio rápido

Instalación

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

Esto instala el paquete de la aplicación AgentSH con la extensión del sistema ESF+NE. Después de la instalación, se te pedirá que apruebes la extensión del sistema en **System Settings > General > Login Items & Extensions**.

**Linux (desde un lanzamiento de GitHub)**

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

Desde el código fuente (Linux)```bash make build sudo install -m 0755 bin/agentsh bin/agentsh-shell-shim /usr/local/bin

**Desde el código fuente (macOS)**```bash
# ESF+NE mode (full enforcement — Alpha, requires Xcode 15+)
make build-macos-enterprise

Consulta la Guía de compilación de macOS para obtener instrucciones detalladas de compilación en macOS.

---

Ejecutar 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

---

### Comprueba qué se aplica realmente

`agentsh detect` sondea el host e informa qué primitivas de cumplimiento están realmente disponibles — seccomp, Landlock, FUSE, eBPF, ptrace, cgroups — agrupadas en puntuaciones de protección por dominio más el modo de seguridad seleccionado. En hosts restringidos (clase Daytona, E2B, Firecracker) donde el listener user-notify de seccomp no puede instalarse, informa del modo que se aplicará *efectivamente* en lugar de lo que el kernel meramente soporta.```bash
agentsh detect              # human-readable protection report
agentsh detect config       # emit a config tuned for this host

Consulta Modos de seguridad para la matriz de modos y los parámetros de ajuste.

---

Indica a tu agente que lo use (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)

---

### Autostart (sin paso manual de daemon)

**No** necesitas iniciar `agentsh server` tú mismo.