قبل AgentBox                    بعد AgentBox
─────────────────                  ──────────────
وكيل → قرص كامل ❌               وكيل → مسارات مسموحة فقط ✅
وكيل → كل الشبكة ❌              وكيل → مضيفون مسموحون فقط ✅
وكيل → أسرار خام ❌              وكيل → رموز محدودة النطاق ✅
لا سجل تدقيق ❌                  كل إجراء مسجل ✅
لا مفتاح إيقاف طارئ ❌          إيقاف في <100ms ✅
المهارات تعمل كجذر ❌            صندوق معزول على مستوى النواة ✅

# التثبيت
go install github.com/siyad01/agentbox/cmd/agentbox@latest

# التحقق من بيان قبل التشغيل
agentbox validate manifests/email-sorter.yaml

# تشغيل وكيل في صندوق معزول
agentbox run --manifest manifests/email-sorter.yaml python agent.py

# عرض ما فعله الوكيل
agentbox audit --log logs/email-sorter-audit.log

# التحقق من عدم العبث بالسجل
agentbox verify logs/email-sorter-audit.log

# إدارة الأسرار
agentbox vault add ANTHROPIC_API_KEY
agentbox vault list

name: "email-sorter"
version: "1.0.0"
description: "Reads inbox, categorizes emails, writes to sorted folder"
runtime: docker        # or: gvisor (kernel-level), firecracker (MicroVM)

permissions:
  filesystem:
    read:
      - "~/Documents/inbox"
    write:
      - "~/Documents/sorted"
    deny:                      # ALWAYS blocked — even if in read list
      - "~/.ssh"
      - "~/.aws"
      - "~/.config"
      - "/etc"

  network:
    allow:
      - "api.anthropic.com"
      - "gmail.googleapis.com"
    deny:
      - "*"                    # block everything else

  tools:
    allow:
      - "read_file"
      - "write_file"
      - "list_*"
    deny:
      - "execute_shell"        # no shell access, ever
      - "*_delete"             # no deletion tools

  credentials:
    - ANTHROPIC_API_KEY        # injected from vault at runtime
    - GMAIL_TOKEN              # agent never sees the raw value

limits:
  max_tokens:    50000         # LLM token budget
  max_duration:  "30m"         # killed after 30 minutes
  max_memory_mb: 256           # RAM ceiling
  max_requests:  500           # max tool invocations

audit:
  log_level: full
  alert_on:
    - filesystem_deny
    - network_deny
    - token_budget_80pct
  log_path: "logs/email-sorter-audit.log"

agentbox run --manifest agent.yaml python agent.py
         │
         ▼
┌─────────────────────────────────────────────────────┐
│                 Policy Engine                        │
│  Parses manifest → builds allow/deny lists          │
│  Validates signatures → rejects unsigned skills     │
│  Injects credentials from vault                     │
└──────────────────────┬──────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────┐
│              Isolation Layer                         │
│                                                     │
│  Docker  → container + seccomp + cap-drop           │
│  gVisor  → user-space kernel, syscall interception  │
│  Firecracker → dedicated MicroVM kernel per agent   │
│                                                     │
│  Filesystem: only declared paths mounted            │
│  Network:    only declared hosts reachable          │
│  Capabilities: ALL dropped, none added back         │
└──────────────────────┬──────────────────────────────┘
                       │
          ┌────────────┼────────────┐
          ▼            ▼            ▼
   Audit Logger   Credential    Resource
   (hash-chain)     Vault       Monitor
   every action   AES-256-GCM  auto-kill
   logged         scoped tokens on limit

Agent tries: write("/home/user/.ssh/id_rsa")
                    │
                    ▼
         gVisor user-space kernel
                    │
         Path in deny list? → YES
                    │
                    ▼
         EPERM returned immediately
         Host kernel never sees this syscall
         Prompt injection cannot cross this layer

agentbox <command> [options]

Commands:
  run       Run an agent in a sandbox
  validate  Validate a manifest file
  kill      Terminate a running agent
  audit     View agent audit logs
  verify    Verify audit log integrity
  vault     Manage encrypted credentials
  serve     Start the REST API server
  version   Show version

