> ## Documentation Index
> Fetch the complete documentation index at: https://ahvn.top/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> System requirements, recommended software, installation, and first-run verification for HeavenBase.

<Note>
  ***TL;DR:** `pip install heavenbase && hb setup` is all you need.*
</Note>

<br />

## 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.

<br />

## 2. Recommended Software

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

* **[Docker](https://www.docker.com/)** — spin up local databases (PostgreSQL, MySQL, Milvus, etc.) for testing or production.
* **[Portkey](https://portkey.ai/)** or **[Bifrost](https://github.com/RubikSQL/Bifrost)** — LLM gateways for observability, caching, failover, and key management across multiple providers.
* **[Ollama](https://ollama.com/)**, **[LM Studio](https://lmstudio.ai/)**, or **[oMLX](https://omlx.ai/)** — 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](/integrations/databases) and [Vector database integrations](/integrations/vector-databases) for setup guides.

<br />

## 3. Installation

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

<Info>
  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.
</Info>

<br />

### 3.1. Install from PyPI

Choose your package manager from any of the following:

**pip:**

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
pip install heavenbase
```

**uv:**

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
uv pip install heavenbase
```

**poetry:**

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
poetry add heavenbase
```

**Conda-forge:**

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

<br />

### 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:**

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
pip install "heavenbase[full]"
```

**uv:**

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
uv pip install "heavenbase[full]"
```

**poetry:**

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
poetry add heavenbase --extras "full"
```

**Conda-forge:**

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

<br />

## 4. Install from Source

Clone the repository and install using your preferred method:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
git clone https://github.com/Magolor/HeavenBase.git
cd HeavenBase
```

**pip (editable, recommended for development):**

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
pip install -e ".[dev]"
```

**All extras from source:**

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
pip install -e ".[full]"
```

**uv:**

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
uv pip install -e "."
```

**poetry:**

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
poetry install
```

**conda:**

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
conda env create -f environment.yml
conda activate hvnb
```

<br />

## 5. Initialize

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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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/`.

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

<br />

## 6. Verify Installation

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
hb --version
# 0.1.1.5
```

Quick config test:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 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](/quickstart/first-llm) — quickly use LLMs for chat, embeddings, sessions, and Python API calls.

<br />

## Further Exploration

<Tip>
  **Next steps:**

  * [First LLM](/quickstart/first-llm) — CLI chat, embeddings, sessions, and Python API
  * [LLM provider integrations](/integrations/llm-providers) — switch to OpenAI, Anthropic, Ollama, or any LiteLLM-compatible provider
  * [Database integrations](/integrations/databases) — connect PostgreSQL, MySQL, DuckDB, and more
</Tip>

<br />