n8n-nodes-hermes

n8n-nodes-hermes provides the Hermes community node for n8n.

Hermes is a controlled execution layer between an AI Agent and external systems. An agent produces structured action JSON; Hermes validates the action, applies local safety policy, requests approval when needed, routes the action through a service adapter, executes it through the Hermes API, and returns a normalized result.

Architecture

AI Agent / n8n Input
          |
          v
  Input Extraction
  - Entire item
  - Specific field
  - Manual JSON
          |
          v
  Validation Layer
  - Required fields
  - JSON parsing
  - Schema extension point
          |
          v
    Safety Layer
  - Allowed actions
  - Blocked actions
  - Sensitive actions
          |
          v
   Approval Layer
  - Approval policy
  - Approval status
  - Approval requests
          |
          v
    Action Router
          |
          v
  Service Adapter Registry
  - gmail
  - google_calendar
  - whatsapp
  - crm
  - tasks
  - reminders
  - reports
  - webhooks
  - custom_api
          |
          v
   Execution Layer
  - Authenticated HTTP
  - Timeout and retry
  - Idempotency
          |
          v
 Response Normalization
          |
          v
      n8n Output

The registered adapters are intentionally generic. They select the correct Hermes API operation without embedding Gmail, calendar, CRM, or other service business logic in the node. A future adapter can implement HermesServiceAdapter and be registered without changing the router.

Project Structure

