HostAgentics Docs

HostAgentics Relay

Last updated: 2026-08-06

The Relay is the authenticated bridge between the HostAgentics control plane and agent runtimes (OpenClaw, Hermes Agent), and between runtimes and the customer's own integrations. It lets customers trigger agent tasks and n8n workflows from outside, receive progress events, and connect n8n to agents without opening inbound ports broadly. This document describes the security primitives, endpoints, tokens, and client surfaces (n8n nodes and the MCP server). The Relay is included with the Complete plan and available to agent runtimes as a managed capability.

1. Request signing (HMAC-SHA256)

Every Relay request carries a signature computed over a **canonical string**: `timestamp.nonce.sha256(body)`.

  • `sha256(body)` — the raw body is hashed first, so large payloads don't inflate the signed string and the signature covers the exact body bytes.
  • The HMAC-SHA256 digest of that canonical string (keyed with the shared secret) is the signature.

    • Verification recomputes the expected signature and compares it in constant time (`timingSafeEqual`) — no string comparison that could leak timing.

    2. Headers

    | Header | Content |

    | --- | --- |

    | `x-hostagentics-signature` | Hex HMAC-SHA256 of `timestamp.nonce.sha256(body)` |

    | `x-hostagentics-timestamp` | Unix milliseconds of signing time |

    | `x-hostagentics-nonce` | Single-use random nonce |

    3. Replay protection

  • **Timestamp window**: payloads older than **5 minutes** are rejected (`stale_timestamp`); timestamps more than **30 seconds** in the future are rejected (`future_timestamp`) to absorb clock skew.
  • **Nonce freshness**: nonces are single-use. The API checks nonce freshness against the nonce store (`relay_nonces`); a reused nonce is rejected (`replayed_nonce`) even if the signature is valid.
  • **Idempotency keys**: retries are safe because run-creating endpoints accept an idempotency key (8–128 chars); a retry with the same key returns the existing run instead of creating a duplicate (`agent_runs.idempotencyKey`, `workflow_runs.idempotencyKey`).

    • 4. Scoped tokens

    Relay tokens are scoped and capability-limited:

  • Format: `hag_` prefix plus 32 random bytes (base64url). The plaintext token is displayed **exactly once** at issuance.
  • **Hashed at rest**: only the SHA-256 hash is stored (`relay_tokens.tokenHash`); the token is verified by hashing the presented value and comparing to the stored hash.
  • **Hint only**: the UI shows a non-reversible hint (`hag_abcde…wxyz`), never the full token.
  • **Claims**: each token carries the organization, the allowed runtime IDs (empty = all of the org's runtimes), allowed actions, optional IP and domain restrictions, and an expiry. Claim checks reject expired, action-mismatched, runtime-mismatched, IP-restricted, and domain-restricted requests (`checkTokenClaims`).
  • Tokens can be revoked at any time (`revokedAt`); usage is recorded (`lastUsedAt`).

    • 5. Endpoints

  • **Run task** — start an agent task on an OpenClaw or Hermes runtime: `POST /relay/runs/agent` with task, optional input, timeout, and callback URL. Recorded as `agent_runs`; status transitions queued → running → succeeded/failed/cancelled/timed_out.
  • **Trigger workflow** — trigger a workflow on an n8n runtime: `POST /relay/runs/workflow` with workflow ID and input. Recorded as `workflow_runs`.
  • **Progress events** — run progress is delivered as events (`relay_events`: created, progress, completed, cancelled, callback_sent) and callbacks are delivered to the customer's `callbackUrl` with the same signing scheme. Callback delivery is retried with backoff via `webhook_deliveries` until delivered or exhausted.

    • 6. Client surfaces

  • **n8n nodes** — the `n8n-nodes-hostagentics` package provides nodes that call Relay endpoints (run task, trigger workflow) from inside a customer's n8n workflow, using a scoped Relay token stored as a node credential.
  • **MCP server** — the `mcp-server` package exposes Relay capabilities as MCP tools, so MCP-capable clients can start runs and read run state with the same scoped-token authentication.

    • Both surfaces use the same primitives: signed requests, scoped tokens, idempotency keys.

    7. Notes and limitations

  • The Relay carries run instructions and results between the customer's systems and their own runtimes; it does not give the platform access to agent memory, and run payloads are stored for operational visibility (see the privacy policy).
  • A compromised Relay token is limited by its claims (org, runtimes, actions, expiry, restrictions) and can be revoked; rotate tokens on any suspected exposure.

    • 8. Related documents

  • `docs/architecture.md` — where the Relay sits in the platform
  • `docs/security.md` — Relay security in the threat model
  • `docs/secret-rotation.md` — webhook secrets and token hygiene