Skip to main content
Installation should be boring; save the drama for your first query.

​
1. Motivation

A polyglot data project already has enough moving parts. HeavenBase keeps its base installation small, then lets you add provider and database extras only when your workspace needs them. The shortest supported path is pip install heavenbase, followed by one hb setup. The remaining sections help you choose an environment, optional extras, and a verification route without turning installation into architecture.

​
2. 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.

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 32 database backends: See Database integrations and Vector database integrations for setup guides.

​
4. Installation

HeavenBase supports multiple package managers. Choose based on your workflow preferences.
HeavenBase 0.1.2.2 is published on PyPI. Use pip, uv, or Poetry; Conda-forge packages are not published yet.

​
4.1. Install from PyPI

Choose your package manager from any of the following: pip:
uv:
poetry:
Conda-forge:
Conda-forge packages are not published for 0.1.2.2 yet; use pip, uv, or Poetry for the current release.

​
4.2. Optional Extras

Install additional database and development dependencies on demand: pip:
uv:
poetry:
Conda-forge:
Optional extras are PyPI package extras. Use pip, uv, or Poetry until Conda-forge packages are published.

​
5. Install from Source

Clone the repository and install using your preferred method:
pip (editable, recommended for development):
All extras from source:
uv:
poetry:
conda:

​
6. Initialize

Run setup once after installation. It initializes the default Context Registry, Capsule storage, and a durable default workspace definition:
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.

​
7. Verify Installation

Quick config test:
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:
Now we are ready to forward to the next chapter: First LLM — quickly use LLMs for chat, embeddings, sessions, and Python API calls.

​
Summary

  • Install the base package first and add extras only for the integrations you use.
  • Run hb setup once to initialize Context-owned configuration and workspace metadata.
  • Verify the CLI version before configuring providers or starting a workshop.

​
Further Exploration

Next steps: