Skip to content
Provara

Installation

Prerequisites

Section titled “Prerequisites”
  • Python 3.12+ — Required for the server and SDK
  • uv — Recommended Python package manager (install uv)
  • PowerShell 5.1+ — Command execution backend (included with Windows)
  • Git — For cloning the repository

Install from Source

Section titled “Install from Source”

  1. Clone the repository

    Terminal window
    git clone https://github.com/hunt-info-systems/provara.git
    cd provara

  2. Create a virtual environment

    Terminal window
    uv venv
    uv sync

    This installs all required dependencies:

    PackagePurpose
    fastapiREST API framework
    uvicornASGI server
    pydanticData validation
    pydantic-settingsEnvironment-based configuration
    httpxHTTP client for agent SDK
    psutilSystem metrics for health endpoint
    richTerminal formatting
    python-dotenv.env file loading

  3. Configure environment

    Terminal window
    Copy-Item .env.example .env

    Edit .env to set your authentication token:

    Terminal window
    AGENT_HUB_TOKEN=your-secure-token-here

    Or generate one automatically:

    Terminal window
    $token = -join ((65..90) + (97..122) + (48..57) | Get-Random -Count 64 | % {[char]$_})
    $token | Set-Content runtime\agent_hub_token.txt

  4. Verify installation

    Terminal window
    uv run python -c "from src.server.main import app; print('Provara ready')"

Optional Dependencies

Section titled “Optional Dependencies”

AutoGen Integration

Section titled “AutoGen Integration”

To use Provara with Microsoft AutoGen agents:

Terminal window
uv sync --extra autogen

This adds autogen-agentchat and autogen-ext[openai].

Development Tools

Section titled “Development Tools”

For contributing or running tests:

Terminal window
uv sync --extra dev

This adds pytest, mypy, ruff, and other development tools.

Directory Structure

Section titled “Directory Structure”

After installation, your project should look like this:

provara/
├── src/
│   ├── server/          # FastAPI server
│   │   ├── main.py      # API endpoints
│   │   ├── config.py    # Configuration
│   │   └── exec/        # Execution engine
│   │       ├── policy.py    # Security policy
│   │       └── runner.py    # Command runner
│   ├── cli/             # CLI tools
│   └── ui/              # GUI application
├── agents/              # Agent integrations
│   └── hub_tool.py      # Python SDK
├── scripts/             # PowerShell utilities
├── runtime/             # Runtime data (auto-created)
│   ├── pending/         # Pending command queue
│   ├── denied/          # Denied command archive
│   ├── runs/            # Execution history
│   └── audit.log        # Audit trail
├── workspace/           # Agent workspace (jailed)
│   ├── inbox/           # Script staging
│   └── outbox/          # Output files
├── tests/               # Test suite
├── .env                 # Local configuration
├── .env.example         # Configuration template
└── pyproject.toml       # Project metadata

Next Steps

Section titled “Next Steps”