Installation

CubePi runs on Python 3.11+. The core has three runtime dependencies: pydantic, anthropic, openai. Optional features (SQLite, Postgres, MCP, OpenTelemetry tracing) are gated behind extras so you only install what you use.

With pip

pip install cubepi

Optional extras:

pip install "cubepi[sqlite]"        # adds aiosqlite for SQLiteCheckpointer
pip install "cubepi[postgres]"      # adds asyncpg + sqlalchemy + msgpack
pip install "cubepi[mcp]"           # adds the MCP SDK for tool loaders
pip install "cubepi[tracing]"       # adds opentelemetry-sdk for Tracer / Meter
pip install "cubepi[tracing-otlp]"  # adds the OTLP/HTTP span exporter
pip install "cubepi[sqlite,mcp,tracing]"  # combine

With uv

uv is significantly faster than pip and is the recommended workflow:

uv add cubepi
uv add "cubepi[sqlite,postgres,mcp,tracing,tracing-otlp]"

In an existing uv project, uv sync re-locks the environment after edits to pyproject.toml.

With Poetry

poetry add cubepi
poetry add "cubepi[sqlite,postgres,mcp,tracing,tracing-otlp]"

Verifying the install

python -c "import cubepi; print(cubepi.__doc__)"
# cubepi — Pythonic async-native agent framework.

If you see an ImportError, your interpreter is likely < 3.11 — check python --version.

Configuring provider credentials

CubePi providers read credentials from constructor arguments. Most deployments pull them from environment variables:

import os
from cubepi.providers.anthropic import AnthropicProvider
from cubepi.providers.openai import OpenAIProvider

anthropic = AnthropicProvider(api_key=os.environ["ANTHROPIC_API_KEY"])
openai = OpenAIProvider(api_key=os.environ["OPENAI_API_KEY"])

You can also pass base_url=... to either provider to point at a self-hosted endpoint or compatible proxy (e.g. Anthropic Bedrock, LiteLLM, vLLM).

For the FauxProvider (used in tests), no credentials are required.

Choosing extras: which to install

Extra	Pulls in	Install when
(none)	core only	You only need in-memory state, no MCP, no tracing
[sqlite]	aiosqlite	Single-process app needs disk persistence
[postgres]	asyncpg, sqlalchemy, msgpack	Multi-instance / production — see Postgres guide
[mcp]	mcp	You want to mount MCP server tools into your agent
[tracing]	opentelemetry-sdk	You want OpenTelemetry traces (and optionally metrics) — see Tracing guide
[tracing-otlp]	opentelemetry-exporter-otlp-proto-http	Ship traces to an OTLP/HTTP backend (Jaeger ≥1.50, Tempo, Honeycomb, Datadog, …)
[docs]	griffe	You're building the docs site (contributors only)

Next steps

• Quick Start — your first agent in five minutes.
• Core Concepts — what Agent / Tool / Provider / Checkpointer actually mean before you start gluing them.