n8n-nodes-hermes/
|-- package.json
|-- package-lock.json
|-- tsconfig.json
|-- eslint.config.mjs
|-- index.ts
|-- README.md
|-- LICENSE
|-- credentials/
|   `-- HermesApi.credentials.ts
|-- nodes/
|   `-- Hermes/
|       |-- Hermes.node.ts
|       |-- Hermes.node.json
|       `-- hermes.svg
`-- helpers/
    |-- GenericFunctions.ts
    |-- validators.ts
    |-- actionRouter.ts
    |-- types.ts
    |-- normalizers.ts
    `-- errors.ts

File Responsibilities

| File | Responsibility | | --- | --- | | package.json | Package metadata, n8n node registration, build scripts, and development dependencies. | | package-lock.json | Reproducible development dependency resolution. | | tsconfig.json | Strict TypeScript compilation settings and output configuration. | | eslint.config.mjs | Official strict n8n community-node ESLint configuration. | | index.ts | Public exports for the node, credential, router, client, types, validators, and normalizers. | | LICENSE | MIT license required for verified n8n community nodes. | | credentials/HermesApi.credentials.ts | Credential UI for the API base URL, authentication, timeout, approval policy, and environment. | | nodes/Hermes/Hermes.node.ts | n8n node UI, input extraction, operation orchestration, safety enforcement, routing, and normalized output handling. | | nodes/Hermes/Hermes.node.json | n8n node metadata, categories, and documentation links used by current community-node tooling. | | nodes/Hermes/hermes.svg | Hermes node icon. | | helpers/types.ts | Shared interfaces, unions, operation types, adapter contracts, and request/response types. | | helpers/errors.ts | Typed reusable Hermes errors and safe conversion of unknown failures. | | helpers/validators.ts | JSON parsing, required-field validation, allow/block lists, sensitive-action policy, and schema-validation extension point. | | helpers/actionRouter.ts | Router and adapter registry. It maps target services to generic adapters without service business logic. | | helpers/GenericFunctions.ts | Authenticated Hermes API client, operation functions, retries, timeouts, idempotency headers, and secret-safe logging. | | helpers/normalizers.ts | Stable success, failure, approval-required, and validation output shapes. |

Installation

For a local n8n installation:

npm install n8n-nodes-hermes

You can also install it from Settings > Community Nodes in n8n by entering:

n8n-nodes-hermes

Restart self-hosted n8n after installation when your deployment does not reload community nodes automatically.

Build

Node.js 22 or newer is required.

npm install
npm run typecheck
npm run lint
npm run build

The production package is compiled into dist/.

Development

npm install
npm run dev

The n8n node CLI builds the package in watch mode and starts a local n8n development instance.

Useful commands:

npm run build:watch
npm run lint
npm run lint:fix
npm run typecheck

Publishing

1. Replace the placeholder homepage, repository, documentation URLs, and author values.
2. Run npm run typecheck, npm run lint, and npm run build.
3. Test the packed artifact with npm pack.
4. Publish with npm provenance from a trusted GitHub Actions publisher.

npm version patch
npm publish --provenance --access public

n8n requires the n8n-community-node-package keyword for community node discovery. New community node releases should use npm provenance.

Credentials Setup

Create a Hermes API credential and configure:

• Base URL: HTTPS base URL for the Hermes API.
• Authentication Type: Bearer Token, API Key Header, or No Auth.
• API Key: Stored by n8n as encrypted credential data.
• API Key Header Name: Used only with API Key Header authentication.
• Timeout Seconds: Default request timeout.
• Default Approval Mode: Local approval policy.
• Environment: Development, staging, or production.

Hermes never writes the API key to logs, normalized errors, output data, or request metadata.

Node Configuration

The node accepts action data from:

• Entire Input Item: Uses the root object or auto-detects output, action, command, hermes_action, or data.
• Specific Field: Reads a field or dotted path such as output or data.hermes_action.
• Manual JSON: Uses JSON entered directly in the node.

If an input value is a JSON string, Hermes parses it automatically. Main fields provide fallback values when the selected input does not provide them.

Advanced options configure:

• Allowed, blocked, and sensitive actions
• Timeout and retry count
• Log level
• Raw response inclusion
• Idempotency key
• Correlation ID

Supported Operations

| Operation | Behavior | | --- | --- | | Execute Action | Validates, applies safety policy, routes, and executes an action. | | Validate Action | Applies local policy and requests API validation when locally executable. | | Dry Run Action | Calls the Hermes dry-run endpoint with dry_run: true. | | Get Capabilities | Returns capabilities exposed by the Hermes API. | | Create Approval Request | Creates an approval request for the supplied action. | | Execute Approved Action | Executes an action through the approved-action endpoint. | | Raw Hermes Request | Sends GET, POST, PUT, PATCH, or DELETE to a relative Hermes endpoint. |

Supported Target Services

• gmail
• google_calendar
• whatsapp
• crm
• tasks
• reminders
• reports
• webhooks
• custom_api

These values select adapters only. External-system business logic belongs in the Hermes API or a future dedicated adapter, not in the core router.

Approval Workflow

1. The agent creates an action with requires_approval and approval_status.
2. Hermes validates the action and applies the configured approval mode.
3. A sensitive, unapproved action returns status: "approval_required" without execution.
4. Use Create Approval Request to create a human review task.
5. After approval, set approval_status to approved.
6. Use Execute Approved Action.

Approval modes:

• always_require_approval
• require_approval_for_sensitive_actions
• allow_safe_actions_only
• full_auto_mode

Blocked actions always fail, regardless of approval status or mode.

Safety Layer

Local validation runs before routed action calls:

• action, target_service, and operation must be present.
• Input JSON must be valid.
• A blocked action always fails.
• When an allowlist is configured, actions outside it fail.
• Sensitive actions follow the credential approval mode.
• Schema validation is an explicit placeholder for a future schema registry.

Local checks complement server-side authorization. They do not replace access controls in the Hermes API or target systems.

Idempotency

Set idempotency_key in agent output or Advanced Options > Idempotency Key. The advanced option takes precedence.

Hermes sends the value in:

Idempotency-Key: unique-key

It also passes idempotency_key in the action body. The Hermes API should persist idempotency results and prevent repeated side effects. Hermes only retries POST and PATCH requests when an idempotency key is present; GET, PUT, and DELETE requests may be retried without one.

Logging

Log levels are error, warn, info, and debug. Logs contain operation metadata such as the method, relative endpoint, attempt number, status code, and correlation ID.

Hermes does not log:

• API keys or bearer tokens
• Authorization headers
• Request bodies
• Response bodies
• Credential objects

AI Agent Integration

Ask the AI Agent to emit one JSON object matching this contract:

{
  "action": "create_email_draft",
  "target_service": "gmail",
  "operation": "create_draft",
  "requires_approval": true,
  "approval_status": "pending",
  "safety_level": "medium",
  "idempotency_key": "unique-key",
  "correlation_id": "workflow-id",
  "data": {},
  "metadata": {}
}

Connect the agent output to Hermes and select Entire Input Item. Hermes also supports agents that put serialized JSON in output, command, hermes_action, or data.

Examples

1. Gmail Draft

{
  "action": "create_email_draft",
  "target_service": "gmail",
  "operation": "create_draft",
  "requires_approval": false,
  "approval_status": "not_required",
  "safety_level": "low",
  "data": {
    "to": ["[email protected]"],
    "subject": "Project update",
    "body": "The draft was generated by an AI Agent."
  }
}

2. Calendar Event

{
  "action": "create_calendar_event",
  "target_service": "google_calendar",
  "operation": "create_event",
  "requires_approval": false,
  "data": {
    "title": "Planning session",
    "start": "2026-06-16T09:00:00Z",
    "end": "2026-06-16T10:00:00Z"
  }
}

3. Task Creation

{
  "action": "create_task",
  "target_service": "tasks",
  "operation": "create",
  "requires_approval": false,
  "data": {
    "title": "Review Hermes action policy",
    "priority": "high"
  }
}

4. Approval Required Email

Configure send_email as a sensitive action:

{
  "action": "send_email",
  "target_service": "gmail",
  "operation": "send",
  "requires_approval": true,
  "approval_status": "pending",
  "safety_level": "high",
  "data": {
    "to": ["[email protected]"],
    "subject": "Contract confirmation",
    "body": "Please review before sending."
  }
}

The node returns:

{
  "success": false,
  "status": "approval_required",
  "approval_required": true,
  "error": {
    "code": "APPROVAL_REQUIRED",
    "message": "Action \"send_email\" requires approval before execution.",
    "details": {
      "action": "send_email"
    }
  }
}

5. Dry Run

Select Dry Run Action:

{
  "action": "create_webhook_delivery",
  "target_service": "webhooks",
  "operation": "deliver",
  "dry_run": true,
  "data": {
    "url": "https://example.com/hooks/hermes",
    "method": "POST"
  }
}

6. Raw Hermes API Request

Configure:

HTTP Method: POST
Endpoint: /v1/custom/inspect
Request Body: {"resource":"policy"}
Query Parameters: {"verbose":true}

The endpoint is always resolved relative to the credential Base URL and uses the configured authentication, timeout, retries, and correlation headers.

Normalized Output

Successful outputs use:

{
  "success": true,
  "status": "completed",
  "action": "create_task",
  "target_service": "tasks",
  "operation": "create",
  "result": {},
  "error": null,
  "approval_required": false,
  "correlation_id": "workflow-id",
  "idempotency_key": "unique-key",
  "executed_at": "2026-06-14T12:00:00.000Z"
}

Failures use the same top-level fields and a structured error:

{
  "success": false,
  "status": "failed",
  "action": "",
  "target_service": "",
  "operation": "",
  "result": {},
  "error": {
    "code": "INVALID_JSON",
    "message": "The supplied value is not valid JSON.",
    "details": {}
  },
  "approval_required": false,
  "correlation_id": "",
  "idempotency_key": "",
  "executed_at": "2026-06-14T12:00:00.000Z"
}

Enable n8n Continue On Fail to emit structured failure items. When disabled, Hermes throws a NodeOperationError and stops the node.

Testing

Run static checks:

npm install
npm run typecheck
npm run lint
npm run build

Run npm run dev, create a workflow with a Manual Trigger and Hermes node, and test:

Test Case 1: Valid Action Executes

• Use a valid action with all required fields.
• Expect one normalized result with success: true.
• Verify the Hermes API receives the configured correlation and idempotency headers.

Test Case 2: Invalid JSON

• Select Manual JSON and provide malformed JSON.
• With Continue On Fail enabled, expect error.code: "INVALID_JSON".
• With Continue On Fail disabled, expect a NodeOperationError.

Test Case 3: Blocked Action

• Add the action name to Blocked Actions.
• Expect error.code: "BLOCKED_ACTION" and no API execution request.

Test Case 4: Approval Required

• Add the action to Sensitive Actions.
• Use a policy that requires sensitive-action approval and set status to pending.
• Expect status: "approval_required" and no execution request.

Test Case 5: Dry Run

• Select Dry Run Action.
• Verify Hermes calls /v1/actions/dry-run with dry_run: true.
• Expect a normalized response and no target-system side effect.

Test Case 6: Hermes API Failure

• Return a 500 response from a test Hermes API.
• Verify retries match Retry Count.
• Expect a normalized HERMES_API_ERROR with Continue On Fail enabled.
• Confirm logs and outputs contain no API key or Authorization header.

Troubleshooting

Node does not appear

• Confirm the package name starts with n8n-nodes-.
• Confirm package.json contains the n8n-community-node-package keyword.
• Run npm run build and confirm dist/nodes/Hermes/Hermes.node.js exists.
• Restart self-hosted n8n.

Authentication fails

• Confirm the Base URL does not include an endpoint path.
• Match the credential authentication type to the Hermes server.
• For API Key Header, verify the exact header name.
• Confirm the key has not expired and is authorized for the selected environment.

Approval is always required

• Review the credential Default Approval Mode.
• Check requires_approval, approval_status, and Sensitive Actions.
• always_require_approval intentionally requires approval for every unapproved action.

Action is rejected locally

• Ensure action, target_service, and operation are non-empty strings.
• Check Allowed Actions and Blocked Actions.
• A blocked action cannot be enabled by adding it to Allowed Actions.

Request times out

• Increase Advanced Options > Timeout or the credential timeout.
• Keep retries low for non-idempotent requests.
• Supply an idempotency key before retrying an operation that can create side effects.

Raw request reaches the wrong URL

• Use a relative endpoint such as /v1/capabilities.
• Hermes joins the endpoint to the credential Base URL and normalizes duplicate slashes.

Security Notes

• No secrets are hardcoded.
• Credentials are read through n8n credential APIs.
• Authentication headers are created only at request time.
• Logs exclude headers, bodies, responses, and credential values.
• Blocked actions fail before network execution.
• Adapter routing contains no external-system business logic.
• Raw requests remain authenticated Hermes API calls; they are not arbitrary credential forwarding.

License

MIT