Skip to content
Provara

Scripts Reference

Overview

Section titled “Overview”

Provara includes several PowerShell scripts in the scripts/ directory for common operations. These scripts handle server management, command queueing, and approval workflows.

Server Management

Section titled “Server Management”

start_all.ps1

Section titled “start_all.ps1”

Starts both the API server and the approval UI in separate windows.

Terminal window
.\scripts\start_all.ps1 [-HostAddr "127.0.0.1"] [-Port 8787]

Parameters:

  • -HostAddr — API bind address (default: 127.0.0.1)
  • -Port — API port (default: 8787)

What it does:

  1. Sets default AGENT_HUB_TOKEN and AGENT_HUB_BASE if not set
  2. Starts the API server via uvicorn in a minimized window
  3. Starts the approval UI in a normal window

start_api.ps1

Section titled “start_api.ps1”

Starts only the FastAPI server:

Terminal window
.\scripts\start_api.ps1

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

start_ui.ps1

Section titled “start_ui.ps1”

Starts only the approval GUI:

Terminal window
.\scripts\start_ui.ps1

Runs uv run python .\src\ui\main.py.

Hub Client Library (hub.ps1)

Section titled “Hub Client Library (hub.ps1)”

A PowerShell module providing functions for interacting with the Provara API. Source it to use the functions:

Terminal window
. .\scripts\hub.ps1

Functions

Section titled “Functions”

Invoke-HubPending

Section titled “Invoke-HubPending”

List all pending commands:

Terminal window
Invoke-HubPending [-BaseUrl "http://127.0.0.1:8787"]

Invoke-HubPlan

Section titled “Invoke-HubPlan”

Queue a command for approval:

Terminal window
Invoke-HubPlan -Command "Get-Process python" [-Cwd (Get-Location)] [-TimeoutS 60] [-Note ""]

Parameters:

  • -Command — Required. The PowerShell command to queue.
  • -Cwd — Working directory (defaults to current location)
  • -TimeoutS — Timeout in seconds (default: 60)
  • -Note — Optional note for the approver

Invoke-HubApprove

Section titled “Invoke-HubApprove”

Approve a pending command:

Terminal window
Invoke-HubApprove -PendingId "20250115_143022_a1b2c3d4" [-BaseUrl "http://127.0.0.1:8787"]

Invoke-HubPlanScript

Section titled “Invoke-HubPlanScript”

Stage a script in workspace/inbox/ and queue it for execution:

Terminal window
Invoke-HubPlanScript -ScriptName "check.ps1" -ScriptContent $script [-Cwd ...] [-TimeoutS 300] [-Note ""]

What it does:

  1. Creates the workspace/inbox/ directory if needed
  2. Writes the script content to workspace/inbox/{ScriptName}
  3. Queues a powershell -File command via Invoke-HubPlan

Helper Functions

Section titled “Helper Functions”
  • Get-HubToken — Reads the token from runtime/agent_hub_token.txt
  • Get-HubBaseUrl — Normalizes the API base URL

Quick Queue Script (hub_plan.ps1)

Section titled “Quick Queue Script (hub_plan.ps1)”

A shortcut for queueing commands from the command line:

Terminal window
.\scripts\hub_plan.ps1 "Get-Process python"

Internally delegates to app/client_plan.py.

Approval Script (approve_latest.ps1)

Section titled “Approval Script (approve_latest.ps1)”

Approves the most recent pending command:

Terminal window
.\scripts\approve_latest.ps1

Agent Integration (fetch_agents.ps1)

Section titled “Agent Integration (fetch_agents.ps1)”

Located in agents/, this script handles agent-specific operations.

Workspace Scripts

Section titled “Workspace Scripts”

workspace/inbox/smoketest.ps1

Section titled “workspace/inbox/smoketest.ps1”

A basic smoke test that can be queued through Provara:

Terminal window
# Run via Provara
Invoke-HubPlanScript -ScriptName "smoketest.ps1" -ScriptContent (Get-Content .\workspace\inbox\smoketest.ps1 -Raw)

Quick Operations Cheat Sheet

Section titled “Quick Operations Cheat Sheet”
Terminal window
# Start everything
.\scripts\start_all.ps1


# Check server status
Test-NetConnection 127.0.0.1 -Port 8787


# Check pending queue
Invoke-RestMethod http://127.0.0.1:8787/pending `
  -Headers @{ "X-Agent-Token" = (Get-Content runtime\agent_hub_token.txt) }


# Queue a manual command
Invoke-RestMethod http://127.0.0.1:8787/plan -Method Post `
  -Headers @{ "X-Agent-Token" = $env:AGENT_HUB_TOKEN } `
  -ContentType application/json `
  -Body '{"command":"whoami","note":"manual"}'


# View recent runs
Get-ChildItem runtime\runs | Sort LastWriteTime -Desc | Select -First 5


# Kill stuck server
Get-Process uvicorn -ErrorAction SilentlyContinue | Stop-Process -Force

Next Steps

Section titled “Next Steps”