Honcho on Cubeship

Honcho is a persistent memory service for AI agents. It stores conversations, extracts observations and builds context that agents can retrieve across sessions.

This template installs Honcho v3.1.2 with authenticated HTTPS access, a background worker, PostgreSQL with pgvector, and Redis. It can provide shared memory to a Hermes on your VPS and another Hermes on your Mac.

What it creates

Resource	Purpose	Limit
honcho app	API on port 8000, exposed on your chosen domain. Runs migrations before serving requests.	1 CPU / 2 GiB
deriver app	Extracts memories, generates summaries and processes background jobs. Waits for the API before starting.	1 CPU / 2 GiB
postgres app	PostgreSQL 17 with pgvector 0.8.2, stored in a volume at /var/lib/postgresql/data.	1 CPU / 1 GiB
honcho-redis database	Managed Redis 7.4 for caching and coordination.	0.5 CPU / 256 MiB

Only the API has a public domain. PostgreSQL and Redis are reachable on the instance's internal network; the worker has no public endpoint.

Requires Cubeship 0.7.0 or newer and an admin to install: the API and worker build a small wrapper around Honcho's official image. The image is pinned to a multi-platform digest supporting Linux amd64 and arm64. Cubeship runs each image's own entrypoint, so the wrapper handles dependency readiness, migrations and the choice of API or worker.

What you are asked

Input	What to provide
Where the Honcho API answers	A domain pointed at your Cubeship instance.
Your OpenAI API key	A key with access to gpt-5.4-mini and text-embedding-3-small, the defaults in this Honcho version.
The key Honcho signs access tokens with	Generated by Cubeship. Keep it unchanged across updates.
The password Honcho uses for its database	Generated by Cubeship. Keep it unchanged once the database has initialized.

Self-hosting stores Honcho's data on your instance. Its default memory processing still sends content to OpenAI and incurs model usage charges. Other providers and OpenAI-compatible endpoints can be configured using Honcho's per-feature model settings on both the API and worker; see the upstream configuration.

Create an access token

Authentication is enabled from the first start. The generated jwtSecret is the signing secret, not the API key to give Hermes.

In the Cubeship terminal for the honcho app, run Honcho's bundled token generator to create a token scoped to the shared hermes workspace:

/app/.venv/bin/python scripts/generate_jwt.py --workspace hermes --print-only

Save the returned token and use it as the Honcho apiKey. It can create and access the hermes workspace, but cannot access other workspaces. You can run the command separately for each agent. This token has no expiry; changing AUTH_JWT_SECRET invalidates all existing tokens.

Connect Hermes on your VPS and Mac

On each Hermes installation, enable the Honcho memory provider:

hermes memory setup

Choose Honcho and its self-hosted configuration. In the active profile's honcho.json ($HERMES_HOME/honcho.json, normally ~/.hermes/honcho.json), use your HTTPS URL and workspace token. The default profile configuration is:

{
  "baseUrl": "https://memory.example.com",
  "apiKey": "YOUR_WORKSPACE_TOKEN",
  "hosts": {
    "hermes": {
      "enabled": true,
      "workspace": "hermes",
      "peerName": "lucas",
      "aiPeer": "hermes-vps"
    }
  }
}

Use the same baseUrl, workspace and peerName on your Mac, and change aiPeer to hermes-mac. Replace lucas with your own stable user identity. For a named Hermes profile, keep the host key generated by its setup wizard (for example, hermes.work) instead of replacing it with hermes.

If you also use Telegram or another messaging gateway, configure userPeerAliases to map your messaging identity to the same peerName. Otherwise that channel may build memory for a different user. Restart the gateway and start a new Desktop session after changing configuration. See Hermes's Honcho integration and memory provider settings.

Both agents can now contribute to and retrieve context about the same user. Their local files, skills, session databases and current chat context remain separate. Enabling a provider does not import all previous conversations. Computer Use still runs on the Mac; use Hermes A2A separately if the VPS agent should delegate tasks to it.

Check the installation

Opening https://YOUR_DOMAIN/health should return {"status":"ok"} without a token. This route confirms the API process is ready, not that an LLM request will succeed. The API reference is at https://YOUR_DOMAIN/docs; this template does not install a Honcho management dashboard.

Check hermes memory status on each agent, then use Hermes to save a test fact and search for it from the other agent. Allow the deriver time to process the conversation. If it does not appear, inspect the deriver app's logs for provider errors and verify the workspace and user identities match.

Data and updates

PostgreSQL contains conversations, embeddings, memory and the background queue. It runs as an app because Cubeship's managed Postgres image has no pgvector. Back up its volume from the app's settings. Managed database SQL dump and restore actions do not apply to this Postgres app. Redis is a cache, not the source of truth for memories.

Keep PostgreSQL and the API at one replica. Before upgrading Honcho, back up PostgreSQL and stop the deriver; update the API and let its migrations finish, then update/start the deriver. Schema migrations may make a rollback to an older Honcho image unsafe without restoring the matching backup. Do not change the embedding model or dimensions without Honcho's documented migration procedure.

Uninstall with data preservation to keep the Postgres volume and Redis. Deleting the volume deletes the memory stored in it.

Template maintenance

The Dockerfile pins upstream Honcho v3.1.2 to its published image digest. The manifest's API and deriver both build this template repository at v1.0.0. For a new release, update both ref values to the tag being published.

Run python3 -m unittest discover -s tests -v for the startup checks. Validate template.yaml using Cubeship's product/template.Validate before publishing. The validator's no-health warnings for Postgres and the deriver, and its unreachable-app warning for the deriver, are expected: neither serves an HTTP health route, and the deriver consumes work rather than receiving requests. The catalog requires this manifest, this README and icon.png in a public repository named cubeship-honcho-template, with topic cubeship-template and a GitHub release. The catalog indexes published releases automatically; see this template's releases.

Honcho v3.1.2's bundled token generator writes an ISO timestamp for --expires, but its JWT verifier expects a numeric expiry. The setup command above omits that option so the generated token works with this pinned version.

The icon is rendered from Honcho's official favicon.