Examples:
  agentbox validate manifests/email-sorter.yaml
  agentbox run --manifest manifests/email-sorter.yaml python agent.py
  agentbox kill agent-abc123
  agentbox audit --log logs/email-sorter.log --deny
  agentbox audit --log logs/email-sorter.log --last 1h
  agentbox verify logs/email-sorter.log
  agentbox vault add ANTHROPIC_API_KEY
  agentbox vault list
  agentbox vault delete OLD_KEY
  agentbox serve :8081

# List running agents
curl http://localhost:8081/api/agents

# Start an agent
curl -X POST http://localhost:8081/api/agents \
  -H "Content-Type: application/json" \
  -d '{"manifest":"manifests/email-sorter.yaml","command":["python","agent.py"]}'

# Kill an agent
curl -X DELETE http://localhost:8081/api/agents/abc123

# Query audit log
curl "http://localhost:8081/api/audit?deny=true&agent=email-sorter"

{"id":1,"hash":"a3f2...","prev_hash":"genesis","timestamp":"2026-05-05T09:00:00Z","agent_id":"abc123","agent_name":"email-sorter","event_type":"agent_start","allowed":true,"resource":"manifests/email-sorter.yaml"}
{"id":2,"hash":"b7c1...","prev_hash":"a3f2...","timestamp":"2026-05-05T09:00:01Z","agent_id":"abc123","agent_name":"email-sorter","event_type":"filesystem_allow","allowed":true,"resource":"read:/home/user/Documents/inbox/mail.txt","rule":"filesystem.read: ~/Documents/inbox"}
{"id":3,"hash":"d9e4...","prev_hash":"b7c1...","timestamp":"2026-05-05T09:00:01Z","agent_id":"abc123","agent_name":"email-sorter","event_type":"filesystem_deny","allowed":false,"resource":"read:/home/user/.ssh/id_rsa","rule":"filesystem.deny: ~/.ssh","reason":"path is explicitly denied"}

agentbox verify logs/email-sorter-audit.log

✅ Audit log is intact
   Entries: 47 (IDs 1–47)
   Hash chain: unbroken

# Store a secret (never logged, never in env plaintext)
agentbox vault add ANTHROPIC_API_KEY

# List stored credential names (values never shown)
agentbox vault list

# Verify a credential can be decrypted
agentbox vault test ANTHROPIC_API_KEY

# Rotate a credential
agentbox vault add ANTHROPIC_API_KEY   # add updates existing

# This agent is configured with max_duration: 5s
agentbox run --manifest manifests/timeout-test.yaml python long_running_agent.py

Agent started
tick 1
tick 2
tick 3
tick 4
tick 5
🛑 Killing agent timeout-test: duration limit exceeded: 5s
⚠️  Agent timeout-test exited code 137 in 5.2s

# Clone
git clone https://github.com/siyad01/agentbox
cd agentbox

# Build
go build -o agentbox ./cmd/agentbox/

# Run tests (27 tests, all passing)
go test ./...

# Install globally
go install ./cmd/agentbox/

agentbox/
├── cmd/agentbox/main.go          ← CLI entry point
├── internal/
│   ├── policy/
│   │   ├── manifest.go           ← YAML manifest schema
│   │   ├── parser.go             ← validation + defaults
│   │   └── engine.go             ← deny-first decision engine (20 tests)
│   ├── audit/
│   │   ├── logger.go             ← append-only SHA-256 hash-chained log
│   │   ├── verifier.go           ← tamper detection
│   │   └── reader.go             ← query + filter
│   ├── vault/
│   │   ├── store.go              ← AES-256-GCM encrypted credential store
│   │   └── injector.go           ← runtime injection (7 tests)
│   ├── sandbox/
│   │   ├── sandbox.go            ← Sandbox interface
│   │   ├── docker.go             ← Docker backend
│   │   ├── gvisor.go             ← gVisor backend (kernel-level)
│   │   ├── manager.go            ← agent lifecycle management
│   │   └── util.go               ← WSL2 detection, path helpers
│   ├── monitor/
│   │   └── enforcer.go           ← resource limits + auto-kill
│   └── api/
│       └── server.go             ← REST API on :8081
└── manifests/
    ├── email-sorter.yaml         ← production example
    └── timeout-test.yaml         ← limit enforcement example