Installing Honcho from Scratch on Debian — No Docker Required

2026-07-03 10:07:32 - No Comments

Honcho is an agent memory layer that gives persistent cross-session memory to AI agents. Instead of rebuilding knowledge every time you start a new session, Honcho remembers user preferences, tracks behavioral patterns, and builds a profile over time — all self-hosted with no third-party cloud dependencies.

First we ensure that our system is up to date.

sudo apt update
sudo apt upgrade

Next we install the required packages: Git, build tools, curl, PostgreSQL, and Python venv support.

export DEBIAN_FRONTEND=noninteractive

sudo apt-get install -y git build-essential curl postgresql python3-venv

We verify PostgreSQL is running. On Debian Trixie this gives you PostgreSQL 17 and Python 3.13.

pg_lsclusters -H
# Should show: 17/main/online (or whatever version)

Next we need the pgvector extension, which Honcho uses to store vector embeddings alongside relational data. The package name depends on your PostgreSQL version.

PG_VERSION=$(pg_lsclusters -H | tail -1 | awk '{print $1}')

sudo apt-get install -y postgresql-${PG_VERSION}-pgvector

If the apt package doesn't exist for your version, you can build from source:

sudo apt-get install -y postgresql-${PG_VERSION}-dev gcc make
cd /tmp && git clone --depth 1 https://github.com/pgvector/pgvector.git
cd pgvector && make clean && make && sudo make install

Create Database and Honcho User

Now we create the database user and give it everything it needs. We switch to the PostgreSQL user and enter the shell.

sudo -i -u postgres
psql

Next we add the new Honcho database, user, enable the pgvector extension, and grant privileges.

CREATE USER honcho_user WITH PASSWORD 'honcho_pass';
CREATE DATABASE honcho OWNER honcho_user;
\connect honcho;
CREATE EXTENSION IF NOT EXISTS vector;
GRANT ALL PRIVILEGES ON DATABASE honcho TO honcho_user;
ALTER SCHEMA public OWNER TO honcho_user;
GRANT ALL ON SCHEMA public TO honcho_user;

After we exit PostgreSQL and return to our normal user.

Verify pgvector is loaded:

psql --user=postgres -d honcho -c "SELECT extname, extversion FROM pg_extension WHERE extname = 'vector';"
# Expected: vector | 0.8.x

Install uv

Honcho uses uv for Python package management, which is the fastest way to install and manage Python dependencies.

curl -LsSf https://astral.sh/uv/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"

Verify:

which uv && echo "uv $(uv --version)"
# Expected: /home/youruser/.local/bin/uv  uv 0.x.x

Clone Honcho and Install Dependencies

One thing to watch out for — some VM builders mount /tmp as a tmpfs backed by RAM, typically around half of total RAM. The uv sync command extracts Python wheels to /tmp, and the largest package alone can fill that space instantly. You'll see "No space left on device" even though your ext4 partition has GBs free. We set an alternate temp directory:

export TMPDIR="$HOME/.uv-tmp"
mkdir -p "$TMPDIR"

Next we clone the Honcho repository and install dependencies.

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

uv sync --link-mode=copy

Run Database Migrations

We need to tell Honcho where the database is before migrations can run, then apply the schema.

export DB_CONNECTION_URI="postgresql+psycopg://honcho_user:honcho_pass@localhost/honcho"

uv run alembic upgrade head

You should see schema migration output and a clean exit. If it fails you'll get a Python traceback.

Configure Honcho

Next we create our environment file with all the configuration.

vi ~/honcho/.env

We need a few sections here — database connection, security settings, Ollama routing for each model config type, and server binding.

# Database connection
DB_CONNECTION_URI=postgresql+psycopg://honcho_user:honcho_pass@localhost/honcho

# Disable auth, telemetry, and message embedding to keep things lightweight
AUTH_USE_AUTH=false
SENTRY_ENABLED=false
TELEMETRY_ENABLED=false
EMBED_MESSAGES=false

