Installation - HeavenBase

TL;DR: pip install heavenbase && hb setup is all you need.

1. System Requirements

HeavenBase runs on any system with Python — no GPU, server rack, or cluster required.

Operating system: macOS, Linux, Windows. Tested on Windows 11 and macOS Sequoia.
Python: 3.10 or higher. Tested on Python 3.10 through 3.13.
Hardware: Standard consumer hardware is sufficient. Some optional dependencies (local LLM serving via Ollama, LM Studio, or oMLX) may have their own hardware preferences, but HeavenBase itself is lightweight.

2. Recommended Software

These tools are entirely optional but make the HeavenBase experience much richer:

Docker — spin up local databases (PostgreSQL, MySQL, Milvus, etc.) for testing or production.
Portkey or Bifrost — LLM gateways for observability, caching, failover, and key management across multiple providers.
Ollama, LM Studio, or oMLX — run LLMs and embedding models locally. No API keys, no rate limits, full privacy.

HeavenBase ships with built-in support for 16+ database backends:

Category	Backends
SQL databases	SQLite, PostgreSQL, MySQL, DuckDB, OceanBase, MsSQL, Oracle, Trino, StarRocks
Vector stores	Milvus, LanceDB, Chroma, Pinecone, pgvector
Search / text	Elasticsearch

See Database integrations and Vector database integrations for setup guides.

3. Installation

HeavenBase supports multiple package managers. Choose based on your workflow preferences.

HeavenBase 0.1.1.5 is the current PyPI release. Conda-forge packages are not published yet; use pip, uv, or Poetry for this release.

3.1. Install from PyPI

Choose your package manager from any of the following: pip:

pip install heavenbase

uv:

uv pip install heavenbase

poetry:

poetry add heavenbase

Conda-forge:

Conda-forge packages are not published for 0.1.1.5 yet; use pip, uv, or Poetry for the current release.

3.2. Optional Extras

Install additional database and development dependencies on demand:

Extra	Contents	When to use
`dev`	Testing, linting, and contributor tooling	Contributor workflows
`interop`	Pydantic, pandas, pyarrow, and SQLAlchemy interop helpers	Data interop with external systems
`daft`	Daft and pyarrow for dataframe-style workloads	Daft-based analytics or ETL
`sql`	SQLAlchemy (also included in base dependencies)	Explicit SQLAlchemy pin for custom stacks
`full`	Provider and database drivers (psycopg2, pgvector, lancedb, elasticsearch, litellm, …)	Production workloads with external backends

pip:

pip install "heavenbase[full]"

uv:

uv pip install "heavenbase[full]"

poetry:

poetry add heavenbase --extras "full"

Conda-forge:

Optional extras are PyPI package extras. Use pip, uv, or Poetry until Conda-forge packages are published.

4. Install from Source

Clone the repository and install using your preferred method:

git clone https://github.com/Magolor/HeavenBase.git
cd HeavenBase

pip (editable, recommended for development):

pip install -e ".[dev]"

All extras from source:

pip install -e ".[full]"

uv:

uv pip install -e "."

poetry:

poetry install

conda:

conda env create -f environment.yml
conda activate hvnb

5. Initialize

Run setup once after installation. It creates the global config store, initializes the capsule registry, and registers a default workspace:

hb setup

All package data lives under ~/.heavenbase/. More conveniently, inspect paths anytime with hb pj %/, where % maps to the heavenbase global root folder, ~/.heavenbase/.

hb setup --reset destroys all configuration, cached data, and registered workspaces. This operation is irreversible. Use only when you intend to start from scratch.

6. Verify Installation

hb --version
# 0.1.1.5

Quick config test:

hb llm status -p chat
# preset: chat
# provider: openrouter
# model: deepseek-v4-flash
# model_id: deepseek/deepseek-v4-flash
# gateway: openai

The status command prints the resolved LLM preset, provider, model, and gateway. Out of the box, it uses the system and chat preset backed by deepseek-v4-flash on OpenRouter — no config file edits needed, just setup your OPENROUTER_API_KEY in the environment and you’re good to go. Now try a test chat with the default LLM using HeavenBase README file as context:

# Setup OPENROUTER_API_KEY in your environment first, then run:
$ hb llm chat "What is HeavenBase?" -i "path:&/README.md"

# HeavenBase is a **metadata-driven data gateway** that lets AI agents interact
# with multiple databases and schema systems through a single, unified interface.
# It doesn't replace your existing stack - it sits on top of it...

Now we are ready to forward to the next chapter: First LLM — quickly use LLMs for chat, embeddings, sessions, and Python API calls.

Further Exploration

Next steps:

First LLM — CLI chat, embeddings, sessions, and Python API
LLM provider integrations — switch to OpenAI, Anthropic, Ollama, or any LiteLLM-compatible provider
Database integrations — connect PostgreSQL, MySQL, DuckDB, and more

​1. System Requirements

​2. Recommended Software

​3. Installation

​3.1. Install from PyPI

​3.2. Optional Extras

​4. Install from Source

​5. Initialize

​6. Verify Installation

​Further Exploration

1. System Requirements

2. Recommended Software

3. Installation

3.1. Install from PyPI

3.2. Optional Extras

4. Install from Source

5. Initialize

6. Verify Installation

Further Exploration