--- title: "Deploy Honcho" description: "Self-hosted memory server for AI agents (unofficial Honcho stack)" category: "AI/ML" url: https://railway.com/deploy/honcho --- # Deploy Honcho Self-hosted memory server for AI agents (unofficial Honcho stack) **[Deploy Honcho on Railway](https://railway.com/template/honcho)** Machine-readable deploy manifest (JSON, validated by TemplateCI): https://railway.com/deploy/honcho/manifest.json - **Creator:** George's Projects - **Category:** AI/ML ## Template content ### honcho-api - **Image:** ghcr.io/plastic-labs/honcho:v3.2.1 - **Start command:** `sh docker/entrypoint.sh` - **Health check:** /health - **Public domain:** Yes ### honcho-db - **Image:** pgvector/pgvector:0.8.6-pg15 ### honcho-deriver - **Image:** ghcr.io/plastic-labs/honcho:v3.2.1 - **Start command:** `/app/.venv/bin/python scripts/provision_db.py && exec /app/.venv/bin/python -m src.deriver` ## Documentation # Deploy and Host Honcho on Railway Honcho is an open-source memory layer for AI agents: it stores conversations, extracts what it learns about each user or agent in the background, and answers questions about them. This template deploys the official plastic-labs/honcho image (v3.2.1) as an API service and a background deriver worker, plus a pgvector-enabled Postgres on a persistent volume. Unofficial template, not affiliated with Plastic Labs. ## About Hosting Honcho Three services run in your project: honcho-api (the HTTP API on port 8000), honcho-deriver (the worker that turns messages into memory) and honcho-db (Postgres with pgvector, on a volume). Bring your own LLM key: set LLM_OPENAI_API_KEY when you deploy. No key is included, and you pay your LLM provider directly for memory extraction. API authentication is switched on (AUTH_USE_AUTH=true) with a generated AUTH_JWT_SECRET, so every request needs a bearer token that you create yourself (see below). Redis is optional and left out; caching falls back to memory. ## Common Use Cases - Long-term memory for a chat or coding agent - A self-hosted backend for the Honcho plugins for Hermes Agent and OpenClaw (configured on the agent side) - Per-user profiles and summaries built from conversation history ## Dependencies for Honcho Hosting - ghcr.io/plastic-labs/honcho:v3.2.1 (API and deriver, same image) - pgvector/pgvector:0.8.6-pg15 (Postgres with the pgvector extension) - An LLM provider key (OpenAI by default; Anthropic, Gemini or OpenAI-compatible endpoints are documented upstream) ### Implementation Details **Create your admin token first.** Auth is on and the admin token is not printed anywhere. Two options: 1. Open a shell in honcho-api (`railway ssh`) and run `python scripts/generate_jwt.py --admin`. For a narrower token use `--workspace NAME --expires 30d`. 2. Sign an HS256 JWT yourself with the value of AUTH_JWT_SECRET (Variables tab of honcho-api) and the payload `{"t":"","ad":true}`. Use the token as `Authorization: Bearer ` or as the API key in the Honcho SDK/CLI, with your domain as the base URL. Give agents workspace-scoped tokens rather than the admin token. Check `https:///health` after deploy. **HTTPS.** Railway terminates TLS at its edge for generated *.up.railway.app domains and custom domains (certificates are provisioned automatically), and redirects plain HTTP GET requests to HTTPS. This is Railway's platform behaviour, not a Honcho feature, and this template makes no claim about encryption inside Railway's network or about the security of Honcho itself. **Costs and limits.** The deriver runs continuously and calls your LLM provider as messages arrive. The database volume cannot be used with replicas, and redeploying the database service causes brief downtime. ### FAQ / troubleshooting - **Deploy is green but nothing gets remembered.** The deriver builds memory. Check honcho-deriver logs for LLM errors. The deriver reads the same LLM key as honcho-api. - **API logs "Missing client for ..." or crash loops.** No LLM provider key is set. Add LLM_OPENAI_API_KEY (or the Anthropic/Gemini equivalent plus matching model overrides). - **401 or "No access token provided".** Auth is on. Send `Authorization: Bearer ` and mint one as described above. - **"An unexpected error occurred" on every request.** Check the connection string prefix (it must be `postgresql+psycopg://`) and that honcho-db is running. - **One restart of the deriver or API on first deploy is expected.** Both services prepare the database on first start and can collide once; Railway restarts the one that lost the race and it then stays up. If it keeps restarting, check the logs. - **Do I need Redis?** No. Add Redis and set CACHE_ENABLED=true and CACHE_URL only for high traffic. - **Can I change the model?** Yes, with the DERIVER_MODEL_CONFIG__MODEL style variables and, for OpenAI-compatible providers, the BASE_URL overrides in the upstream .env.template. Models must support tool calling. - **Is my data safe on redeploy?** Postgres data lives on the honcho-db volume and survives redeploys. Expect brief downtime. - **How do I connect Hermes or OpenClaw?** Hermes: run `hermes memory setup`, choose honcho, enter this service's public URL and your token. OpenClaw: install `@honcho-ai/openclaw-honcho` and run `openclaw honcho setup`. ## Why Deploy Honcho on Railway? Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it. By deploying Honcho on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway. ## Similar templates - [Chat Chat](https://railway.com/deploy/-WWW5r) — Chat Chat, your own unified chat and search to AI platform. - [stella](https://railway.com/deploy/stella) — Self-host stella with web, API, Postgres, Redis, and object storage. - [Hermes Agent | OpenClaw Alternative with Dashboard](https://railway.com/deploy/hermes-agent-or-openclaw-alternative-wit) — Self-Hosted Hermes AI Agent for Telegram, Discord & Slack Open this page in a browser: https://railway.com/deploy/honcho