honcho

环境要求

• Docker 与 Docker Compose 环境
• Postgres 数据库（需带 pgvector 扩展，可用 Supabase 或项目自带 docker-compose 模板）
• 至少一个 LLM 提供方的 API Key（Gemini / Anthropic / OpenAI）
• 若走源码非 Docker 安装，需要 uv 来创建虚拟环境并同步 Python 依赖

安装与启动步骤

1. 1克隆仓库

   从 GitHub 拉取 Honcho 源码到本地，后续所有配置与启动都在该目录内进行。

   git clone https://github.com/plastic-labs/honcho.git

   复制

2. 2复制配置模板

   进入仓库，把 docker-compose 和环境变量模板复制为实际使用的文件，不要直接改模板。

   cd honcho
   cp docker-compose.yml.example docker-compose.yml
   cp .env.template .env

   复制

3. 3填写必需环境变量

   编辑 .env：填入 Postgres 连接串 DB_CONNECTION_URI，以及所用的 LLM API Key（Gemini/Anthropic/OpenAI 至少一个）。

4. 4启动服务

   用 docker compose 拉起 Honcho 全部服务（含数据库容器），首次启动会拉取镜像，需等待片刻。

   docker compose up

   复制

5. 5SDK 指向本地服务

   把 SDK 的 base_url 指向 http://localhost:8000，用 workspace_id 区分你的应用数据。

   honcho = Honcho(workspace_id="my-app-testing", base_url="http://localhost:8000")

   复制

关键配置

如何确认成功

服务启动后，把 SDK 的 base_url 设为 http://localhost:8000 并发起一次调用，能正常返回即接入成功。

常见问题

注意事项

• README 明确给出的本地服务地址是 http://localhost:8000，SDK 的 base_url 直接指向它即可。
• 除 .env 外还支持 config.toml，可通过 cp config.toml.example config.toml 生成，按 app、db、llm、summary 等子系统分节。
• 较多配置项（日志、监控、安全等）并非必需，README 未逐项列出的参数不要臆测填写，以 docs.honcho.dev 的配置参考为准。
• 本地源码安装推荐使用虚拟环境隔离依赖，默认虚拟环境位于 honcho/.venv。