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
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:
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/honcho
# 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:
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_DB=honcho \
-e POSTGRES_USER=postgres \
-e POSTGRES_PASSWORD=postgres \
-p 5432:5432 \
-d pgvector/pgvector:pg15
3. Create Database and Enable Extensions
Connect to PostgreSQL and set up the database:
# Connect to PostgreSQL
psql -U postgres
# Create database and enable extensions
CREATE DATABASE honcho;
\c honcho
CREATE EXTENSION IF NOT EXISTS vector;
CREATE EXTENSION IF NOT EXISTS pg_trgm;
\q
Create a .env
file with your settings:
Edit .env
with your configuration:
# Database connection
DB_CONNECTION_URI=postgresql+psycopg://postgres:postgres@localhost:5432/honcho
# 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
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
- Change the port in your configuration:
FASTAPI_PORT=8001
- 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
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