Architecture Overview

System Architecture

Provara follows a queue-approve-execute pattern where every command flows through a human gate before reaching the operating system.

┌─────────────────────────────────────────────────────────────────┐
│                         Provara Server                          │
│                                                                 │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────────┐   │
│  │  FastAPI  │  │  Policy  │  │  Runner  │  │  Audit Log   │   │
│  │  Routes   │──│  Engine  │──│ (PowerShell)│──│ (JSON-line) │   │
│  └──────────┘  └──────────┘  └──────────┘  └──────────────┘   │
│       │                                          │              │
│  ┌──────────┐                            ┌──────────────┐      │
│  │   Auth   │                            │  File System  │      │
│  │  (Token) │                            │    (Jailed)   │      │
│  └──────────┘                            └──────────────┘      │
└─────────────────────────────────────────────────────────────────┘
        ▲                                          ▲
        │                                          │
   ┌─────────┐                              ┌──────────┐
   │  Agent  │                              │  Human   │
   │  SDK    │                              │  UI      │
   └─────────┘                              └──────────┘

Components

FastAPI Server (src/server/main.py)

The core API server exposes all endpoints for command management. It handles:

• Request routing — Maps HTTP methods to handler functions
• Authentication — Token verification via X-Agent-Token header
• Rate limiting — Per-client request throttling
• CORS — Restricted to localhost origins
• SSE — Server-Sent Events for real-time notifications

The server runs on uvicorn and binds to 127.0.0.1:8787 by default.

Policy Engine (src/server/exec/policy.py)

The security backbone. Implements a three-stage validation:

1. Deny check — 26 regex patterns that block dangerous operations (checked first)
2. Allow check — Category-based patterns that match permitted command intent
3. CWD jail — Verifies working directory is under the project root

See Security Model for full details.

Command Runner (src/server/exec/runner.py)

Executes approved commands through PowerShell with:

• Policy re-validation — Double-checks policy before execution
• Subprocess isolation — subprocess.run() with capture_output=True
• Timeout enforcement — Configurable per-command timeouts (default 60s, max 3600s)
• Result capture — stdout, stderr, exit code, duration
• Execution records — Saved as JSON to runtime/runs/{run_id}/record.json
• Audit logging — Appended to runtime/audit.log

Configuration (src/server/config.py)

Centralized settings using pydantic-settings:

• Environment variable loading with AGENT_HUB_ prefix
• .env file support
• Auto-detection of project root
• Cached settings with @lru_cache

Agent SDK (agents/hub_tool.py)

A minimal Python client library:

def plan(command, note=None, cwd=None, timeout_s=300) -> dict:
    """Queue a command for human approval."""

Uses httpx for HTTP requests. Reads AGENT_HUB_BASE and AGENT_HUB_TOKEN from environment.

Request Flow

1. Command Queueing (POST /plan)

Agent → POST /plan → Token auth → Generate pending_id → Save JSON → Return pending_id

The pending record is persisted as a JSON file in runtime/pending/:

{
  "command": "Get-Process python",
  "cwd": null,
  "timeout_s": 300,
  "note": "checking processes",
  "pending_id": "20250115_143022_a1b2c3d4",
  "ts": 1705329022.123,
  "queued_at": "2025-01-15T14:30:22"
}

2. Command Approval (POST /approve/{id})

Human → POST /approve → Token auth → Load record → Policy check → Execute → Save result → Audit log

If the policy engine blocks the command, a 403 error is returned with the deny reason. The command is not removed from pending on policy failure.

3. Command Denial (POST /deny/{id})

Human → POST /deny → Token auth → Load record → Move to denied/ → Return confirmation

The denied record is enriched with denied_ts and denied_at timestamps.

Data Model

Pydantic Models

Model	Purpose
PlanRequest	Incoming command submission
PlanResponse	Command queued confirmation
StatusResponse	Server health overview
HealthResponse	Detailed system metrics
PendingItem	Pending command details
ApproveResponse	Execution results
DenyResponse	Denial confirmation
ErrorResponse	Error details

Execution Result (RunResult)

class RunResult(TypedDict):
    run_id: str          # Unique execution identifier
    cwd: str             # Working directory used
    command: str          # The executed command
    exit_code: int        # Process exit code (0 = success)
    stdout: str           # Standard output
    stderr: str           # Standard error
    ts: float             # Unix timestamp
    duration_ms: float    # Execution time in milliseconds

Security Layers

Provara implements defense-in-depth:

Layer	Mechanism
Authentication	Token-based API access
Rate Limiting	Per-IP request throttling
Policy Engine	Deny-first command validation
CWD Jail	Working directory restriction
File Jail	Path validation for file API
CORS	Localhost-only origin restriction
Audit Trail	Immutable operation log
Timeout	Per-command execution limits

Next Steps

• Security Model — Deep dive into the policy engine
• API Reference — Complete endpoint documentation