Honcho (Coolify Compose)

Self-hosted Honcho — open-source memory for stateful agents — packaged as a Docker Compose stack for Coolify.

Upstream: plastic-labs/honcho. This repository ships deployment configuration only.

Architecture

Service	Role
api	HTTP API on port 8000 (Coolify proxy target)
deriver	Background memory worker (observations, summaries, dreaming)
database	PostgreSQL + pgvector
redis	Cache

Messages are stored by the API. The deriver calls an external OpenAI-compatible LLM endpoint to build memory. No model runs inside this stack.

External LLM (required)

All deriver / dialectic / summary / dream / embedding calls use the OpenAI-compatible HTTP protocol (transport=openai) pointed at a custom base URL. Traffic goes to that URL, not to OpenAI, unless the base URL is OpenAI’s.

Set these in Coolify → Environment Variables:

Variable	Example	Purpose
LLM_BASE_URL	https://llm.example.com/v1	Gateway base URL (include /v1 if the gateway expects it)
LLM_API_KEY	gateway secret	Mapped internally to LLM_OPENAI_API_KEY (protocol name only)
LLM_MODEL	my-chat-model	Chat / tool-calling model id
LLM_EMBEDDING_MODEL	snowflake-arctic-embed:latest	Embedding model id (free default on Nous-style gateways)
LLM_EMBEDDING_DIMENSIONS	1024	Must match the embedding model output size

Chat models must support tool calling (function calling). Gateways that lack OpenAI structured-output json_schema keep the default DERIVER_STRUCTURED_OUTPUT_MODE=json_object.

If embeddings are unavailable on the gateway, set EMBED_MESSAGES=false (search quality drops).

Embedding dimensions

Alembic creates pgvector columns at 1536. On API start this compose runs migrations, then configure_embeddings.py --yes so the schema matches LLM_EMBEDDING_DIMENSIONS (default 1024 for snowflake-arctic-embed:latest).

This compose uses volume pgdata_v1024 so the first boot can ALTER empty columns. Changing dims again after durable embeds exist needs another fresh volume.

Security

Setting	Default	Notes
AUTH_USE_AUTH	true	JWT required on API calls
AUTH_JWT_SECRET	Coolify SERVICE_PASSWORD_API	Signing secret; do not rotate casually
CORS_ORIGINS	public API URL	Override with a JSON array if browsers need extra origins

HTTPS is provided by Coolify’s reverse proxy. Database and Redis are internal-only (no published ports).

Mint a client token

After a healthy deploy, in the Coolify terminal for the api container:

# Do NOT pass --expires on Honcho v3.0.x — PyJWT rejects the ISO-string
# exp claim and every request returns 401 Invalid JWT.
/app/.venv/bin/python scripts/generate_jwt.py --admin --print-only

Use that value as Authorization: Bearer <token> or as the SDK / agent API key when pointing tools at this instance.

Scoped tokens (workspace / peer / session) are supported; see upstream scripts/generate_jwt.py. For time-limited keys, mint via POST /v3/keys after an admin JWT works, or wait for an upstream fix to --expires.

Deploy on Coolify

1. Create a Docker Compose resource from this repository (docker-compose.yml at repo root).
2. Assign a domain to the api service (port 8000).
3. Set LLM_BASE_URL, LLM_API_KEY, LLM_MODEL, and LLM_EMBEDDING_MODEL.
4. Deploy. Check GET /health on the domain (process up only; does not prove LLM reachability).
5. Mint a JWT (above) and configure agents / SDKs.

Coolify env note: values Coolify already stored are not overwritten when compose defaults change. Update Environment Variables in the UI after pulling this revision.

Optional: HONCHO_VERSION (default v3.0.12) to pin a different GHCR tag.

Client / tool usage

from honcho import Honcho

honcho = Honcho(
    workspace_id="example-workspace",
    base_url="https://honcho.example.com",
    api_key="<jwt-from-generate_jwt>",
)

export HONCHO_URL=https://honcho.example.com
export HONCHO_API_KEY=<jwt-from-generate_jwt>

Agent integrations (Claude Code plugin, OpenClaw, Hermes, etc.) should use the same base URL and JWT as the API key for a self-hosted authenticated instance.

License note

Honcho upstream is AGPL-3.0. Operators running the image remain subject to upstream licensing.