Skip to main content
Self-hosting is currently in alpha stage and is planned for a major revamp soon.

​
Overview

Self-hosting Aden gives you complete control over your deployment, data, and infrastructure. This guide walks you through setting up Aden using Docker Compose.

​
Prerequisites

Docker

Docker Engine 20.10+ and Docker Compose v2+

Git

Git for cloning the repository

​
Installation

​
Step 1: Clone the Repository

Get a copy of the latest Aden repository: 
git clone https://github.com/adenhq/beeline
cd beeline

​
Step 2: Run Docker Compose

Start all services using Docker Compose: 
docker compose up
This will start:
  • Aden API server
  • Database (PostgreSQL)
  • Cache layer (Redis)
  • Web dashboard

​
Step 3: Access the Dashboard

Once the services are running, access the Aden dashboard at: 
http://localhost:3000

​
Configuration

The default config.yaml file comes with sensible defaults for quick testing. You only need to modify it for production deployments or custom requirements.

​
Key Configuration Options

If you need to customize your deployment, edit the config.yaml file in the repository: Server Ports (if ports 3000/4000 are already in use): 
server:
  frontend:
    port: 3000  # Change to your desired frontend port
  backend:
    port: 4000  # Change to your desired backend port
Database Connection (for external database): 
database:
  url: postgresql://honeycomb:honeycomb@localhost:5432/honeycomb
  # Update with your database credentials and host
Security (required for production): 
auth:
  jwt_secret: change-this-to-a-secure-random-string
  # Generate a secure secret with: openssl rand -base64 32
  jwt_expires_in: 7d
CORS Settings (for production deployments): 
cors:
  origin: http://localhost:3000
  # Change to your production frontend URL
Application Environment: 
app:
  environment: development  # Change to 'production' for production
  log_level: info  # Options: debug, info, warn, error

​
Advanced Docker Compose Customization

For advanced configurations, you can also modify the docker-compose.yml file to:
  • Change port mappings
  • Add volume mounts for persistence
  • Configure resource limits
  • Set up external networks

​
Connecting Your SDKs

After deployment, configure your SDKs to point to your self-hosted instance:
Use http://localhost:4000 as the server URL for self-hosted instances.
import { instrument } from "aden-ts";

await instrument({
  apiKey: "your-api-key",
  serverUrl: "http://localhost:8080", // Your self-hosted URL. Use http://localhost:4000 instead.
  sdks: { OpenAI },
});
Learn more in the TypeScript SDK documentation.

​
Updating

To update your self-hosted Aden instance: 
# Pull latest changes
git pull origin main

# Rebuild and restart services
docker compose down
docker compose up --build

​
Troubleshooting

​
Services Won’t Start

Check Docker logs for specific errors: 
docker compose logs -f

​
Github Documentation

Visit the github Beeline documentation for more information.

​
Need Help?

Book a Discovery Call

Get expert help with your self-hosted deployment.

​
Next Steps

Quickstart Guide

Learn how to instrument your first LLM call

TypeScript SDK

Complete TypeScript documentation

Python SDK

Complete Python documentation

Cost Control

Set budgets and alerts for your deployment