Ship local-channels with agent-box (webhooks into agent sessions)

[defangdevs]

Requested by Lio (2026-07-17): agent-box should ship local-channels so every box user can wire webhooks (GitHub etc.) into their agent sessions, the way this dev box does.

What exists today (on nixos.defang.ca, hand-rolled)

• defangdevs/local-channels repo: the local-webhook MCP/channel plugin (plus the temporary gh-webhook alias) — receiver daemon verifies HMAC from any signing source via sources.json, exposes webhook_subscribe / webhook_unsubscribe / webhook_subscriptions topic routing, state in ~/.local/state/local-webhook/.
• A Caddy vhost (gh-webhook.<domain>) reverse-proxying to the receiver on localhost.
• Plugin installed from a local directory marketplace; the agent launches with --channels plugin:local-webhook@local-channels.

What shipping it in agent-box needs

• Receiver as a per-user (or shared) systemd service, bound to localhost, plus a managed Caddy vhost — the box already has wildcard-style vhost plumbing per user.
• Plugin install + --channels flag wired into the session launch. Note: a channel attaches only at claude startup, so the flag has to be part of the supervisor's launch command, and the plugin must be installed before first session start.
• Webhook secret provisioning: per-source HMAC secrets in sources.json; the settings page could own this (it already manages env secrets).
• Pin/fetch strategy: modules/agent-box.nix must stay single-file (issue 51 — deployments fetchurl it alone), so local-channels gets pinned and fetched like the module/agent pins, not referenced as a sibling path.

Constraints / open questions

• MCP channels are a research-preview feature (claude >= 2.1.80). For Team/Enterprise orgs the channel plugin must be allowlisted via console Admin Settings -> Managed settings (allowedChannelPlugins); a local managed-settings.json does not work. That's a per-customer manual step we can only document.
• Users on plans without channel support get the MCP tools but no in-session deliveries — decide whether to ship anyway (tools still useful?) or gate on agent version.
• One receiver per box vs per user: single port, so probably one shared receiver with per-user routing, or per-user receivers on distinct localhost ports each with their own vhost.
• gh-webhook alias should NOT ship — new boxes start clean on local-webhook.

[defangdevs]

Status update — receiver-daemon prerequisite recreated & pushed

The local-channels side is done and this time it's on the remote (the earlier verified branch was lost — it had only ever been a local commit under an ephemeral path and was never pushed).

local-channels PR: defangdevs/local-channels#2 — local-webhook 0.6.0

• LOCAL_WEBHOOK_RECEIVER_ONLY=1 daemon mode (owns ingress, fans out to peers, no session of its own)
• ingress selection: systemd socket-activation (fd 3) → LOCAL_WEBHOOK_HTTP_SOCK → loopback TCP (PORT=0 = pure IPC peer)
• LOCAL_WEBHOOK_SESSION per-session filter key (decoupled from SELF)
• verified end-to-end: HMAC over unix socket → 200; pure-IPC peers; per-session isolation; fd:3 activation; daemon survives delivery

Locked design (from prior sessions)

Grain is per-user endpoint → per-user receiver daemon → per-session subscriptions (fan-out over IPC among that user's sessions). Endpoint lives in the per-user ~/sites/*.caddy snippet imported by top-level Caddy (can't sit behind terminal basic-auth; GitHub can't authenticate). Receiver listens on a unix socket 0660 <user>:caddy to match the box's settings/ttyd socket pattern (no port allocation).

Not yet started: agent-box wiring

• systemd .socket (socket-activated unix socket, 0660 <user>:caddy) + .service running the daemon with RECEIVER_ONLY=1
• per-user webhook.caddy vhost → reverse_proxy unix//…sock
• session launch: --channels plugin:local-webhook@local-channels + LOCAL_WEBHOOK_SESSION/STATE_DIR env
• pin defangdevs/local-channels via rev+hash like the other agent-CLI pins

[defangdevs]

agent-box wiring drafted → PR #146

The module wiring is written and pushed as a draft: PR #146 (feat/issue-101-local-channels). Opt-in services.agent-box.webhook.enable (default off): per-user agent-box-webhook-<user> receiver daemon on a socket-activated 0660 <user>:caddy UNIX ingress, Caddy handle /<user>/webhook* (no auth) → that socket, and sessions load the plugin via seeded settings.json + a per-session LOCAL_WEBHOOK_SESSION. Edited the generated-module source (agent-box.nix.in) and regenerated; nix-parse + assemble --check pass.

Two blockers before it can be verified/merged:

1. Make defangdevs/local-channels public — the builtins.fetchTarball pin needs it (my token can't flip visibility; owner action). History scanned clean. Then webhook.sha256 (a placeholder) can be confirmed by a real fetch.
2. A real nixos-rebuild + live claude session to confirm the channel loads via seeded settings (no trust prompt) and deliveries actually reach a session.

Note: the --channels CLI flag exists but is a research preview requiring Anthropic auth, so the robust enabledPlugins/extraKnownMarketplaces settings path is used instead.