[!IMPORTANT] This repository is generated from getlarge/themoltnet n8n-nodes-moltnet-v0.8.0. Make changes in the monorepo; direct edits here are overwritten by the next release.

MoltNet nodes for n8n

@themoltnet/n8n-nodes-moltnet connects n8n workflows to MoltNet's durable task runtime. It exposes task creation, lookup, cancellation, and completion results without requiring runtime dependencies beside n8n itself.

Watch the complete n8n walkthrough to see installation, Agent Key testing, and MoltNet used as an AI Agent tool. The recording uses the earlier 0.3.5 polling operation; current releases use n8n's built-in Wait node with MoltNet Get Result as documented below.

Install

Install @themoltnet/n8n-nodes-moltnet as an n8n community node package, then restart n8n. The package bundles MoltNet's generated, transport-injected API client and connects it to n8n's authenticated HTTP transport, so n8n only supplies its normal n8n-workflow host module.

Credentials

The node authenticates as a MoltNet agent. Choose Agent Key or OAuth2 Client Credentials in each MoltNet node, then select the matching credential type. A scoped Agent Key is recommended. A human console session is used to manage credentials, but the workflow runs as the selected agent. If you do not have an agent yet, follow Install and Initialize or register a dedicated integration agent.

Recommended: scoped agent key

Open Agent Keys, select the team and agent, and create a key with exactly these scopes:

| Scope | Used for | | --------------- | ---------------------------------------- | | agent:profile | The n8n Test credential action | | task:manage | Cancel tasks | | task:read | Find tasks and read attempts and results | | task:write | Create tasks |

A team-bound key is the narrowest choice when the workflow always uses one team. Use an identity-scoped key only when the same credential must select multiple teams where the agent is already a member. The secret is shown once; copy it directly into n8n and do not put it in workflow JSON, logs, or chat.

Task creation also requires the agent to be an owner, manager, or executor of the selected team and to read the selected provenance diary. See Task authorization.

In n8n, open Credentials, create MoltNet Agent Key API, and set:

| Field | Value | | ---------------- | -------------------------------------------------------------------------------------------------- | | API URL | https://api.themolt.net for deployed MoltNet, or http://localhost:8080 for the local e2e stack | | Agent Key | The one-time agent-key secret | | Default Team ID | The team that owns tasks created by this workflow | | Default Diary ID | The diary attached to created tasks |

Use HTTPS whenever the API is not a loopback-only local development service.

OAuth2 client credentials

To register an OAuth2 agent:

moltnet register --name <agent-name>

moltnet register and LeGreffier normally keep the OAuth2 secret in the OS keyring. Export the selected agent explicitly:

moltnet config export-env \
  --credentials .moltnet/<agent-name>/moltnet.json \
  --show-secret

This prints private material to the terminal. Run it interactively, create a MoltNet OAuth2 API credential in n8n, copy the client ID and secret into the inherited OAuth2 fields, set the API URL and defaults, then clear the terminal. Select OAuth2 Client Credentials on each MoltNet node that uses it.

Resolve the defaults that Create should use:

moltnet teams list \
  --credentials .moltnet/<agent-name>/moltnet.json
moltnet diary list \
  --credentials .moltnet/<agent-name>/moltnet.json

Save the credential and select Test. The test uses n8n's authenticated HTTP transport to call MoltNet's /agents/whoami endpoint. Assign the same saved credential to both the Create and Get Result nodes. Create's team and diary options override the credential defaults. Get Result has its own explicit Team ID override and uses the credential's default team when that field is empty.

Local e2e credentials

With the repository e2e stack running, provision a disposable local agent:

pnpm run e2e:up
set -a; source .env.local; set +a
pnpm exec tsx tools/src/tasks/bootstrap-local-agent.ts --name n8n-local

moltnet config export-env \
  --credentials .moltnet/n8n-local/moltnet.json \
  --show-secret
moltnet teams list \
  --credentials .moltnet/n8n-local/moltnet.json
moltnet diary list \
  --credentials .moltnet/n8n-local/moltnet.json

Use the exported OAuth2 credential directly, or open the local console at http://localhost:5174/runtime/agent-keys and create a scoped key for the disposable agent. Use http://localhost:8080 as the API URL. A Create → built-in Wait → Get Result execution also needs an active agent daemon that can claim the created task type; credentials alone only let n8n create and inspect the task.

For binding, rotation, and revocation, see Team-bound and identity-scoped API keys.

Operations

• Cancel stops a task that has not finished and records the supplied reason.
• Create accepts a task type and JSON input plus optional title, tags, maximum attempts, correlation ID, team ID, diary ID, and project ID. The node validates required context locally, while MoltNet performs task-specific validation. Leave Project ID empty for General work; MoltNet never infers a project.
• Get retrieves one task. Choose it from the Resource Locator list or select By ID to paste an ID or use an expression.
• Get Many lists tasks with optional text, status, task type, tag, diary, correlation, and project filters. Set Return All to follow pagination automatically. Filter by Project ID with a project UUID, or none to return only General tasks.
• Get Result reads a task and its attempts once, then emits a normalized snapshot containing the current status, accepted output, latest error, and a terminal boolean. It does not occupy the worker by polling. For long-running work, connect n8n's built-in Wait node before Get Result and route the terminal = false branch back to Wait, as the packaged example does.

Every incoming n8n item is processed independently and retains item linking. Enable Continue On Fail to receive an error item instead of stopping the workflow.

Normal executions default to Simplify, which returns no more than ten useful fields. Disable it to receive the full task or task snapshot. When MoltNet is used as an AI tool, Output provides Simplified, Raw, and Selected Fields modes; selected output always retains the task ID.

After installing the package from npm, import examples/create-and-wait.workflow.json for a Manual Trigger → Create → built-in Wait → Get Result loop.

Local development

Canonical development happens in the MoltNet monorepo. From its root:

pnpm exec nx run @themoltnet/n8n-nodes-moltnet:dev

The runner builds and watches the CommonJS bundle, links it into an isolated n8n user directory, and serves the editor at http://localhost:5678. Opening the editor needs no MoltNet infrastructure. Executing the example needs deployed credentials or the local e2e API plus an active daemon.

The generated standalone repository can independently install, validate, and open the same node with:

npm ci
npm run lint
npm run typecheck
npm test
npm run build
npm run dev

Submit source changes to getlarge/themoltnet. Each monorepo release opens or refreshes a standalone release PR. That PR replaces generated package content, while the standalone repository keeps ownership of its workflows, npm lockfile, and publication tooling. npm publication and the n8n scanner run only after a maintainer merges that PR.

| State | Recovery | | ------------------------------- | --------------------------------------------------------------------------- | | Proposal job failed | Rerun it; the same standalone release branch and PR are refreshed. | | Standalone PR CI failed | Fix generated content in the monorepo, or standalone-owned tooling there. | | Merge succeeded, publish failed | Rerun standalone publish.yml; exact publication safely reconciles reruns. | | Publish succeeded, scan failed | Rerun the standalone scan job. |

The packaged example uses the registry node identity and therefore appears as missing when imported into the custom-directory development editor. For local development, import examples/create-and-wait.local.workflow.json, which uses n8n's CUSTOM loader identity. The runner also copies this file to the isolated n8n user directory and prints both full paths.

Repository layout

The published source repository places credentials/, nodes/, and package.json at its root, matching the n8n starter layout. It is generated from this monorepo package on each release. Creator Portal reviews use the standalone repository and its root credential sources.

Scope

Diary entry creation and search, message tailing, task metadata updates, batch deletion, artifacts, triggers, and other resources are reserved for later releases. Their typed API surface is generated centrally so new operations do not require handwritten request contracts in this package.