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: pip install uv (manages Python installations automatically)
Git - Download from git-scm.com
Docker (optional) - 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

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

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 set your API keys (if using LLM features):

# Optional API keys (required for LLM features)
OPENAI_API_KEY=your-openai-api-key
ANTHROPIC_API_KEY=your-anthropic-api-key

# Database will be created automatically by Docker
DB_CONNECTION_URI=postgresql+psycopg://postgres:postgres@database:5432/postgres


# Disable auth for local development
AUTH_USE_AUTH=false

3. Start the Services

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

# Start PostgreSQL and Honcho
docker compose up -d

4. Verify It’s Working

Check that both services are running:

docker compose ps

Test the Honcho API:

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

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 extensions on the default database
CREATE EXTENSION IF NOT EXISTS vector;
CREATE EXTENSION IF NOT EXISTS pg_trgm;
\q

4. Configure Environment

Create a .env file with your settings:

cp .env.template .env

Edit .env with your configuration:

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

# Optional API keys (required for LLM features)
OPENAI_API_KEY=your-openai-api-key
ANTHROPIC_API_KEY=your-anthropic-api-key

# Development settings
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
fastapi dev src/main.py

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

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;
CREATE EXTENSION IF NOT EXISTS pg_trgm;

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

2. API Documentation

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

3. Test with SDK

Create a simple test script:

from honcho import Honcho

# Connect to your local instance
client = Honcho(base_url="http://localhost:8000")

# 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 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 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
Try the SDKs: See our guides for examples
Configure Honcho: Visit the Configuration Guide for detailed settings
Join the community: Discord

Troubleshooting

Common Issues

Database Connection Errors

Ensure PostgreSQL is running
Verify the connection string format: postgresql+psycopg://...
Check that pgvector extension is installed

API Key Issues

Verify your OpenAI and Anthropic API keys are valid
Check that the keys have sufficient credits/quota

Port Already in Use

Pass a different port to FastAPI or stop other services using port 8000

Docker Issues

Ensure Docker is running
Check container logs: docker compose logs
Restart containers: docker compose down && docker compose up -d

Migration Errors

Ensure the database exists and pgvector is enabled
Check database permissions
Run migrations manually: uv run alembic upgrade head

Getting Help

GitHub Issues: Report bugs
Discord: Join our community
Documentation: Check the Configuration Guide for detailed settings

Production Considerations

When self-hosting for production, consider:

Security: Enable authentication, use HTTPS, secure your database
Scaling: Use connection pooling, consider load balancing
Monitoring: Set up logging, error tracking, health checks
Backups: Regular database backups, disaster recovery plan
Updates: Keep Honcho and dependencies updated

​Overview

​Prerequisites

​Required Software

​Database Options

​Docker Setup (Recommended)

​1. Clone the Repository

​2. Set Up Environment Variables

​3. Start the Services

​4. Verify It’s Working

​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

​Cloud Database Setup

​Supabase (Recommended)

​Railway

​Verify Your Setup

​1. Health Check

​2. API Documentation

​3. Test with SDK

​Connect Your Application

​Update SDK Configuration

​Next Steps

​Troubleshooting

​Common Issues

​Getting Help

​Production Considerations