Description
n8n-nodes-niyoos
> Requires n8n 2.16 or newer. On an older n8n (any 1.x, or 2.x before 2.16), install
> [email protected] instead — this version will not run there. See
> Compatibility.
Put your n8n AI agents under governance. Niyoos sits between your
workflows and your AI providers. Every model call your AI Agent makes goes through Niyoos,
which can stop an agent instantly with a kill switch, hold it to a spending limit, and seal a
record of each call — its cost, model, timing and outcome — in a tamper-evident audit log.
Your provider keys stay encrypted inside Niyoos; n8n only ever holds a per-agent Niyoos key.
This package gives n8n two nodes:
- Niyoos Chat Model — the model for your AI Agent, Basic LLM Chain or any node with a Chat
- Niyoos (action) — Get Agent: the name, organisation and status of your agent, so a
- n8n 2.16 or newer for version 1.x of this package. On an older n8n the chat model says so
- On n8n 1.x, or n8n 2.x before 2.16, install
[email protected]. In n8n’s community - Retries: current n8n versions do not retry a failed AI model call, so the chat model’s
- No runtime dependencies: n8n supplies the model client.
Model input. Each workflow execution is recorded in Niyoos as one run, with no setup.
workflow can check the agent is active before it starts.
Installation · Credentials · Usage ·
Runs · When Niyoos stops a call ·
Compatibility · Development · License
Installation
Follow n8n’s community nodes installation guide
and install n8n-nodes-niyoos.
Credentials
Create a Niyoos API credential:
| Field | What to enter |
|—|—|
| Agent Key | Your Niyoos agent key, starting sk-aiwos-. In the Niyoos dashboard, open Agents, pick or create an agent, and copy its key. |
| Base URL | Leave as https://api.niyoos.com/proxy/v1 unless you run your own Niyoos deployment. |
The connection test checks the key against Niyoos and passes when it belongs to an existing
agent. Each Niyoos agent is bound to one provider credential, so the model list shows that
provider’s models. To use another provider, create another agent and another credential.
Usage
1. Add an AI Agent (or any node with a Chat Model input).
2. Click the + under the agent’s Chat Model input and search for Niyoos, then pick
Niyoos Chat Model. On n8n Cloud, install the Niyoos package from the node panel first
(press N, search “Niyoos”, Install).
3. Choose your Niyoos API credential and a model, then run the workflow.
Runs
Every model call carries a run id, n8n-, so all the calls one
workflow execution makes are grouped as one run in Niyoos. Nothing needs configuring.
When Niyoos stops a call
When Niyoos refuses a call, the node tells you why and what to change — for example:
| What happened | What the node says |
|—|—|
| The agent’s kill switch is on | This Niyoos agent is disabled (kill switch). Re-enable it in the Niyoos dashboard before running this workflow again. |
| The agent reached its spending limit | This Niyoos agent has reached the spending limit set for it, so Niyoos stopped the request before any provider was called. … |
| The provider rejected the stored key | The upstream provider rejected the provider key configured for this Niyoos agent. … |
Every refusal Niyoos can return has its own explanation. If n8n is going to retry a call, the
retry is left to happen and the explanation is shown only once the call has failed for good.
Compatibility
when the workflow runs.
nodes installer, enter the package name with the version, e.g. [email protected], and do
not update it past 0.1.x until you have upgraded n8n.
Maximum Retries option has no effect today. It is kept so the setting works if n8n restores
retries.
Development
npm ci
npm run lint
npm test # builds, then runs the test suite against the built package
contract/niyoos-contract.json holds the Niyoos wire values this package depends on — every
refusal code, the client header and the run-id rule. The tests fail if the package and the
contract disagree.
