Honcho for Coolify

A self-contained, public Docker Compose deployment for Honcho, designed to be installed from the Coolify graphical interface.

This repository is intentionally independent from vypdev/ai01. It contains everything required to deploy a fresh Honcho instance on a Coolify Docker destination:

• Honcho API
• Honcho Deriver worker
• PostgreSQL 15 with pgvector
• Redis with AOF persistence
• Idempotent vector-extension initialization
• Health checks and dependency ordering
• A pinned upstream Honcho source (v3.0.12)

No application secrets, database data, Hermes state, or historical memory are stored here.

Deployment model

Hermes / OpenClaw on the host
        |
        | localhost HTTP, initially port 18082
        v
Honcho API (Coolify-managed Compose application)
        |
        +-- PostgreSQL + pgvector (private Compose network)
        +-- Redis (private Compose network)
        +-- Deriver worker (private Compose network)

The Compose file binds the API to loopback by default. It does not publish PostgreSQL or Redis. Keep the API private while AUTH_USE_AUTH=false.

Coolify installation

If Coolify automatically selects main and fails before the branch selector becomes editable, use the branch-pinned GitHub URL instead:

https://github.com/vypdev/honcho-coolify/tree/master

This tells Coolify to use master when it parses the public repository. Do not leave the branch inferred from the plain repository URL in affected Coolify versions.

Build pack selection

When Coolify asks for the build pack, select:

Docker Compose

Do not select Nixpacks, Railpack, Static, or Dockerfile. This deployment contains multiple coordinated services, so the Compose build pack is required.

The repository already contains the complete docker-compose.yaml manifest. No custom Dockerfile path, Nixpacks configuration, Railpack configuration, or static-site configuration is needed.

The existing Coolify control plane uses host port 8000. Do not assign Honcho to that port. During parallel validation, Honcho uses:

Host address: 127.0.0.1
Host port:    18082
Container port: 8000

The container's port is 8000; the host port is controlled by HONCHO_API_PORT.

1. Create the application

In Coolify:

1. Create or select a project.
2. Create a new application and select the Docker Compose build pack.
3. Select the target Docker server and destination.
4. Select the public repository using the branch-pinned URL: https://github.com/vypdev/honcho-coolify/tree/master
5. Confirm that Coolify displays the branch as master.
6. Use repository root as the base directory: /.
7. Use /docker-compose.yaml as the Compose file location (with base directory /). If the UI removes the leading slash automatically, docker-compose.yaml is equivalent.
8. Leave the domain/public proxy configuration empty during initial validation.
9. Do not expose or publish PostgreSQL or Redis.

The repository is deliberately root-installable: no path inside ai01 is required.

If Coolify displays a separate exposed-port field, use the application/container port 8000; the Compose file handles the loopback host mapping to 18082. Do not use Coolify's own host port 8000 for Honcho.

Health checks

The Compose manifest defines Docker healthchecks for the API, PostgreSQL, and Redis services. The API check calls http://localhost:8000/health, so Docker and Coolify can verify container readiness.

Coolify's Health check path (/health) and Health check port (8000) are application metadata managed by Coolify's UI/API; they are not standard Docker Compose properties and cannot be reliably prefilled from a public Compose repository. If Coolify displays the optional proxy warning, configure those two fields in the resource settings. Use the container port 8000, not the host port HONCHO_API_PORT (default 18082).

2. Configure variables

Add these variables in Coolify's environment-variable UI. For the database password, use Coolify's Generate action (or enter another strong random password) when the variable is shown empty:

SERVICE_PASSWORD_HONCHO=<generate in Coolify; do not leave empty>
LLM_OPENAI_API_KEY=
OPENAI_API_KEY=

SERVICE_PASSWORD_HONCHO is a Coolify magic-variable name. Coolify may display it empty during the initial repository/Compose inspection and resolve it only after the variable is generated/saved. Do not deploy while it is empty. The Compose file maps the resulting value to the container variable HONCHO_DB_PASSWORD. Do not commit any generated password to GitHub. Enter the DeepSeek and OpenAI API keys manually and keep their values hidden.

Optional validation settings:

HONCHO_API_PORT=18082
AUTH_USE_AUTH=false
DERIVER_REPRESENTATION_BATCH_WORK_UNIT_TARGET_TOKENS=512
DERIVER_REPRESENTATION_BATCH_MAX_AGE_SECONDS=300
DERIVER_FLUSH_ENABLED=false

The model policy is already encoded in docker-compose.yaml:

• DeepSeek for derivation, summaries, observations, and dialectic operations.
• OpenAI text-embedding-3-small for embeddings.
• DREAM_ENABLED=false during the initial validation window.
• Vector reconciliation every 60 seconds.
• Representation batches target 512 tokens and flush after 5 minutes by default. This avoids leaving short Hermes conversations un-derived for the upstream 30-minute default while retaining batching for cost control. Set DERIVER_FLUSH_ENABLED=true only for controlled tests, because it can increase model/API usage.

Do not add .env files to this repository. Coolify is the secret store for this deployment.

3. Deploy and validate

Deploy from Coolify, then verify from the host:

curl --fail --silent --show-error \
  --max-time 10 \
  http://127.0.0.1:18082/health

Expected response:

{"status":"ok"}

Then verify in Coolify or with Docker:

docker compose ps
docker compose logs --tail=100 api deriver database database-init redis

Required state:

• api: healthy
• database: healthy
• redis: healthy
• deriver: running
• database-init: exited successfully
• no PostgreSQL or Redis host-published ports

The first deployment starts with an empty database. Honcho migrations are executed by the API entrypoint and pgvector is initialized before the API is allowed to start.

Hermes cutover

Keep the existing Honcho deployment running while validating this repository. Do not change Hermes until all of the following pass:

1. API health check.
2. PostgreSQL health and successful migrations.
3. Redis health.
4. Deriver startup without errors.
5. OpenAI embedding request succeeds.
6. DeepSeek derivation produces observations.
7. A real semantic-search request succeeds through the Hermes Honcho integration.
8. A restart preserves PostgreSQL and Redis data.

For a reversible cutover, either:

• keep the new instance on 18082 and change Hermes' Honcho base URL; or
• stop the old instance, change HONCHO_API_PORT to 18080, and redeploy this Compose application.

Do not run both instances on the same host port.

Security

• This repository must remain free of credentials and data.
• Do not commit .env, database dumps, Docker logs, OAuth tokens, or Hermes state.
• Do not expose the API publicly with AUTH_USE_AUTH=false.
• If a public or private HTTPS route is required, enable Honcho authentication and configure AUTH_JWT_SECRET before assigning a domain.
• Do not reuse Hermes Codex OAuth credentials as an LLM API key.
• PostgreSQL and Redis should remain private to the Compose network.

Persistence and rollback

Coolify creates project-scoped persistent volumes for the pgdata and redis-data declarations. Do not enable destructive volume deletion during redeployments.

To roll back the application without deleting data, redeploy the previous Compose revision or stop the Coolify application. Do not remove its volumes until a verified database backup exists.

This repository intentionally does not migrate data from the direct honcho-ai01 deployment. A fresh Honcho workspace is acceptable during the initial rollout; data migration can be added later if required.

Updating Honcho

The Compose build context is pinned to the upstream tag:

https://github.com/plastic-labs/honcho.git#v3.0.12

Upgrade only through a reviewed pull request. Update the tag, validate the Compose configuration and deployment, then document migration or compatibility notes in the same change.

Local validation

The same Compose file can be syntax-checked without exposing secrets:

cp .env.example .env
chmod 600 .env
# Replace the three placeholders locally.
docker compose --env-file .env config --quiet
docker compose --env-file .env config --services

Do not run the local stack on a host where port 18082 is already in use. Use a different HONCHO_API_PORT for a parallel validation deployment.

Repository layout

docker-compose.yaml  Coolify-compatible deployment manifest
.env.example       Secret names and safe validation defaults
README.md          Installation, validation, security, and rollback guide
SECURITY.md        Security reporting and handling policy
LICENSE            MIT license
.github/workflows/ CI syntax and secret-scan checks
docs/              Operational notes and troubleshooting

License

MIT. See LICENSE.