Installation & Setup

Installation & Setup#

This guide will help you install Pantheon and set up your environment.

Requirements#

  • Python 3.10 or higher

  • API keys for LLM providers (e.g., OpenAI, Anthropic)

Using pip#

Install from PyPI#

pip install pantheon-agents

With Optional Dependencies#

# RAG/vector search support (LlamaIndex, Qdrant)
pip install "pantheon-agents[knowledge]"

# PantheonClaw mobile gateway channels
pip install "pantheon-agents[claw]"

# Multiple extras
pip install "pantheon-agents[knowledge,claw]"

Install from Source#

For the latest development version:

git clone https://github.com/aristoteleo/PantheonOS.git
cd PantheonOS
pip install -e ".[knowledge]"

Development Installation#

For contributors and developers:

git clone https://github.com/aristoteleo/PantheonOS.git
cd PantheonOS

# Using uv (recommended)
uv sync --extra dev --extra knowledge

# Run tests
uv run pytest tests/

# Or using pip
pip install -e ".[dev,knowledge]"
pytest tests/

Optional Dependencies#

Pantheon provides several optional dependency groups:

Extra

Description

knowledge

RAG and vector search support (LlamaIndex, Qdrant, fastembed)

slack

Slack bot integration (slack-sdk, slack-bolt)

r

R language support for notebooks (rpy2, requires R installed)

dev

Development and testing tools (pytest, pytest-asyncio)

Core Dependencies#

Core dependencies are automatically installed:

  • Provider Adapters - Unified LLM API access (OpenAI, Anthropic, etc.)

  • Rich - Terminal UI and formatting

  • prompt-toolkit - Interactive REPL

  • NATS - Distributed messaging

  • FastMCP - Model Context Protocol support

  • LanceDB - Vector database for embeddings

  • Crawl4AI - Web content extraction

Environment Setup#

API Keys#

Set up your LLM provider API keys:

# OpenAI (default)
export OPENAI_API_KEY="your-openai-key"

# Anthropic Claude
export ANTHROPIC_API_KEY="your-anthropic-key"

# Or use other supported providers
export GEMINI_API_KEY="your-gemini-key"

You can also create a .env file in your project directory:

# .env
OPENAI_API_KEY=your-openai-key
ANTHROPIC_API_KEY=your-anthropic-key

Custom API Endpoint (Third-party Proxy)#

If you use a third-party API proxy service, set these two universal variables to route all LLM calls through your proxy:

export LLM_API_BASE="https://your-proxy.com/v1"
export LLM_API_KEY="your-proxy-key"

You can also configure this interactively:

# Launch the setup wizard at any time
pantheon setup

# Or use /keys in the REPL
/keys 0 https://your-proxy.com/v1 your-proxy-key

Priority: Provider-specific keys (e.g. OPENAI_API_KEY) take precedence over universal keys. When LLM_API_BASE is active, LLM_API_KEY is preferred over provider-specific keys.

Configuration Directory#

Pantheon uses a layered configuration system:

  1. User global config: ~/.pantheon/

  2. Project config: ./.pantheon/

Create a project configuration:

mkdir .pantheon
# Configuration files will be auto-generated on first run

Starting the REPL#

The easiest way to start using Pantheon:

# With uv
pantheon cli

# With pip installation
pantheon cli

This launches the interactive REPL with default settings.

Verifying Installation#

import asyncio
from pantheon.agent import Agent

async def main():
    agent = Agent(
        name="test",
        instructions="Say hello!"
    )
    response = await agent.run("Hello!")
    print(response.content)

asyncio.run(main())

Troubleshooting#

Common Issues#

ImportError: No module named ‘pantheon’

Ensure you’ve activated your virtual environment or installed the package correctly.

API key errors

Make sure your API keys are set as environment variables or in a .env file.

NATS connection errors

For distributed features, ensure NATS server is running. For local development, Pantheon can auto-start a NATS server if nats-server-bin is installed.

Next Steps#