First Version
This commit is contained in:
@@ -0,0 +1,185 @@
|
||||
# Honcho — self-hosted Docker package
|
||||
|
||||
This folder contains a ready-to-run Docker Compose setup for [Honcho](https://honcho.dev),
|
||||
the memory server used by the personal-agent's Honcho plugin
|
||||
([`src/plugin/honcho/`](../src/plugin/honcho/)).
|
||||
|
||||
---
|
||||
|
||||
## What runs
|
||||
|
||||
| Service | Image | Port | Role |
|
||||
| --- | --- | --- | --- |
|
||||
| `api` | `ghcr.io/plastic-labs/honcho:latest` | **8000** | REST API (the endpoint personal-agent talks to) |
|
||||
| `deriver` | same image | — | Background worker: extracts conclusions, summaries, peer representations |
|
||||
| `db` | `pgvector/pgvector:pg17` | 5432 (internal) | PostgreSQL + pgvector (vector search) |
|
||||
| `redis` | `redis:7-alpine` | 6379 (internal) | Cache for session context |
|
||||
|
||||
Data is stored in named Docker volumes (`honcho_db`, `honcho_redis`) and survives container restarts.
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- **Docker** ≥ 24 with **Compose** plugin (`docker compose version`)
|
||||
- An LLM API key (OpenAI by default; OpenRouter and Ollama also supported — see [LLM providers](#llm-providers))
|
||||
|
||||
---
|
||||
|
||||
## Quick start
|
||||
|
||||
```sh
|
||||
# 1. Copy the env template
|
||||
cp .env.example .env
|
||||
|
||||
# 2. Set your LLM key (minimum required)
|
||||
# Open .env and fill in LLM_OPENAI_API_KEY=sk-...
|
||||
|
||||
# 3. Start all services (detached)
|
||||
docker compose up -d
|
||||
|
||||
# 4. Verify the API is up
|
||||
curl http://localhost:8000/health
|
||||
# → {"status":"ok"}
|
||||
|
||||
# 5. Open interactive API docs
|
||||
open http://localhost:8000/docs
|
||||
```
|
||||
|
||||
The first startup takes ~30 s while Docker pulls the images and the database runs migrations.
|
||||
|
||||
---
|
||||
|
||||
## Connect personal-agent
|
||||
|
||||
Enable the Honcho plugin in personal-agent by asking the main agent or using the REST API:
|
||||
|
||||
```http
|
||||
PUT /api/plugins/honcho
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"enabled": true,
|
||||
"config": {
|
||||
"base_url": "http://localhost:8000",
|
||||
"api_key": "",
|
||||
"workspace_id": "personal-agent"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- `api_key` — leave empty when `HONCHO_AUTH_TOKEN` is not set in `.env`.
|
||||
- `workspace_id` — any string; used to namespace workspaces inside Honcho.
|
||||
|
||||
---
|
||||
|
||||
## LLM providers
|
||||
|
||||
Honcho needs an LLM to run the **deriver** (background memory extraction). The API itself
|
||||
works without it, but no long-term conclusions will be built.
|
||||
|
||||
### OpenAI (default)
|
||||
|
||||
```dotenv
|
||||
LLM_OPENAI_API_KEY=sk-...
|
||||
```
|
||||
|
||||
Defaults to `gpt-4o-mini` for text generation and `text-embedding-3-small` for embeddings.
|
||||
|
||||
### OpenRouter
|
||||
|
||||
```dotenv
|
||||
LLM_OPENAI_API_KEY=sk-or-...
|
||||
DERIVER_MODEL_CONFIG__TRANSPORT=openai
|
||||
DERIVER_MODEL_CONFIG__MODEL=openai/gpt-4o-mini
|
||||
DERIVER_MODEL_CONFIG__OVERRIDES__BASE_URL=https://openrouter.ai/api/v1
|
||||
```
|
||||
|
||||
Gives access to many models (Anthropic, Mistral, Gemini, …) on a single key.
|
||||
|
||||
### Ollama (fully local — no data leaves the machine)
|
||||
|
||||
Requires [Ollama](https://ollama.com) running on the host with a function-calling model
|
||||
and an embedding model:
|
||||
|
||||
```sh
|
||||
ollama pull llama3.3:70b
|
||||
ollama pull nomic-embed-text
|
||||
```
|
||||
|
||||
```dotenv
|
||||
LLM_OPENAI_API_KEY=ollama
|
||||
DERIVER_MODEL_CONFIG__TRANSPORT=openai
|
||||
DERIVER_MODEL_CONFIG__MODEL=llama3.3:70b
|
||||
DERIVER_MODEL_CONFIG__OVERRIDES__BASE_URL=http://host.docker.internal:11434/v1
|
||||
LLM_EMBEDDING_API_KEY=ollama
|
||||
LLM_EMBEDDING_BASE_URL=http://host.docker.internal:11434/v1
|
||||
LLM_EMBEDDING_MODEL=nomic-embed-text
|
||||
```
|
||||
|
||||
`host.docker.internal` resolves to the host machine from inside the container (works on
|
||||
macOS and Windows; on Linux add `--add-host=host.docker.internal:host-gateway` to the
|
||||
compose service if needed).
|
||||
|
||||
---
|
||||
|
||||
## Useful commands
|
||||
|
||||
```sh
|
||||
# Start / stop
|
||||
docker compose up -d
|
||||
docker compose down
|
||||
|
||||
# Follow logs
|
||||
docker compose logs -f api
|
||||
docker compose logs -f deriver
|
||||
|
||||
# Restart only the API after a config change
|
||||
docker compose restart api
|
||||
|
||||
# Stop and wipe all data (destructive!)
|
||||
docker compose down -v
|
||||
|
||||
# Upgrade to a newer Honcho image
|
||||
docker compose pull
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Build from source (alternative)
|
||||
|
||||
If the published image is unavailable or you want to run unreleased code:
|
||||
|
||||
```sh
|
||||
# Clone the official Honcho repository next to this folder
|
||||
git clone https://github.com/plastic-labs/honcho honcho-src
|
||||
|
||||
# In docker-compose.yml, replace the api/deriver `image:` lines with:
|
||||
# build:
|
||||
# context: ./honcho-src
|
||||
|
||||
docker compose up -d --build
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Symptom | Likely cause | Fix |
|
||||
| --- | --- | --- |
|
||||
| `api` container exits immediately | DB not ready | Check `docker compose logs db`; wait for "database system is ready" |
|
||||
| `deriver` keeps restarting | Invalid LLM key or unreachable endpoint | Check `docker compose logs deriver`; verify `.env` |
|
||||
| `curl http://localhost:8000/health` returns connection refused | Wrong port or container not started | Run `docker compose ps`; check `HONCHO_PORT` in `.env` |
|
||||
| personal-agent logs `honcho: session_context failed` | API unreachable | Verify `base_url` in plugin config; check firewall / VPN |
|
||||
| Conclusions not appearing after several chats | Deriver not running | Run `docker compose logs deriver`; check LLM key |
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
- [Honcho GitHub](https://github.com/plastic-labs/honcho)
|
||||
- [Honcho docs](https://docs.honcho.dev)
|
||||
- [Self-hosting guide (official)](https://docs.honcho.dev/v3/contributing/self-hosting)
|
||||
- [personal-agent Honcho plugin docs](../docs/honcho.md)
|
||||
- [personal-agent Memory architecture](../docs/memory.md)
|
||||
Reference in New Issue
Block a user