Hookaido

Overview

Implement and troubleshoot Hookaido with a config-first workflow: edit Hookaidofile, validate, run, exercise ingress/pull/exec flows, then diagnose queue health and DLQ behavior. Treat Hookaido v2.6.0's modular architecture as additive in this skill: keep the existing workflow intact by default, and opt into modules such as postgres, gRPC workers, subprocess delivery (deliver exec), or release verification only when they materially help the task. Use conservative, reversible changes and validate before runtime operations.

Workflow

1. Confirm target topology: inbound+pull (HTTP or gRPC), push outbound, subprocess exec, or internal queue, plus the queue backend (sqlite, memory, or postgres).
2. Choose runtime mode and ensure hookaido exists where tools execute.
   • Host-binary mode: use the install action from metadata.openclaw.install.
   • Host fallback: run bash {baseDir}/scripts/install_hookaido.sh (pinned v2.6.0, SHA256-verified).
   • Public repo/source mode: use the public upstream repo github.com/nuetzliches/hookaido via go install github.com/nuetzliches/hookaido/cmd/[email protected] when a source-based install is preferred.
   • Docker-sandbox mode: use a sandbox image that already includes hookaido (preferred), or install inside sandbox via agents.defaults.sandbox.docker.setupCommand.
   • Keep host install actions available as fallback and to satisfy metadata.openclaw.requires.bins.
3. Inspect and update Hookaidofile minimally.
4. Run format and validation before starting or reloading:
   • hookaido config fmt --config ./Hookaidofile
   • hookaido config validate --config ./Hookaidofile
   • hookaido config validate --config ./Hookaidofile --strict-secrets when secret refs or Vault-backed config are involved.
5. Start runtime and verify health:
   • hookaido run --config ./Hookaidofile --db ./.data/hookaido.db
   • hookaido run --config ./Hookaidofile --postgres-dsn "$HOOKAIDO_POSTGRES_DSN" when queue postgres is selected.
   • curl http://127.0.0.1:2019/healthz?details=1
6. Validate end-to-end behavior:
   • ingress request accepted and queued
   • consumer dequeue/ack/nack/extend path works (HTTP pull, batch ack/nack, plus gRPC pull when enabled)
7. For incidents, inspect backlog and DLQ first, then mutate.

Task Playbooks

Configure Ingress and Pull Consumption

1. Define a route with explicit auth and pull path (HTTP pull, optional gRPC pull worker listener).
2. Keep secrets in env/file refs, never inline.
3. Verify route and global pull auth are consistent.
4. Test with a real webhook payload and a dequeue/ack cycle, using batch ack/nack when worker throughput matters.

Prefer this baseline:

ingress {
  listen :8080
}

pull_api {
  listen :9443
  grpc_listen :9943 # optional gRPC pull-worker listener
  auth token env:HOOKAIDO_PULL_TOKEN
}