honcho/docs/v3/contributing/self-hosting.mdx

---
title: 'Local Environment Setup'
sidebarTitle: 'Local Environment'
description: 'Set up a local environment to run Honcho for development, testing, or self-hosting'
icon: 'computer'
---

This guide helps you set up a local environment to run Honcho for development, testing, or self-hosting.

## Overview

By the end of this guide, you'll have:
- A local Honcho server running on your machine
- A PostgreSQL database with pgvector extension
- Basic configuration to connect your applications
- A working environment for development or testing

## Prerequisites

Before you begin, ensure you have the following installed:

### Required Software
- **uv** - Python package manager: `pip install uv` (manages Python installations automatically)
- **Git** - [Download from git-scm.com](https://git-scm.com/downloads)
- **Docker** (optional) - [Download from docker.com](https://www.docker.com/products/docker-desktop/)

### Database Options
You'll need a PostgreSQL database with the pgvector extension. Choose one:

- **Local PostgreSQL** - Install locally or use Docker
- **Supabase** - Free cloud PostgreSQL with pgvector
- **Railway** - Simple cloud PostgreSQL hosting
- **Your own PostgreSQL server**

## Which API Keys Do I Need?

Honcho uses different LLM providers for different features. The table below shows which keys are needed for the **default** configuration. All providers are configurable per feature (see the [Configuration Guide](./configuration)).

| Feature | Default Provider | Environment Variable | Required? |
|---------|-----------------|---------------------|-----------|
| Deriver (memory extraction) | Google Gemini | `LLM_GEMINI_API_KEY` | Yes (core feature) |
| Summary generation | Google Gemini | `LLM_GEMINI_API_KEY` | Yes (core feature) |
| Dialectic minimal/low | Google Gemini | `LLM_GEMINI_API_KEY` | If using Chat API |
| Dialectic medium/high/max | Anthropic Claude | `LLM_ANTHROPIC_API_KEY` | If using Chat API |
| Dream (memory consolidation) | Anthropic Claude | `LLM_ANTHROPIC_API_KEY` | Optional |
| Message embeddings | OpenAI | `LLM_OPENAI_API_KEY` | If `EMBED_MESSAGES=true` (default) |

**Minimum for basic usage**: `LLM_GEMINI_API_KEY` + `LLM_OPENAI_API_KEY`

**Full functionality**: All three keys (Gemini, Anthropic, OpenAI)

## Docker Setup (Recommended)

The easiest way to get started is using Docker Compose, which handles both the database and Honcho server.

### 1. Clone the Repository

```bash
git clone https://github.com/plastic-labs/honcho.git
cd honcho
```

### 2. Set Up Environment Variables

Copy the example environment file and configure it:

```bash
cp .env.template .env
```

Edit `.env` and set your API keys (see [Which API Keys Do I Need?](#which-api-keys-do-i-need) above):

```bash
# Database (matches docker-compose.yml.example credentials)
DB_CONNECTION_URI=postgresql+psycopg://postgres:postgres@database:5432/postgres

# LLM API keys (see table above for which features use which provider)
LLM_GEMINI_API_KEY=your-gemini-api-key
LLM_ANTHROPIC_API_KEY=your-anthropic-api-key
LLM_OPENAI_API_KEY=your-openai-api-key

# Disable auth for local development
AUTH_USE_AUTH=false
```

### 3. Start the Services

```bash
# Copy the example docker-compose file
cp docker-compose.yml.example docker-compose.yml

# Start PostgreSQL, Redis, Honcho API, and the deriver background worker
docker compose up -d
```

> **Note:** The docker-compose file starts both the API server and the deriver (background worker) automatically. It also includes Redis (for caching, disabled by default) and Grafana (for monitoring on port 3000 when `METRICS_ENABLED=true`).

### 4. Run Database Migrations

After the containers are running, create the database tables:

```bash
docker compose exec api uv run alembic upgrade head
```

### 5. Verify It's Working

Check that both services are running:

```bash
docker compose ps
```

Test the Honcho API:

```bash
curl http://localhost:8000/health
```

You should see a response indicating the service is healthy.

## Manual Setup

For more control over your environment, you can set up everything manually.

### 1. Clone and Install Dependencies

```bash
git clone https://github.com/plastic-labs/honcho.git
cd honcho

# Install dependencies using uv (this will also set up Python if needed)
uv sync

# Activate the virtual environment
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
```

### 2. Set Up PostgreSQL

#### Option A: Local PostgreSQL Installation

Install PostgreSQL and pgvector on your system:

**macOS (using Homebrew):**
```bash
brew install postgresql
brew install pgvector
```

**Ubuntu/Debian:**
```bash
sudo apt update
sudo apt install postgresql postgresql-contrib
# Install pgvector extension (see pgvector docs for your version)
```

**Windows:**
Download from [postgresql.org](https://www.postgresql.org/download/windows/)

#### Option B: Docker PostgreSQL

```bash
docker run --name honcho-db \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=postgres \
  -p 5432:5432 \
  -d pgvector/pgvector:pg15
```

### 3. Enable Extensions

Connect to PostgreSQL and enable pgvector:

```bash
# Connect to PostgreSQL
psql -U postgres

# Enable the pgvector extension on the default database
CREATE EXTENSION IF NOT EXISTS vector;
\q
```

### 4. Configure Environment

Create a `.env` file with your settings:

```bash
cp .env.template .env
```

Edit `.env` with your configuration (see [Which API Keys Do I Need?](#which-api-keys-do-i-need) above):

```bash
# Database connection
DB_CONNECTION_URI=postgresql+psycopg://postgres:postgres@localhost:5432/postgres

# LLM API keys (see table above for which features use which provider)
LLM_GEMINI_API_KEY=your-gemini-api-key
LLM_ANTHROPIC_API_KEY=your-anthropic-api-key
LLM_OPENAI_API_KEY=your-openai-api-key

# Development settings
AUTH_USE_AUTH=false
LOG_LEVEL=DEBUG
```

### 5. Run Database Migrations

```bash
# Run migrations to create tables
uv run alembic upgrade head
```

### 6. Start the Server

```bash
# Start the development server
uv run fastapi dev src/main.py
```

The server will be available at `http://localhost:8000`.

### 7. Start the Background Worker (Deriver)

In a **separate terminal**, start the deriver background worker:

```bash
uv run python -m src.deriver
```

The deriver is essential for Honcho's core functionality. It processes incoming messages to extract observations, build peer representations, generate session summaries, and run dream consolidation. Without it, messages will be stored but no memory or reasoning will occur.

## Cloud Database Setup

If you prefer to use a managed PostgreSQL service:

### Supabase (Recommended)

1. **Create a Supabase project** at [supabase.com](https://supabase.com)
2. **Enable pgvector extension** in the SQL editor:
   ```sql
   CREATE EXTENSION IF NOT EXISTS vector;
   ```
3. **Get your connection string** from Settings > Database
4. **Update your `.env` file** with the connection string

### Railway

1. **Create a Railway project** at [railway.app](https://railway.app)
2. **Add a PostgreSQL service**
3. **Enable pgvector** in the PostgreSQL console
4. **Get your connection string** from the service variables
5. **Update your `.env` file**

## Verify Your Setup

Once your Honcho server is running, verify everything is working:

### 1. Health Check

```bash
curl http://localhost:8000/health
```

### 2. API Documentation

Visit `http://localhost:8000/docs` to see the interactive API documentation.

### 3. Test with SDK

Create a simple test script:

```python
from honcho import Honcho

# Connect to your local instance
client = Honcho(
    base_url="http://localhost:8000",
    workspace_id="my-app-testing"
)

# Create a test peer
peer = client.peer("test-user")
print(f"Created peer: {peer.id}")
```

## Connect Your Application

Now that Honcho is running locally, you can connect your applications:

### Update SDK Configuration

```python
# Python SDK
from honcho import Honcho

client = Honcho(
    base_url="http://localhost:8000",  # Your local instance
    api_key="your-api-key"  # If auth is enabled
)
```

```typescript
// TypeScript SDK
import { Honcho } from '@honcho-ai/sdk';

const client = new Honcho({
  baseUrl: 'http://localhost:8000',  // Your local instance
  apiKey: 'your-api-key'  // If auth is enabled
});
```

### Next Steps

- **Explore the API**: Check out the [API Reference](../api-reference/introduction)
- **Try the SDKs**: See our [guides](../guides) for examples
- **Configure Honcho**: Visit the [Configuration Guide](./configuration) for detailed settings
- **Join the community**: [Discord](https://discord.gg/plasticlabs)

## Troubleshooting

Running into issues? See the [Troubleshooting Guide](./troubleshooting) for detailed solutions to common problems including:

- Startup failures (missing API keys, database issues)
- Runtime errors ("An unexpected error occurred" on every request)
- Deriver not processing messages
- Database connection and migration issues
- Docker and Redis problems

**Quick checks:**
- Verify the server is running: `curl http://localhost:8000/health`
- Check logs: `docker compose logs api` (Docker) or check terminal output (manual setup)
- Ensure migrations ran: `uv run alembic upgrade head`

## Production Considerations

When self-hosting for production, consider:

### Security
- Set `AUTH_USE_AUTH=true` and generate a JWT secret with `python scripts/generate_jwt_secret.py`
- Use HTTPS via a reverse proxy (e.g., nginx, Caddy) in front of Honcho
- Secure your database with strong credentials and restrict network access

### Scaling the Deriver
- Increase `DERIVER_WORKERS` (default: 1) for higher message throughput
- You can also run multiple deriver processes across machines — they coordinate via the database queue
- Monitor deriver logs for processing backlog

### Caching
- Enable Redis caching for high-traffic environments: `CACHE_ENABLED=true`
- Requires a Redis instance (included in docker-compose, or use a managed Redis service)
- Configure `CACHE_URL` to point to your Redis instance

### Database Migrations
- Always run `uv run alembic upgrade head` after updating Honcho before starting the server
- Check current migration status with `uv run alembic current`

### API Keys
- Ensure you have the correct API keys for your configured providers (see [Which API Keys Do I Need?](#which-api-keys-do-i-need))
- All providers are configurable — see the [Configuration Guide](./configuration) to use different models or providers

### Monitoring
- Enable Prometheus metrics with `METRICS_ENABLED=true` (scraped at `/metrics` on port 8000 for API, port 9090 for deriver)
- Enable Sentry error tracking with `SENTRY_ENABLED=true`
- The docker-compose includes Grafana on port 3000 for dashboards

### Backups
- Set up regular PostgreSQL backups (pg_dump or continuous archiving)
- Back up your `.env` or `config.toml` configuration files