Local Environment Setup

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: curl -LsSf https://astral.sh/uv/install.sh | sh or brew install uv
Git - Download from git-scm.com
Docker (required for Docker setup, not needed for manual setup) - Download from docker.com

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 Setup

Honcho uses LLMs for memory extraction, summarization, dialectic chat, and dreaming. The server will fail to start without a provider configured. If you keep the built-in defaults, you only need one API key: all text-generation features default to openai / gpt-5.4-mini, and embeddings default to openai / text-embedding-3-small. Any OpenAI-compatible endpoint works too — OpenRouter, Together, Fireworks, Ollama, vLLM, or LiteLLM. Models must support tool calling (function calling). After copying .env.template to .env, the default setup is:

# Required for the built-in defaults
LLM_OPENAI_API_KEY=sk-...

If you want a different model or an OpenAI-compatible proxy, uncomment and edit the relevant *_MODEL_CONFIG__TRANSPORT, *_MODEL_CONFIG__MODEL, and *_MODEL_CONFIG__OVERRIDES__BASE_URL lines in the Deriver, Dialectic, Summary, and Dream sections. For example:

LLM_OPENAI_API_KEY=sk-or-v1-...

DERIVER_MODEL_CONFIG__TRANSPORT=openai
DERIVER_MODEL_CONFIG__MODEL=google/gemini-2.5-flash
DERIVER_MODEL_CONFIG__OVERRIDES__BASE_URL=https://openrouter.ai/api/v1

For recommended model tiers per feature, using multiple providers, or direct vendor API keys, see the Configuration Guide.

Community quick-start: elkimek/honcho-self-hosted provides a one-command installer with pre-configured model tiers, interactive provider setup, and Hermes Agent integration.

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 if the build fails. The compose file is production-oriented by default (ports bound to 127.0.0.1, restart policies, caching enabled). For development, uncomment the source mounts and monitoring services inside the file.

1. Clone the Repository

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

2. Set Up Environment Variables

Copy the example environment file and configure it:

cp .env.template .env

Edit .env and configure your LLM provider — see LLM Setup above. The database connection is set in the compose file. Auth is disabled by default (AUTH_USE_AUTH=false).

3. Start the Services

cp docker-compose.yml.example docker-compose.yml
docker compose up -d --build

The first build takes a few minutes (compiling from source). Subsequent starts are fast. This starts four services: api (port 8000), deriver (background worker), database (PostgreSQL with pgvector, port 5432), and redis (port 6379). All ports are bound to 127.0.0.1. Redis caching is enabled by default. For development, uncomment the source mount and monitoring sections inside docker-compose.yml to enable live reload, Prometheus, and Grafana.

4. Verify

Migrations run automatically on startup.

# Check all containers are running
docker compose ps

# Health check (confirms the process is up)
curl http://localhost:8000/health

# Check the deriver is processing (look for "polling" or "processing" in logs)
docker compose logs deriver --tail 20

For a full end-to-end test, see Verify Your Setup below.

Manual Setup

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

1. Clone and Install Dependencies

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):

brew install postgresql
brew install pgvector

Ubuntu/Debian:

sudo apt update
sudo apt install postgresql postgresql-contrib
# Install pgvector extension (see pgvector docs for your version)

Windows: Download from postgresql.org

Option B: Docker PostgreSQL

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:

# Connect to PostgreSQL
psql -U postgres

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

Least-privilege database roles. Honcho runs CREATE EXTENSION IF NOT EXISTS vector before migrations and again at startup, so if the role in DB_CONNECTION_URI can’t create extensions, both fail with a privilege error — IF NOT EXISTS doesn’t help, because Postgres checks the privilege first.Run the statement above once as a superuser (or rds_superuser) and the application role needs no extension privileges. See Troubleshooting if you hit this.

4. Configure Environment

Create a .env file with your settings:

cp .env.template .env

Edit .env — configure your LLM provider (see LLM Setup above) and set the database connection:

DB_CONNECTION_URI=postgresql+psycopg://postgres:postgres@localhost:5432/postgres
AUTH_USE_AUTH=false
LOG_LEVEL=DEBUG

5. Run Database Migrations

# Run migrations to create tables
uv run alembic upgrade head

6. Start the Server

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

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)

Create a Supabase project at supabase.com
Enable pgvector extension in the SQL editor:
CREATE EXTENSION IF NOT EXISTS vector;
Get your connection string from Settings > Database
Update your .env file with the connection string

Railway

Create a Railway project at railway.app
Add a PostgreSQL service
Enable pgvector in the PostgreSQL console
Get your connection string from the service variables
Update your .env file

Verify Your Setup

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

1. Health Check

curl http://localhost:8000/health
# {"status":"ok"}

Note: /health only confirms the process is running. It does not check database or LLM connectivity.

2. Smoke Test (database + API)

This confirms the database connection, migrations, and API are all working:

# Create a workspace
curl -s -X POST http://localhost:8000/v3/workspaces \
  -H "Content-Type: application/json" \
  -d '{"name": "test"}' | python3 -m json.tool

