Ag-Bash
sairam0424/ag-bash
Shell virtualizado sandboxado para agentes IA com observabilidade integrada
Ver no GitHubUm servidor MCP de ambiente Bash sandboxado de nível produção, projetado para agentes de IA. Oferece análise AST por Tree-sitter, observabilidade agentica automática (AgTrace), filesystem em memória e suporte multiplataforma.
Instalação
npx convez-ai sairam0424/ag-bash1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Execução segura de comandos Bash em agentes IA
- Automação de tarefas de desenvolvimento sem risco ao sistema
- Análise estruturada de scripts com AST e detecção de comandos destrutivos
Veredito

Solução robusta e bem arquitetada para executar código shell de forma segura em agentes IA. Pipeline de execução modular e observabilidade nativa fazem desta uma escolha sólida para automação confiável, embora exija familiaridade com conceitos de sandboxing e protocolos MCP.
README
A tradução para o português deste README ainda está na fila.
Ag-Bash: The AI-Native Shell Monorepo
Ag-Bash is a production-grade, sandboxed Bash environment designed specifically for AI agents. It provides a virtualized Unix-like experience entirely in-process, featuring an in-memory filesystem, integrated runtimes for Python and JavaScript, and full support for modern agentic protocols.
🏗️ Monorepo Architecture
This repository is organized into a modular monorepo to support independent versioning and consumption of core engine components and protocol adapters.
| Package | Version | Description |
|---|---|---|
@ag-bash/bash | Core Engine: The virtual shell, filesystem, and sandboxed runtimes. | |
@ag-bash/mcp-server | MCP Server: A standalone Model Context Protocol server for seamless agent integration. | |
@ag-bash/agent-bridge | Agent Bridge: Terminal UI bridge for AI agent communication. |
What's New in v6.0.0
| Feature | Description |
|---|---|
| ExecutionPipeline | The composable 6-stage pipeline (normalize, parse, transform, sandbox, interpret, persist) is now the sole execution engine. The legacy monolith path has been removed. |
| Fork-Speculation | bash.fork() creates isolated copy-on-write branches; bash.speculate() runs N candidates in parallel and keeps the winner. Core moat for agentic workflows. |
| Observations at Source | Every command produces typed Observation objects with code and confidence fields, surfacing issues without blocking execution. |
| True Streaming | bash.execStream() yields stdout/stderr chunks via AsyncGenerator as statements produce output, byte-identical to buffered exec. |
| RunLoop v2 | Extended with mode, healer, and memory configuration. AgentMemory now persists across sessions. |
| MCP 2025-06-18 | Protocol bumped to latest spec with back-compat preserved for 2024-11-05 clients. Code Mode slice for structured output. |
| Destructive Detection | AST-based gate detects rm -rf /, fork bombs, and decode-pipe-to-shell patterns structurally. Default policy: WARN. |
| OTEL at Exec Level | Optional AgBashTracer wraps each exec() call in an OpenTelemetry span. Zero overhead when @opentelemetry/api is absent. |
Installation & Distribution
Requires Node.js >=20.6.0. For full ESM-hook security hardening, Node.js >=23.5 is recommended.
Ag-Bash ships across multiple channels (current version 6.0.4, synchronized across all npm packages):
npm library
# Core engine (recommended)
npm i @ag-bash/bash
# With the standalone MCP server
npm install @ag-bash/mcp-server
Subpath imports for tree-shaking and targeted use:
import { Bash, createShell } from "@ag-bash/bash";
import { RunLoop } from "@ag-bash/bash/agent-runtime";
import { createTestBash } from "@ag-bash/bash/testing";
MCP server (npx / MCP Registry)
The MCP server exposes 70 tools over stdio. Add it to Claude Code in one command (no global install needed):
claude mcp add ag-bash -- npx -y @ag-bash/mcp-server
# or run it directly
npx @ag-bash/mcp-server
It is also published to the MCP Registry as io.github.sairam0424/ag-bash.
A submission to the Docker MCP Catalog (
docker/mcp-registry) is currently in review.
Claude Code plugin
/plugin marketplace add sairam0424/ag-bash
/plugin install ag-bash@ag-bash
Homebrew (macOS)
brew tap sairam0424/tap
brew install ag-bash
This also installs the ag-shell and ag-bash-mcp binaries.
🚀 Quick Start
For Developers (Library)
If you are building an application and want to embed a sandboxed shell:
npm install @ag-bash/bash
import { Bash, createShell } from "@ag-bash/bash";
// Quick instantiation
const bash = new Bash();
const result = await bash.exec('echo "Hello Ag-Bash"');
console.log(result.stdout); // "Hello Ag-Bash\n"
// Or use createShell for full configuration
const shell = createShell({ filesystem: "overlay", cwd: "/workspace" });
await shell.exec("ls -la");
2. Standalone CLI & Shell (Global)
For human-in-the-loop debugging and interactive use, install the Ag-Bash suite globally.
Via Homebrew (macOS)
brew tap sairam0424/tap
brew install ag-bash
This installs the ag-bash, ag-shell, and ag-bash-mcp binaries.
Via NPM (Cross-platform)
npm install -g @ag-bash/bash @ag-bash/mcp-server
For AI Agents (MCP)
To provide a bash environment to your agent (e.g., in Claude Code, Claude Desktop, or Cursor), register the MCP server via npx — no global install required:
claude mcp add ag-bash -- npx -y @ag-bash/mcp-server
Or add the server to your MCP configuration manually:
{
"mcpServers": {
"ag-bash": {
"command": "npx",
"args": ["-y", "@ag-bash/mcp-server"]
}
}
}
🛡️ Key Features
- v6.0 Architecture: ExecutionPipeline as sole engine, fork-speculation, observations-at-source, true streaming, OTEL tracing, destructive-detection gate.
- v6.0 RunLoop: Autonomous LLM execution loop with observation forwarding, AgenticHealer self-correction, AgentMemory persistence, plan-mode write-gating, and BudgetManager stopping conditions.
- v3.0 DI (Breaking): Dependency Injection via
ServiceContainer, restructuredBashOptionsAPI with grouped sub-objects, and zero singletons. - FNV-1a ASTCache: Non-cryptographic hashing with true LRU eviction for high-frequency script execution.
- Pipeline Early Termination: Static AST analysis detects
head -Npatterns and truncates upstream output. - Type-Safe Core: Eliminated
anytypes from core services, interpreter, and error hierarchy (unknownthroughout). - Hardened MCP Server: Sanitized JSON-RPC error messages (path stripping, length cap), zero console leakage from library code.
- Project V-Next: (v2.5.0+) Unified Permission Architecture, Real JSON-RPC MCP Client (Stdio/HTTP), and multi-step Planning Mode.
- Nexus Prime Suite: (v2.0.0+) Intelligent semantic analysis (
ag-hover,ag-explain), symbol discovery, and persistent project management. - Agentic Healer 2.0: (v2.4.0+) Tool-aware recovery loop with multi-keyword semantic scoring for automated remediation.
- High-Fidelity Observability: (v2.4.0+) EventEmitter-driven tool tracking with
tool:start,tool:progress, andtool:endhooks. - Tree-sitter AST Parser: High-fidelity shell parsing for complex scripts and security analysis.
- Virtual Filesystem: Choose between
InMemoryFs,OverlayFs(COW), orReadWriteFs. - Integrated Runtimes: Out-of-the-box support for
jq,sqlite3,python3(WASM), andjs-exec(QuickJS). - Protocol First: Full Model Context Protocol (MCP) support with persistent session state.
- Defense in Depth: Robust sandbox prevents prototype pollution and unauthorized filesystem access.
- No Dependencies: The core engine is lightweight and runs in Node.js or the Browser.
📖 Documentation
- User Guide: Narrative introduction to Ag-Bash, installation, and core concepts.
- Command Registry: Categorized reference for all 110+ supported tools.
- Technical Architecture: Deep dive into the Nexus engine, performance, and resource accounting.
- Shell Engine Deep-Dive: Technical guide for filesystem options and custom commands.
- MCP Server Configuration: Agentic integration patterns and configuration.
- Security & Threat Model: Detailed breakdown of the sandbox architecture.
Version History
| Version | Codename | Highlights |
|---|---|---|
| v6.0 | Pipeline | ExecutionPipeline default, fork-speculation, streaming, OTEL, destructive gate, Node >=20.6 |
| v5.0 | Hardened | Lazy ServiceContainer, defense-in-depth default ON, SSRF prevention, ASTCache 64-bit FNV-1a |
| v4.1 | Runtime | Introduced Agent RunLoop, Trap signal handlers, Self-Healing recovery, and OpenTelemetry spans (default/extended in v6.0) |
| v3.0 | Breaking Redesign | ServiceContainer DI, new BashOptions grouped API, zero singletons |
| v2.x | Nexus Prime | Agentic tools (ag-hover, ag-explain), MCP integration, Planning Mode |
| v1.x | Genesis | Initial release, core interpreter, in-memory filesystem, basic builtins |
See the CHANGELOG for detailed release notes.
📜 License
Apache-2.0