Skip to content
Provara

Quick Start

Start the Server

Section titled “Start the Server”

  1. Start the API server

    Terminal window
    .\scripts\start_api.ps1

    Or start manually:

    Terminal window
    uv run uvicorn src.server.main:app --host 127.0.0.1 --port 8787

    You should see:

    2025-01-15 14:30:22 | INFO     | Agent Hub API starting...
    2025-01-15 14:30:22 | INFO     | Token required: True
    2025-01-15 14:30:22 | INFO     | Pending directory: C:\provara\runtime\pending

  2. Verify it’s running

    Terminal window
    Invoke-RestMethod http://127.0.0.1:8787/status

    Expected response:

    {
      "ok": true,
      "pending_count": 0,
      "denied_count": 0,
      "token_required": true,
      "version": "0.1.0"
    }

  3. Start the approval UI (optional)

    Terminal window
    .\scripts\start_ui.ps1

    This launches the GUI where you can review and approve/deny pending commands.

Queue Your First Command

Section titled “Queue Your First Command”

Set up your token and queue a command:

Terminal window
# Load your token
$token = Get-Content runtime\agent_hub_token.txt
$headers = @{ "X-Agent-Token" = $token }


# Queue a safe read-only command
Invoke-RestMethod http://127.0.0.1:8787/plan `
  -Method Post `
  -Headers $headers `
  -ContentType "application/json" `
  -Body '{"command":"whoami","note":"testing first command"}'

Response:

{
  "pending_id": "20250115_143055_a1b2c3d4",
  "queued": true,
  "command": "whoami"
}

Review Pending Commands

Section titled “Review Pending Commands”
Terminal window
Invoke-RestMethod http://127.0.0.1:8787/pending -Headers $headers

This shows all commands waiting for approval.

Approve and Execute

Section titled “Approve and Execute”
Terminal window
# Replace with your actual pending_id
Invoke-RestMethod http://127.0.0.1:8787/approve/20250115_143055_a1b2c3d4 `
  -Method Post `
  -Headers $headers

Response:

{
  "run_id": "20250115_143122_e5f6g7h8",
  "exit_code": 0,
  "stdout": "DESKTOP-ABC\\chase\n",
  "stderr": "",
  "duration_ms": 142.5
}

Or Deny It

Section titled “Or Deny It”
Terminal window
Invoke-RestMethod http://127.0.0.1:8787/deny/20250115_143055_a1b2c3d4 `
  -Method Post `
  -Headers $headers

The command is moved to the denied archive without execution.

Using the Python SDK

Section titled “Using the Python SDK”

For programmatic access from your AI agents:

from agents.hub_tool import plan


result = plan(
    command="Get-Process python",
    note="Checking Python processes",
    timeout_s=30
)
print(f"Queued: {result['pending_id']}")

What Happens Behind the Scenes

Section titled “What Happens Behind the Scenes”

When you queue a command, Provara:

  1. Authenticates the request via the X-Agent-Token header
  2. Generates a unique pending_id with timestamp prefix
  3. Persists the command as a JSON file in runtime/pending/
  4. Returns the pending_id to the caller

When you approve:

  1. Loads the pending record from disk
  2. Validates the command against the policy engine (deny patterns first, then allow patterns)
  3. Checks the working directory is under the project root
  4. Executes the command via PowerShell with timeout enforcement
  5. Saves the result to runtime/runs/{run_id}/record.json
  6. Appends an audit entry to runtime/audit.log
  7. Returns the execution result

Next Steps

Section titled “Next Steps”