Agentic Sandbox + AIWG Ecosystem — Document Catalog
Cross-repo reference for daemon, webserver, orchestration, control plane, and related documentation spanning both the Agentic Sandbox and AIWG projects.
Agentic Sandbox is a complete standalone platform and also a first-class AIWG compute node. This catalog helps you find documentation for both use cases.
How the Projects Relate
┌──────────────────────────────────────────────────────────────┐
│ AIWG (aiwg.io) │
│ │
│ Operator Layer Orchestration Layer │
│ ───────────── ──────────────────── │
│ aiwg serve Mission Control (mc) │
│ Web dashboard Ralph / External Ralph │
│ HITL drawer Parallel dispatch │
│ Telemetry Agent teams │
│ │ │ │
│ │ sandbox registration │ PTY adapter delegation │
└───────┼─────────────────────────┼────────────────────────────┘
│ │
▼ ▼
┌──────────────────────────────────────────────────────────────┐
│ Agentic Sandbox (this repo) │
│ │
│ Management Server Agent VMs Storage │
│ ───────────────── ───────── ─────── │
│ gRPC :8120 QEMU/KVM virtiofs │
│ WebSocket :8121 Docker agentshare │
│ HTTP :8122 Loadouts inbox/global │
│ HITL detection Claude Code │
│ PTY screen observer AIWG frameworks │
└──────────────────────────────────────────────────────────────┘
Agentic Sandbox Documentation
Architecture & Design
| Document | Description |
|---|
| docs/ARCHITECTURE.md | Full system architecture — management server, agent client, task orchestration, protocols, security, observability, and AIWG integration architecture (§9) |
| docs/agentshare.md | virtiofs shared storage layout — global read-only, per-agent inbox, data flows, libvirt configuration |
| docs/SESSION_RECONCILIATION.md | Session state machine, checkpoint system, orphan detection and cleanup after server restart |
Deployment & Configuration
| Document | Description |
|---|
| docs/DEPLOYMENT.md | Complete production deployment guide — prerequisites, installation, host configuration, management server setup, AIWG integration configuration |
| management/README.md | Management server quick reference — ports, env vars (including `AIWG_SERVE_ENDPOINT`), dev.sh lifecycle, authentication, testing with aiwg serve |
| docs/LOADOUTS.md | Declarative VM provisioning manifests — YAML schema, profiles, AIWG framework installation |
Operations & Runbooks
| Document | Description |
|---|
| docs/OPERATIONS.md | Day-to-day operational procedures — server lifecycle, VM management, task management, session management, AIWG serve operations and HITL management |
| docs/LIFECYCLE.md | VM and task lifecycle state machines, cleanup policies, retention management |
| docs/vm-lifecycle.md | VM state machine, provisioning and teardown scripts, virsh commands reference |
| docs/SESSION_RECONCILIATION.md | Session recovery procedures |
API & Protocols
Subsystems
| Document | Description |
|---|
| docs/container-runtime.md | Docker-backed agent instances — `docker_runtime` API, VM vs container trade-offs, provider image catalog, AIWG bridge integration |
| docs/crash-loop.md | VM crash-loop detector — rolling-window detection, state machine, auto-rebuild via `provision-vm.sh`, operator unblock |
| docs/telemetry.md | Telemetry pipeline — agent-side gather, textfile collector hand-off, management-server aggregation, Prometheus exposition, per-tenant labels |
| docs/transport-audit.md | Operator-facing transport audit — `/api/v1/logs` ring buffer, `/api/v1/events` SSE, admin v2 (`/api/v2/admin/*`) streams |
Monitoring & Observability
| Document | Description |
|---|
| docs/monitoring.md | Prometheus metrics, Grafana dashboards, AlertManager — deployment, metrics schema, SLO tracking |
| docs/observability/README.md | Full observability system design — metrics, log aggregation, SLIs/SLOs, alert rules, dashboards |
| docs/observability/ARCHITECTURE_DIAGRAM.md | ASCII architecture diagrams, data flow, component inventory, retention policies |
| docs/observability/QUICK_REFERENCE.md | Operator cheat sheet — PromQL/LogQL queries, troubleshooting, performance baselines |
| docs/research/agent-activity-observability-spike-707.md | Research spike — correlated agent/session, process, network, runtime, kernel, and loss-aware activity monitoring architecture |
| docs/reliability-README.md | Reliability patterns and SLO design overview |
| docs/reliability-quickstart.md | Quick start for reliability setup |
Troubleshooting
| Document | Description |
|---|
| docs/TROUBLESHOOTING.md | Comprehensive troubleshooting — management server, VMs, agents, tasks, AIWG serve integration issues |
Testing
| Document | Description |
|---|
| tests/README.md | E2E test suite overview and usage |
| scripts/chaos/README.md | Chaos testing framework — 5 experiments: server kill, storage fill, VM kill, network partition, slow clone |
AIWG Documentation
All AIWG documentation is in the jmagly/aiwg repository.
aiwg serve — Operator Dashboard
| Document | Description |
|---|
| docs/serve-guide.md | Primary reference. `aiwg serve` web dashboard — terminal sessions, Mission Control UI, sandbox management, HITL drawer. Covers sandbox registration API, WebSocket event types, PTY bridge, AIWG integration, security, and troubleshooting |
Daemon — Background Process & Automation
| Document | Description |
|---|
| docs/daemon-guide.md | Complete daemon guide — platform support tiers (Tier 1 native, Tier 2 PTY adapter), execution modes (local/container/VM), DaemonSupervisor, scheduled tasks, file watching, PTY adapter configuration |
| docs/addons/daemon/daemon-addon-guide.md | Daemon addon — Concierge front-end, session memory, interaction rules, provider support matrix |
| docs/addons/daemon/quickstart.md | Quick start — install, initialize, start daemon, access web UI at localhost:7474, submit a task |
| docs/addons/daemon/configuration-reference.md | Full `.aiwg/daemon.json` reference — core, supervisor, interface, watch, schedule, rules, behaviors |
| docs/getting-started/daemon-and-automation.md | Scenario guide — background tasks, file watching, scheduled tasks, Telegram notifications, autonomous execution |
| docs/concierge-guide.md | Concierge — the daemon's front-facing interaction layer; intent routing, tone, memory, fallback |
| docs/behaviors-guide.md | Behaviors — event-driven automation (`BEHAVIOR.md` deployable + YAML runtime); triggers, hooks, scripts |
Orchestration — Mission Control & Multi-Agent
| Document | Description |
|---|
| docs/cli-reference.md | Full CLI reference — all 50+ commands including `aiwg mc` (Mission Control), `aiwg serve`, `aiwg ralph`, agent teams, parallel dispatch, SDLC flows |
| docs/frameworks/sdlc-complete/orchestrator-architecture.md | Core orchestration pattern — flow templates as orchestration guides, multi-agent review cycles, human approval gates |
| docs/ralph-guide.md | Ralph — iterative agent execution engine; in-session loops, external crash-resilient loops (6-8+ hours), completion criteria, error recovery |
| docs/task-management-integration.md | Task submission, queue management, and progress tracking integration patterns |
Reference
| Document | Description |
|---|
| README.md | Main AIWG README — what AIWG is, six core components, walkthrough, features, platform support matrix |
| docs/how-it-works.md | AIWG architecture and design patterns overview |
| CHANGELOG.md | Release notes — v2026.4.0 covers daemon, Mission Control, aiwg serve, PTY adapter, sandbox integration |
Quick Navigation by Task