Internal engineering documentation for rust-bash — a Rust-based sandboxed bash environment for AI agents. This guidebook describes the system architecture, design decisions, and implementation details. It is the canonical reference for contributors and AI agents working on this codebase.
| # | Chapter | Description |
|---|---|---|
| 1 | What We Are Building | Vision, goals, non-goals, competitive positioning |
| 2 | Architecture Overview | High-level design, module structure, data flow |
| 3 | Parsing Layer | brush-parser integration, AST types, parsing pipeline |
| 4 | Interpreter Engine | AST walking, word expansion, control flow, pipelines |
| 5 | Virtual Filesystem | VFS trait, InMemoryFs, OverlayFs, MountableFs, ReadWriteFs |
| 6 | Command System | Command trait, registry, command categories, custom commands |
| 7 | Execution Safety | Limits, network policy, security model, threat mitigations |
| 8 | Integration Targets | C FFI, WASM, CLI binary, AI SDK tool definitions |
| 9 | Testing Strategy | Unit tests, snapshot tests, differential testing, fuzzing |
| 10 | Implementation Plan | Milestones, dependencies, build order, risk register |
- New to the codebase? Start with Chapter 1 for the "why", then Chapter 2 for the "how".
- Implementing a feature? Read the relevant chapter for the subsystem you're touching, then check Chapter 10 for milestone context and dependencies.
- Adding a command? Chapter 6 covers the command trait, registration, and conventions.
- Working on the interpreter? Chapters 3 and 4 cover parsing and execution in detail.
- Security review? Chapter 7 covers the threat model and all mitigations.
- Chapters describe the target architecture, not just what exists today. Sections that describe unimplemented features are marked with (planned).
- Code examples show the target API. If the current implementation differs, both are shown.
- This guidebook is the single source of truth. If
AGENTS.mdorREADME.mddiverge from it, follow the guidebook.
When making changes to the codebase:
- Update the relevant guidebook chapter(s) to reflect the change.
- If a planned feature becomes implemented, remove the (planned) marker.
- Keep Chapter 10 (Implementation Plan) current with milestone status.