# Ollama routing (OpenAI-compatible transport)
LLM_OPENAI_API_KEY=ollama
LLM_OPENAI_BASE_URL=http://node7.ea.org:11434/v1

# Deriver model — runs background processing of the message queue
DERIVER_MODEL_CONFIG__MODEL=deriver-qwen3-8b

# Summary model — generates session summaries
SUMMARY_MODEL_CONFIG__MODEL=qwen3.5:4b

# Dialectic levels — reasoning depth for honcho_reasoning calls
DIALECTIC_LEVELS__minimal__MODEL_CONFIG__MODEL=qwen3.5:4b
DIALECTIC_LEVELS__low__MODEL_CONFIG__MODEL=qwen3.5:9b
DIALECTIC_LEVELS__medium__MODEL_CONFIG__MODEL=qwen3.6:27b
DIALECTIC_LEVELS__high__MODEL_CONFIG__MODEL=qwen3.6:27b
DIALECTIC_LEVELS__max__MODEL_CONFIG__MODEL=qwen3.6:27b

# Dream model — DEDUCTION generates observations, INDUCTION generates representations
DREAM_DEDUCTION_MODEL_CONFIG__MODEL=qwen3.6:27b
DREAM_INDUCTION_MODEL_CONFIG__MODEL=qwen3.6:27b

# Server binding — 0.0.0.0 makes it accessible from outside the VM
HOST=0.0.0.0
PORT=8000

After we save and exit, we verify the config loads without errors:

cd ~/honcho
export DB_CONNECTION_URI="postgresql+psycopg://honcho_user:honcho_pass@localhost/honcho"
uv run python3 -c "from src.config import settings; print('Config OK, deriver model:', settings.DERIVER.MODEL_CONFIG.model)"
# Expected: Config OK, deriver model: qwen2.5:0.5b

Create Systemd Services

We need two services, both running as your normal user. The API service starts first; the deriver only boots after the API is ready.

Next we open the service file for the API server.

sudo vi /etc/systemd/system/honcho-api.service

The service definition below points to our Honcho code, loads the environment file, and starts the FastAPI application on port 8000.

[Unit]
Description=Honcho API (FastAPI)
After=network.target postgresql.service
Wants=postgresql.service

[Service]
Type=simple
User=woden
Group=woden
WorkingDirectory=/home/woden/honcho
EnvironmentFile=/home/woden/honcho/.env
ExecStart=/home/woden/.local/bin/uv run fastapi run src/main.py --port 8000
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

After we save and exit, we open the second service file for deriver.

sudo vi /etc/systemd/system/honcho-deriver.service

The deriver service starts after both PostgreSQL and the API are running. It processes the message queue in the background — generating observations, conclusions, and peer representations through LLM calls to our Ollama instance.

[Unit]
Description=Honcho Deriver Worker
After=honcho-api.service postgresql.service
Wants=honcho-api.service postgresql.service

[Service]
Type=simple
User=woden
Group=woden
WorkingDirectory=/home/woden/honcho
EnvironmentFile=/home/woden/honcho/.env
ExecStart=/home/woden/.local/bin/uv run python -m src.deriver
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

Reload the daemon configuration, start and enable both services. The first run with uv takes about 40 seconds to resolve dependencies, so we wait between starting the two:

sudo systemctl daemon-reload
sudo systemctl enable honcho-api.service honcho-deriver.service
sudo systemctl start honcho-api.service
sudo systemctl start honcho-deriver.service

Verify both are running:

systemctl list-units --no-legend | grep honcho
# Expected:
#   honcho-api.service        loaded active running  Honcho API (FastAPI)
#   honcho-deriver.service    loaded active running  Honcho Deriver Worker

Final Health Check

Health check:

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

The Swagger API docs are available in your browser at:

http://localhost:8000/docs

Verify the deriver is actively processing:

journalctl -u honcho-deriver.service --no-pager -n 10
# Expected: "Starting deriver queue processor", "ReconcilerScheduler started"