> ## Documentation Index
> Fetch the complete documentation index at: https://docs.honeyhive.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Self-Hosting Overview
> Deploy HoneyHive in your private cloud or on-premise environment.
HoneyHive offers self-hosted deployments for organizations with strict privacy, security, or compliance requirements. Both the Control Plane and Data Plane are deployed in your environment, giving you full control over all infrastructure and data.
Self-hosted deployments are managed through our Enterprise team. Contact [sales@honeyhive.ai](mailto:sales@honeyhive.ai) to get started.
### Deployment models
We support two deployment models:
| Model | Description |
| ------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| **BYOC** (Bring Your Own Cloud) | We deploy HoneyHive's Kubernetes cluster in a dedicated cloud account you provision (AWS, GCP, or Azure). |
| **BYOVPC** (Bring Your Own VPC) | We deploy HoneyHive's Kubernetes cluster within your existing VPC, with VPC peering to your infrastructure. |
Both models give you full network isolation and control over data residency.
### Supported platforms
| Cloud Provider | Kubernetes | Deployment |
| -------------- | -------------- | ---------------- |
| AWS | EKS | Terraform + Helm |
| GCP | GKE | Terraform + Helm |
| Azure | AKS | Terraform + Helm |
| On-premise | RKE, OpenShift | Helm |
Need a different platform? Let us know.
### What's included
During setup, we work with your security and infrastructure teams to:
* Review network architecture and data flow against your policies
* Configure Terraform modules and Helm charts to meet your requirements
* Deploy the cluster and validate the installation
* Set up VPC peering (for BYOVPC) or PrivateLink
* Integrate SAML/SSO with your identity provider
See [Platform Architecture](/v2/platform-architecture) for details on how these components work together. For data classification, flow boundaries, and retention controls, see [Data Flow & Residency](/v2/setup/self-hosted/data-flow). For security controls, access policies, and compliance scope specific to self-hosted deployments, see [Self-Hosted Security](/v2/setup/self-hosted/security). For the general security posture and certifications, see [Security](/v2/setup/security).
### SDK Configuration
In federated deployments, the Control Plane and Data Plane may run at different URLs. The SDK client accepts separate CP and DP base URLs, though not every SDK surface routes through the CP URL yet - currently it is used on the events read path. For span ingestion and most API calls, `HH_API_URL` is the primary endpoint.
#### Environment Variables
```bash theme={null}
# Data Plane URL - used for span/event ingestion (required)
export HH_API_URL="https://dp.your-company.honeyhive.ai"
# Control Plane URL (optional) - accepts a separate CP endpoint,
# though not all SDK surfaces route through it yet.
# Defaults to HH_API_URL if not set.
export HH_CP_API_URL="https://cp.your-company.honeyhive.ai"
export HH_API_KEY="your-api-key"
```
#### SDK Parameters
You can also pass URLs directly when initializing the SDK client:
```python theme={null}
from honeyhive import HoneyHive
import os
client = HoneyHive(
api_key=os.getenv("HH_API_KEY"),
base_url="https://dp.your-company.honeyhive.ai",
cp_base_url="https://cp.your-company.honeyhive.ai",
)
```
For the tracer, use `server_url`:
```python theme={null}
from honeyhive import HoneyHiveTracer
import os
tracer = HoneyHiveTracer.init(
api_key=os.getenv("HH_API_KEY"),
project="my-project",
server_url="https://dp.your-company.honeyhive.ai",
)
```
The client resolves `HH_CP_API_URL` (falling back to `HH_API_URL`) for CP-bound requests, but not every SDK surface uses it yet. For now, most operations - including tracer session creation - still go through `HH_API_URL`. Set `HH_CP_API_URL` if your deployment splits CP and DP hosts so the SDK is ready when full routing support lands.
#### Resolution Order
The SDK resolves URLs in this order (first match wins):
| Plane | Resolution order |
| ----------------- | ------------------------------------------------------------------------------------------------------------ |
| **Data Plane** | `base_url` parameter → `HH_API_URL` env var → `https://api.dp1.us.honeyhive.ai` |
| **Control Plane** | `cp_base_url` parameter → `HH_CP_API_URL` env var → `HH_API_URL` env var → `https://api.dp1.us.honeyhive.ai` |
For cloud-hosted HoneyHive (default), you don't need to set any URL - both planes share `https://api.dp1.us.honeyhive.ai`. Separate URLs are only needed for self-hosted federated deployments where the CP and DP run on different hosts.
### Maintenance and Support
Self-hosted deployments include:
* **Dedicated implementation** - Setup and deployment led by our forward-deployed engineering team
* **Guided upgrade process with versioned changelogs** - Versioned releases with migration guides and patch diffs provided for your team to review and apply
* **Custom support packages** - Tailored support availability and incident response policies to meet your organization's requirements
For Day 2 operational procedures including upgrades, monitoring, backup, scaling, and incident response, see the [Operations Guide](/v2/setup/self-hosted/operations).
### Get started
Supported dependency versions and required operators.
Access controls, encryption, network policies, and compliance scope.
Data classification, flow boundaries, and retention controls.
Day 2 procedures: upgrades, monitoring, backup, and incident response.
Reach out to discuss your deployment requirements.