Installation Guide¶

1. System Requirements¶

  • Operating System: Platform-independent

    • Tested on Windows 11, macOS Sequoia

  • Python: 3.10 or higher

    • Tested on Python 3.10, 3.11, 3.12, 3.13

  • Hardware: No specific requirements; runs on standard consumer hardware

    • Though, certain optional dependencies, especially LLM serving packages, may have their own hardware requirements or could result in performance issues (e.g., ollama)

  • Recommended Software (Optional):

    • Git for version control functionality

    • Ollama to support local large model services (with embedding features)

    • Docker for self-hosting databases and sandboxes


2. Package Manager Installation¶

AgentHeaven supports multiple package managers for flexible installation. Choose the one that best fits your workflow:

Optional Dependencies:

  • exp: experimental features and integrations, including database integration, vector engines, etc. Recommended.

  • gui: GUI tools for agent management and monitoring.

  • dev: development tools including docs generation, code formatting, testing, etc.


2.1. Quick Install¶

There are multiple ways to install AgentHeaven. You can choose only one method that suits your preferred.

Minimal installation (core only, no optional dependencies):

# pip
pip install agent-heaven

# uv
uv pip install agent-heaven

# poetry
poetry add agent-heaven

# conda
conda install -c conda-forge agent-heaven

Full installation (with all optional dependencies):

# pip
pip install "agent-heaven[exp,dev]"

# uv
uv pip install "agent-heaven[exp,dev]"

# poetry
poetry add agent-heaven --extras "exp gui dev"

# conda
conda install -c conda-forge agent-heaven[exp,dev]

2.2. Install From Source¶

Minimal installation (core only, no optional dependencies):

git clone https://github.com/RubikSQL/AgentHeaven.git
cd AgentHeaven

# pip
pip install -e "."

# uv
uv pip install -e "."

# poetry
poetry install

# conda
conda env create -f environment.yml
conda activate ahvn

Full installation (with all optional dependencies):

git clone https://github.com/RubikSQL/AgentHeaven.git
cd AgentHeaven

# pip
pip install -e ".[dev,exp,gui]"

# uv
uv pip install -e ".[dev,exp,gui]"

# poetry
poetry install --extras "dev exp gui"

# conda
conda env create -f environment-full.yml -n ahvn
conda activate ahvn

3. Verification & Initial Setup¶

After installation, verify that AgentHeaven is working correctly:

# Check if ahvn command is available
ahvn --version

# Initialize AgentHeaven (creates config files)
ahvn setup --reset

4. Documentation¶

For developers on Windows PCs, make needs to be installed (for documentation generation).


Further Exploration¶

Tip: For more information about configuration in AgentHeaven, see:

Tip: For more information about getting started with AgentHeaven, see: