Skip to content

Document sandbox configuration and external runtime options #120

@geoffjay

Description

@geoffjay

Context

Child of #78. Should be done after #116, #117, #118, #119.

Changes

Orchestrator docs (docs/public/services/orchestrator.md)

  • Add security fields to the Create Agent request table
  • Add a "Sandbox & Permissions" section covering:
    • New YAML template fields with examples for common patterns:
      • Read-only agent (permission_mode: plan, tools: [Read, Grep, Glob])
      • Fully sandboxed worker (skip_permissions: true, require_sandbox: true)
      • Git-only agent (allowed_tools: ["Bash(git:*)", "Read", "Grep", "Glob"])
    • Defense-in-depth: tool_policy (orchestrator-level WebSocket enforcement) vs --allowed-tools/--permission-mode (Claude-level restrictions)

Getting started docs (docs/public/getting-started.md)

  • Add a note about sandbox configuration in Claude Code's settings.json
  • Claude Code's Seatbelt sandbox is configured via settings.json — not confirmed enabled by default for SDK mode
  • Link to Claude Code sandboxing docs: https://code.claude.com/docs/en/sandboxing

Future: External Sandbox Runtimes section

Document these as options for deeper OS-level process isolation in a future release:

  • sandbox-runtime-rs — Rust port of Anthropic's sandbox runtime, uses Seatbelt (macOS) and bubblewrap+seccomp (Linux)
  • wardstone — Rust crate for macOS Seatbelt and Linux Landlock LSM sandboxing, designed for AI agent environments

Files

  • docs/public/services/orchestrator.md
  • docs/public/getting-started.md

Acceptance Criteria

  • Create Agent table includes all new fields
  • Sandbox & Permissions section with YAML examples
  • Defense-in-depth explanation
  • Getting started includes sandbox config note
  • Future runtimes section with links

Metadata

Metadata

Assignees

No one assigned

    Labels

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions