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

---
title: 'Local Environment Setup'
sidebarTitle: 'Local Environment'
description: 'Set up a local Honcho environment for development or contributing'
icon: 'computer'
---

<Info>
**Building with Honcho?** The fastest way to get started is the [hosted service](https://app.honcho.dev) — no infrastructure to manage, free tier included. This guide is for **contributors** and developers who need a local instance for development or testing.
</Info>

This guide sets up a local Honcho environment for development and 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**

## LLM Provider Setup

Honcho uses LLMs for memory extraction, summarization, dialectic chat, and dream consolidation. The server will **fail to start** until a provider is configured — this is intentional so you don't get a running server that silently does no reasoning.

Each feature needs a `PROVIDER` and `MODEL`. You set these in your `.env` file (see `.env.template` for the full list).

<Warning>
All Honcho agents (deriver, dialectic, dream) use tool calling. Your models must support the OpenAI tool calling format.
</Warning>

### Provider Options

| Provider | Endpoint | Use case |
|---|---|---|
| `custom` | Any OpenAI-compatible API (OpenRouter, Together, Fireworks, LiteLLM, Ollama) | Single key, many models |
| `vllm` | vLLM self-hosted models | Local inference |
| `google` | Google Gemini (direct) | Direct vendor API |
| `anthropic` | Anthropic Claude (direct) | Direct vendor API |
| `openai` | OpenAI (direct) | Direct vendor API |
| `groq` | Groq (direct) | Direct vendor API |

### Example: OpenRouter

```bash
LLM_OPENAI_COMPATIBLE_BASE_URL=https://openrouter.ai/api/v1
LLM_OPENAI_COMPATIBLE_API_KEY=sk-or-v1-...
LLM_EMBEDDING_PROVIDER=openrouter

DERIVER_PROVIDER=custom
DERIVER_MODEL=google/gemini-2.5-flash-lite

SUMMARY_PROVIDER=custom
SUMMARY_MODEL=google/gemini-2.5-flash

DIALECTIC_LEVELS__minimal__PROVIDER=custom
DIALECTIC_LEVELS__minimal__MODEL=google/gemini-2.5-flash-lite
DIALECTIC_LEVELS__low__PROVIDER=custom
DIALECTIC_LEVELS__low__MODEL=google/gemini-2.5-flash-lite
DIALECTIC_LEVELS__medium__PROVIDER=custom
DIALECTIC_LEVELS__medium__MODEL=anthropic/claude-haiku-4-5
DIALECTIC_LEVELS__high__PROVIDER=custom
DIALECTIC_LEVELS__high__MODEL=anthropic/claude-haiku-4-5
DIALECTIC_LEVELS__max__PROVIDER=custom
DIALECTIC_LEVELS__max__MODEL=anthropic/claude-haiku-4-5

DREAM_PROVIDER=custom
DREAM_MODEL=anthropic/claude-sonnet-4-20250514
DREAM_DEDUCTION_MODEL=anthropic/claude-haiku-4-5
DREAM_INDUCTION_MODEL=anthropic/claude-haiku-4-5
```

Model names depend on your endpoint. OpenRouter uses `vendor/model` format. Swap any model for another available on your provider.

### Example: Self-Hosted (vLLM / Ollama)

```bash
# vLLM
LLM_VLLM_BASE_URL=http://localhost:8000/v1
LLM_VLLM_API_KEY=not-needed
DERIVER_PROVIDER=vllm
DERIVER_MODEL=your-model-name

# Ollama (uses custom provider)
LLM_OPENAI_COMPATIBLE_BASE_URL=http://localhost:11434/v1
LLM_OPENAI_COMPATIBLE_API_KEY=ollama
DERIVER_PROVIDER=custom
DERIVER_MODEL=llama3.3:70b
```

Set `PROVIDER` and `MODEL` for each feature the same way.

### Example: Direct Vendor Keys

Leave the provider overrides commented out in `.env`. Set individual API keys and the code defaults will route to the correct vendor per feature:

```bash
LLM_GEMINI_API_KEY=...       # deriver, summary, dialectic minimal/low
LLM_ANTHROPIC_API_KEY=...    # dialectic medium/high/max, dream
LLM_OPENAI_API_KEY=...       # embeddings
```

See the [Configuration Guide](./configuration) for the full reference.

## Docker Setup (Recommended)

Docker Compose handles the database, Redis, and Honcho server. The compose file **builds the image from source** (there is no pre-built image on Docker Hub). This requires Docker with BuildKit enabled — see [Troubleshooting](./troubleshooting#docker-build-fails-with-permission-errors) if the build fails.

### 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 configure your LLM provider — see [LLM Provider Setup](#llm-provider-setup) above. The database connection is already set in `docker-compose.yml.example`. Auth is disabled by default (`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
```

The compose file starts five services: **api** (port 8000), **deriver** (background worker), **database** (PostgreSQL with pgvector, port 5432), **redis** (port 6379), and **grafana** (port 3000, for monitoring when `METRICS_ENABLED=true`). Redis caching is available but disabled by default (`CACHE_ENABLED=false`).

### 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` — configure your LLM provider (see [LLM Provider Setup](#llm-provider-setup) above) and set the database connection:

```bash
DB_CONNECTION_URI=postgresql+psycopg://postgres:postgres@localhost:5432/postgres
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`

### LLM Providers
- Ensure your provider endpoint and API key are configured (see [LLM Provider Setup](#llm-provider-setup))
- All features are independently configurable — see the [Configuration Guide](./configuration) for per-feature model overrides

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