cubeshipd/honcho

Honcho

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

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.2.1 with authenticated HTTPS access, a background worker, a managed 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
honcho-db database	Managed PostgreSQL 17 with the `pgvector` extension.	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.9.0 or newer and an admin to install: PostgreSQL is a managed database created with the pgvector extension, which needs that release, and 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 database password is not asked for. Cubeship generates it and hands it to the API and the worker; read it from the database's own page if you need it.

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 is a managed database created with pgvector, so it is dumped, scheduled and restored from its own page like any other. Redis is a cache, not the source of truth for memories.

Older installations of this template ran PostgreSQL as an app with a volume. An existing installation is not migrated: its postgres app and volume stay where they are, and moving to the managed database means installing fresh and copying the data across with pg_dump and psql.

A database's extensions are chosen when it is created. Changing this template does not change a database that already exists. Install an extension from the database's own page.

Keep the API at one replica. Before upgrading Honcho, back up the database 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 database and Redis. Deleting the database deletes the memory stored in it.

Template maintenance

The Dockerfile pins upstream Honcho v3.2.1 to its published image digest. The manifest's API and deriver both build this directory at the cataloged commit.

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 and unreachable-app warnings for the deriver are expected: it serves no HTTP health route and consumes work rather than receiving requests. The catalog reads this directory from cubeshipd/cubeship-templates and keeps the previous valid snapshot if a commit fails validation.

The icon is rendered from Honcho's official favicon.

What this creates

honcho

https://github.com/cubeshipd/cubeship-templates

deriver

https://github.com/cubeshipd/cubeship-templates

honcho-db

Postgres 17

honcho-redis

Redis 7.4

template.yaml

# yaml-language-server: $schema=https://cubeship.dev/schema/template/v1.json
version: 1
name: 'Honcho'
# The first release whose instances create a managed Postgres with
# pgvector. Before it, the database would come up without the extension
# and Honcho's migrations would fail.
minCubeship: "0.9.0"
project: honcho

inputs:
  - key: domain
    type: domain
    label: Where the Honcho API answers
  - key: openaiApiKey
    type: secret
    label: Your OpenAI API key
    help: Honcho uses OpenAI for memory extraction, reasoning and embeddings. Model usage is billed by OpenAI.
  - key: jwtSecret
    type: secret
    label: The key Honcho signs access tokens with
    help: Keep this unchanged across updates. Generate a workspace access token after installing, as described in the README.
    generate: 48

databases:
  - key: db
    name: honcho-db
    engine: postgres
    version: "17"
    database: honcho
    # Honcho stores its embeddings as pgvector columns; its migrations
    # expect the extension to exist.
    extensions:
      - pgvector
    limits: { cpu: 1, memory: 1Gi }

  - key: redis
    name: honcho-redis
    engine: redis
    version: "7.4"
    limits: { cpu: 0.5, memory: 256Mi }

apps:
  - key: api
    name: honcho
    repo: https://github.com/cubeshipd/cubeship-templates
    ref: main:honcho
    build: dockerfile
    port: 8000
    health: /health
    domains:
      - host: ${input.domain}
    limits: { cpu: 1, memory: 2Gi }
    env:
      CUBESHIP_HONCHO_ROLE: api
      DB_CONNECTION_URI: postgresql+psycopg://${db.db.user}:${db.db.password}@${db.db.host}:${db.db.port}/${db.db.name}
      DB_POOL_SIZE: "5"
      DB_MAX_OVERFLOW: "5"
      CACHE_ENABLED: "true"
      CACHE_URL: redis://default:${db.redis.password}@${db.redis.host}:${db.redis.port}/0?suppress=true
      AUTH_USE_AUTH: "true"
      AUTH_JWT_SECRET: ${input.jwtSecret}
      LLM_OPENAI_API_KEY: ${input.openaiApiKey}
      VECTOR_STORE_TYPE: pgvector

  - key: deriver
    name: deriver
    repo: https://github.com/cubeshipd/cubeship-templates
    ref: main:honcho
    build: dockerfile
    # The deriver consumes the database queue; it serves no public HTTP API.
    limits: { cpu: 1, memory: 2Gi }
    env:
      CUBESHIP_HONCHO_ROLE: deriver
      CUBESHIP_HONCHO_API_URL: http://${app.api.internal}:${app.api.port}
      DB_CONNECTION_URI: postgresql+psycopg://${db.db.user}:${db.db.password}@${db.db.host}:${db.db.port}/${db.db.name}
      DB_POOL_SIZE: "5"
      DB_MAX_OVERFLOW: "5"
      CACHE_ENABLED: "true"
      CACHE_URL: redis://default:${db.redis.password}@${db.redis.host}:${db.redis.port}/0?suppress=true
      AUTH_USE_AUTH: "true"
      AUTH_JWT_SECRET: ${input.jwtSecret}
      LLM_OPENAI_API_KEY: ${input.openaiApiKey}
      VECTOR_STORE_TYPE: pgvector
      DERIVER_WORKERS: "1"