Deploy Honcho

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.
• The worker may restart once or twice on first deploy. The honcho-deriver worker initialises the database when it first starts and can collide with the API doing the same, so Railway may restart it once or twice. This is normal; 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.