gbash

Getting Started

gbash is a deterministic, sandbox-only, bash-like runtime for AI agents, implemented in Go. Shell parsing and execution are owned in-tree under internal/shell, with a project-owned virtual filesystem, registry-backed command execution, policy enforcement, and opt-in observability around that shell core.

Commands never fall through to host binaries, and network access is off by default.

gbash is alpha software. Additional security hardening is likely needed. Use with care.

What it does

  • Ships a virtual in-memory filesystem with no host access by default
  • Resolves commands through a registry, so unknown commands never run host binaries
  • Includes 100+ built-in commands and shell builtins with GNU coreutils compatibility tracking (compatibility report)
  • Supports optional network access via allowlisted curl
  • Provides persistent sessions with shared filesystem state across executions
  • Allows host directory mounting with read-only overlay for real project workspaces
  • Enforces execution budgets for command count, loop iterations, glob expansion, and stdout/stderr limits
  • Has opt-in tracing and logging for debugging and agent orchestration
  • Runs in the browser via WebAssembly

Next Steps

  • Installation - install the Go library, CLI, or prebuilt binaries
  • Quick Start - run your first sandboxed shell command in under a minute
  • Configuration - choose an in-memory, mounted, or custom filesystem and decide whether network access is allowed
  • Commands - review the default registry, shell builtins, and optional contrib modules
  • API - embed gbash in Go or JavaScript hosts
  • Security - understand the sandbox guarantees, threat model, and observability tradeoffs