If you get back a workspace object with an id, your database is connected and migrations ran correctly.

3. API Documentation

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

4. Test with SDK

from honcho import Honcho

client = Honcho(
    base_url="http://localhost:8000",
    workspace_id="test"
)

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 SDK
from honcho import Honcho

client = Honcho(
    base_url="http://localhost:8000",
)

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

const client = new Honcho({
  baseUrl: 'http://localhost:8000',
});

Next Steps

Configure Honcho: Visit the Configuration Guide for model tiers, provider options, and tuning
Explore the API: Check out the API Reference
Try the SDKs: See our guides for examples
Join the community: Discord

Troubleshooting

Running into issues? See the Troubleshooting Guide 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

The default compose file is already production-oriented — ports bound to 127.0.0.1, restart policies, caching enabled.

Security

Set AUTH_USE_AUTH=true and generate a JWT secret with python scripts/generate_jwt_secret.py

Use HTTPS via a reverse proxy in front of Honcho. Example with Caddy (automatic TLS):

honcho.example.com {
    reverse_proxy localhost:8000
}

Or with nginx:

server {
    listen 443 ssl;
    server_name honcho.example.com;
    ssl_certificate /etc/letsencrypt/live/honcho.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/honcho.example.com/privkey.pem;
    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Secure your database with strong credentials and restrict network access
The production compose binds PostgreSQL and Redis to 127.0.0.1 only — they are not accessible from the network

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

The production compose enables Redis caching by default (CACHE_ENABLED=true)
For the development compose, enable manually: CACHE_ENABLED=true
Configure CACHE_URL to point to your Redis instance (or use a managed Redis service)

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 API keys are configured (see LLM Setup)
For alternative providers or per-feature model overrides, see the Configuration Guide

Monitoring

Enable Prometheus metrics with METRICS_ENABLED=true. The API exposes /metrics on port 8000, the deriver on port 9090 (internal to its container — not published to the host by default).
Enable Sentry error tracking with SENTRY_ENABLED=true
The development compose includes Prometheus (host port 9090) and Grafana (host port 3000) for scraping and dashboards. Uncomment those services to enable them.

Backups

Set up regular PostgreSQL backups:

# One-off backup
docker compose exec database pg_dump -U postgres postgres > backup-$(date +%Y%m%d).sql

# Restore
cat backup.sql | docker compose exec -T database psql -U postgres postgres

Deploying on Fly.io

The API can be deployed on Fly.io. Follow the Fly.io getting-started docs to set up your account and install flyctl. A sample fly.toml is included in the repo for convenience.

The included fly.toml does not provision a PostgreSQL database. Stand one up separately (Fly Postgres, Supabase, Neon, or another managed provider) and set DB_CONNECTION_URI to point at it.

Once flyctl is set up, from the repo root:

flyctl launch --no-deploy           # follow the prompts and edit as you see fit
cat .env | flyctl secrets import    # load secrets from .env
flyctl deploy                       # deploy

Back up your .env or config.toml configuration files

​Overview

​Prerequisites

​Required Software

​Database Options

​LLM Setup

​Docker Setup (Recommended)

​1. Clone the Repository

​2. Set Up Environment Variables

​3. Start the Services

​4. Verify

​Manual Setup

​1. Clone and Install Dependencies

​2. Set Up PostgreSQL

​Option A: Local PostgreSQL Installation

​Option B: Docker PostgreSQL

​3. Enable Extensions

​4. Configure Environment

​5. Run Database Migrations

​6. Start the Server

​7. Start the Background Worker (Deriver)

​Cloud Database Setup

​Supabase (Recommended)

​Railway

​Verify Your Setup

​1. Health Check

​2. Smoke Test (database + API)

​3. API Documentation

​4. Test with SDK

​Connect Your Application

​Update SDK Configuration

​Next Steps

​Troubleshooting

​Production Considerations

​Security

​Scaling the Deriver

​Caching

​Database Migrations

​LLM Providers

​Monitoring

​Backups

​Deploying on Fly.io

Overview

Prerequisites

Required Software

Database Options

LLM Setup

Docker Setup (Recommended)

1. Clone the Repository

2. Set Up Environment Variables

3. Start the Services

4. Verify

Manual Setup

1. Clone and Install Dependencies

2. Set Up PostgreSQL

Option A: Local PostgreSQL Installation

Option B: Docker PostgreSQL

3. Enable Extensions

4. Configure Environment

5. Run Database Migrations

6. Start the Server

7. Start the Background Worker (Deriver)

Cloud Database Setup

Supabase (Recommended)

Railway

Verify Your Setup

1. Health Check

2. Smoke Test (database + API)

3. API Documentation

4. Test with SDK

Connect Your Application

Update SDK Configuration

Next Steps

Troubleshooting

Production Considerations

Security

Scaling the Deriver

Caching

Database Migrations

LLM Providers

Monitoring

Backups

Deploying on Fly.io