Skip to main content

Documentation Index

Fetch the complete documentation index at: https://ahvn.top/llms.txt

Use this file to discover all available pages before exploring further.

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 or LM Studio) may have their own hardware preferences, but HeavenBase itself is lightweight.

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 or LM Studio — run LLMs and embedding models locally. No API keys, no rate limits, full privacy.
HeavenBase ships with built-in support for 16+ database backends:
CategoryBackends
SQL databasesSQLite, PostgreSQL, MySQL, DuckDB, OceanBase, MsSQL, Oracle, Trino, StarRocks
Vector storesMilvus, LanceDB, Chroma, Pinecone, pgvector
Search / textElasticsearch
See Database integrations and Vector database integrations for setup guides.

​
3. Package manager installation

HeavenBase supports multiple package managers. Choose based on your workflow preferences.
HeavenBase is not yet published to PyPI or conda-forge. The commands below show the intended usage for when the first public release ships.

​
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: 
conda install -c conda-forge heavenbase

​
3.2. Optional extras

Install additional database and development dependencies on demand:
ExtraContentsWhen to use
devTesting, linting, docs toolchainContributor workflows
interopThird-party integrationsData interop with external systems
sqlAll SQL database drivers (PostgreSQL, MySQL, DuckDB, etc.)Production SQL workloads
fullAll extras combined: dev, interop, sqlQuick setup with everything
pip: 
pip install "heavenbase[full]"
uv: 
uv pip install "heavenbase[full]"
poetry: 
poetry add heavenbase --extras "full"
conda: 
conda install -c conda-forge heavenbase=full

​
4. Install from source

Clone the repository and install using your preferred method: 
git clone https://github.com/RubikSQL/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 LLM cache, and registers a default workspace: 
hb setup
All runtime 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 it works

hb --version

hb llm status -p chat
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: 
$ 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...

​
Further Exploration

Next steps: