Self Hosting

---
name: self-hosting
description: "Run and troubleshoot the Honcho API, worker, database, Redis,
  embeddings, and startup validation."
metadata:
  disco-role: operating
disable-model-invocation: true
license: AGPL 3.0
---

# Self-hosting Honcho

Use this sub-skill when the task is about running Honcho locally or in a
production-like environment: API startup, worker startup, database schema,
Redis connectivity, embedding dimensions, vector-store mode, startup
validation, or server-side keys.

## What this route covers

- API server startup and shutdown.
- Deriver worker startup and queue processing.
- Database and schema prerequisites.
- Embedding-dimension validation.
- Vector-store mode selection and namespace behavior.
- Server-side key and auth setup.
- Queue health and deployment troubleshooting.

## What it does not cover

- SDK client code and REST client integration details.
- CLI command groups and config-file usage.
- Repo-wide testing and release hygiene.

Use `sub-skills/integrations/` for SDK and route usage, `sub-skills/cli-operations/`
for `honcho` terminal workflows, and `sub-skills/maintenance/` for tests and
release tasks.

## Read first

- `../../references/core-model.md`
- `../../references/configuration-and-environment.md`
- `../../references/troubleshooting.md`
- `references/workflow.md`
- `references/troubleshooting.md`
- `../../scripts/surface_report.py`
- `scripts/runtime_check.py`

## Typical questions this route should answer

- How do I start the API and worker safely?
- What database, Redis, and embedding settings do I need?
- Why did startup fail on vector dimensions?
- How do I tell whether queue processing is healthy?
- Which vector-store mode should I use?
- How should I configure keys and runtime secrets?

## Practical workflow

1. Read the configuration and environment reference.
2. Check the runtime surface with the bundled helper.
3. Confirm the database URI, schema, and embedding dimension.
4. Confirm the worker and queue are running.
5. Check the startup logs for the first closed-loop validation error.
6. If the deployment uses a non-default vector store, verify that mode before
   assuming pgvector behavior.

## Common decision points

- Use pgvector when you want the simplest local deployment.
- Treat external vector stores as optional and environment-specific.
- Treat an embedding mismatch as a blocking startup problem, not a warning.
- Treat queued memory work as asynchronous; do not expect immediate
  representation updates.

## Troubleshooting focus

This route owns startup failures caused by:

- bad database credentials or unreachable DB host,
- missing schema or extension prerequisites,
- Redis connection problems,
- wrong embedding dimension,
- mismatched vector-store settings,
- missing runtime secrets or provider keys,
- queue health problems that show up at startup or on the `/queue/status`
  surface.

See `references/troubleshooting.md` for symptoms, likely causes, and recovery
steps.

## Helpful bundled script

`scripts/runtime_check.py` prints a read-only summary of the current
configuration, route surface, and embedding validation status. Use it before
changing the deployment, or when you need a quick sanity check without digging
through source code.

## Good handoff phrases

- "How do I start Honcho locally?"
- "Why won't Honcho boot?"
- "What embedding dimension should I use?"
- "How do I check if the queue is healthy?"
- "What database and Redis settings do I need?"