How-to guide: Secure a self-hosted Agent Canvas instance for incoming automation webhooks

Problem

There is no how-to guide for the common self-hosting question: how do I secure a self-hosted Agent Canvas instance (auth/login) while making it reachable from the outside so that external webhook events (e.g. Linear, Slack, GitHub) can hit the automation backend?

This came up in a Slack thread where a self-hoster needed Linear webhook events to reach their automation server. Participants pieced together a working answer from scratch (exposing only the automation port via ngrok, LOCAL_BACKEND_API_KEY, nginx basic auth, Cloudflare worker + tunnel, Tailscale), but none of that knowledge is captured in the docs today.

What exists today (partial coverage)

• backend-setup/vm.md covers securing the VM, LOCAL_BACKEND_API_KEY + --public mode, and access methods (SSH tunnel, ngrok, reverse proxy + TLS). It is framed around reaching the UI, not around receiving incoming webhooks on the automation endpoint.
• docs/SELF_HOSTING.md (in-repo) shows the architecture diagram with the automation backend on :18001 routed at /api/automation/*, but does not explain how to expose that path for external services.
• managing-automations.md / prebuilt-automations.md mention that automations can have webhook triggers, but do not explain how to securely expose the webhook-receiving endpoint on a self-hosted instance.
• Event-based automations docs are Cloud-focused (GitHub App event routing) and do not cover self-hosted webhook ingestion.

What's missing

A dedicated how-to guide that walks through securing a self-hosted instance and exposing it for incoming automation webhooks, including:

1. The deployment shape: agent server + automation backend behind the ingress proxy, with /api/automation/* as the only externally reachable path.
2. Authenticating webhook calls: how LOCAL_BACKEND_API_KEY / X-Session-API-Key applies to the automation endpoint, and how third-party webhook providers (Linear, Slack, GitHub) can be configured to send the key (header injection via a proxy, etc.).
3. Options for safely reaching the automation endpoint from the public internet without exposing the full UI/agent server:
   • ngrok scoped to the automation ingress port
   • Cloudflare Tunnel / Worker fronting only /api/automation/*
   • Reverse proxy (nginx) with path-scoped exposure + basic auth / IP allow-listing
   • Tailscale / VPN for a zero-public-exposure option
4. Webhook signature verification (the automation backend already verifies Linear/Slack HMAC signatures) so readers understand the layered security model.
5. A worked example for at least one provider (Linear is the motivating case).

Context

• Slack thread: a self-hoster running Agent Canvas locally needed Linear webhook events to reach the automation server, and the recommended pattern (expose only the automation port, rely on LOCAL_BACKEND_API_KEY) had to be reverse-engineered from the thread.
• This is relevant to the Linear epoch "Barrier-free AI development: securely accessing external context" — securely exposing an automation instance for external context is a prerequisite for that vision.

Proposed title

"How-to: Secure a self-hosted Agent Canvas instance for incoming automation webhooks"

This issue was created by an AI agent (OpenHands) on behalf of a team member, summarizing a Slack thread discussion.

Start by reading backend-setup/vm.md and docs/SELF_HOSTING.md, then compare managing-automations.md and prebuilt-automations.md for the existing webhook terminology. Document the self-hosted deployment shape, authentication and exposure options, signature verification, and a Linear example; the guide is done when these steps are clear without relying on the Slack thread.