Description

@poolsideai/n8n-nodes-poolside

An n8n community node package that adds a Poolside Chat Model sub-node, connecting Poolside’s Laguna models to n8n’s AI Agents and chains through Poolside’s OpenAI-compatible inference API.

It is a thin wrapper: your parameters are passed through to the endpoint as-is. There is no request or response rewriting.

Installation

Install from within n8n:

1. Go to Settings → Community Nodes.
2. Select Install a community node.
3. Enter the package name @poolsideai/n8n-nodes-poolside.
4. Agree to the risks of installing community nodes and select Install.

After installation the node appears in the nodes panel under AI → Language Models.

For self-hosted installs you can also install it manually:

mkdir -p ~/.n8n/nodes
cd ~/.n8n/nodes
npm install @poolsideai/n8n-nodes-poolside

Then restart n8n.

Getting a Poolside API key

1. Sign in to platform.poolside.ai.
2. Open the API Keys tab.
3. Select New key and copy the value.

The key is shown only once — store it somewhere safe before closing the dialog. If you lose it, create a new key.

Credentials

Create a Poolside credential in n8n with:

| Field | Description |
| — | — |
| API Key | The key from platform.poolside.ai. Sent as Authorization: Bearer . |
| Base URL | Defaults to https://inference.poolside.ai/v1. Editable — see Self-hosted deployments. |

The credential test issues GET {baseUrl}/models; a green check means the key and base URL are both good.

Usage

1. Add an AI Agent (or any chain node that takes a language model) to your workflow.
2. Click the Model connector below the Agent.
3. Choose Poolside Chat Model.
4. Select your Poolside credential.
5. Pick a model from the Model dropdown — the list is loaded live from GET /models on your configured base URL.

Tool calling works through the Agent’s normal tool connections, since Poolside’s API is OpenAI-shaped.

Options

All options are optional; leave the collection empty to use the endpoint’s defaults.

| Option | Default | Notes |
| — | — | — |
| Sampling Temperature | 0.7 | Range 0–2, one decimal place. Lower is more deterministic. |
| Maximum Number of Tokens | -1 | Max tokens to generate. -1 leaves it unset. Laguna models cap output at 32,768 tokens. |
| Timeout | 360000 | Maximum request duration in milliseconds. |
| Max Retries | 2 | Number of retry attempts on a failed request. |
| Thinking | true | Whether the model reasons before answering. Sent as chattemplatekwargs.enable_thinking. See Thinking and structured output. |

Thinking and structured output

Laguna models have native reasoning, and Poolside Platform enables thinking by default. The reasoning text arrives in the message content, which breaks n8n nodes that need a strictly formatted reply.

If you see:

> Model output doesn’t fit required format

…on one of these nodes, turn Thinking off in the Poolside Chat Model’s options:

• Text Classifier
• Information Extractor
• Sentiment Analysis
• Any chain using a Structured Output Parser

These nodes prompt for bare JSON and then parse the message text. When thinking is on, the reply can lead with reasoning prose, so parsing fails. Because it depends on how the model chooses to reason about each input, the failure is often intermittent — some items succeed and a later one fails.

Turning Thinking off also makes tool calling more reliable, particularly when forcing a specific call with tool_choice.

Leave Thinking on for open-ended reasoning work: AI Agent steps, code analysis, and generation, where the reasoning improves quality and no rigid output shape is required.

If you leave the option untouched, the node sends nothing and the endpoint’s own default applies. Setting it explicitly to true requests thinking regardless of the endpoint default.

> Note on reasoning content: the node does not post-process responses, so reasoning_content returned by the API is not re-sent on follow-up requests. Poolside recommends preserving it across turns in agentic workflows; if you hit quality issues in long multi-step agent runs, this is the likely cause.

Self-hosted deployments

If you run Poolside in your own environment, override Base URL on the credential to point at your deployment’s OpenAI-compatible endpoint:

https:///openai/v1

The model picker and the credential test both follow this override, so the dropdown lists the models your deployment actually serves.

Compatibility

• Node.js >=22.22, and run n8n on a Node version n8n itself supports. See Connection error below — newer Node releases than n8n supports break outbound requests for all AI nodes, not just this one.
• Requires an n8n version in which community chat-model sub-nodes can connect to the AI Agent’s Model input — i.e. AI Agent v2 or newer. Older n8n versions allow-listed only built-in models on that input, so a community chat model will not connect there.

Connection error

If the node fails immediately with a bare Connection error. and no HTTP status, check the Node version running n8n:

node --version

n8n 2.32 declares engines.node: >=22.22. On Node 24+ or 26, requests fail before leaving the process with an internal invalid onError method, surfaced in the UI as Connection error.

The cause is a dependency mismatch inside n8n, not in this package. @n8n/ai-utilities pins undici@^6, while recent Node versions bundle an undici@7-era fetch internally. When the SDK hands its undici@6 dispatcher to the newer global fetch, the handler interface no longer matches and the request is rejected.

This affects every n8n AI node that routes through getProxyAgent, including the built-in OpenAI Chat Model — so if Poolside fails this way, the built-in nodes will too.

Fix: run n8n on a supported Node version.

Homebrew
brew install node@22
PATH="$(brew --prefix node@22)/bin:$PATH" npx n8n
nvm
nvm install 22 && nvm use 22 && npx n8n

Limitations

• Requires an n8n version that provides @n8n/ai-node-sdk. This package has zero runtime dependencies and uses n8n’s official AI node SDK, supplied by the host. See Zero runtime dependencies.
• No response post-processing. Reasoning output is passed through as the API returns it; see Thinking and structured output.
• reasoning_content is not echoed back on follow-up requests. Poolside recommends preserving it across turns in agentic workflows; if you hit quality issues in long multi-step agent runs, this is the likely cause.

Zero runtime dependencies

This package declares no runtime dependencies, which n8n’s verified-community-node
rules require. It builds the chat model through n8n’s official AI node SDK:

"n8n": { "n8nNodesApiVersion": 1, "aiNodeSdkVersion": 1 },
"peerDependencies": { "@n8n/ai-node-sdk": "", "n8n-workflow": "" }

@n8n/ai-node-sdk is supplied by the host n8n installation, so nothing extra is
installed alongside the node. Using it means the model is constructed from the same
@langchain/openai copy n8n itself loads, and n8n’s token-usage tracing, proxy
support and retry handling are wired up automatically.

Releasing

Publishing uses npm trusted publishing: the
workflow authenticates with a short-lived OIDC token instead of a stored npm token, and
npm generates provenance automatically. There is no NPM_TOKEN secret to manage.

First release only

npm cannot create a new package via OIDC — a trusted publisher can only be configured
on a package that already exists. So the first version must be published once by hand.

Provenance is skipped here because it requires a CI OIDC provider and cannot be
generated from a local machine:

npm login
npm publish --provenance=false

If your ~/.npmrc maps the @poolsideai scope to another registry (GitHub Packages,
for example), override it for this command so the package reaches npmjs:

npm publish --provenance=false --@poolsideai:registry=https://registry.npmjs.org

Then configure the trusted publisher on npmjs.com under the package’s
Settings → Trusted Publisher:

| Field | Value |
| — | — |
| Publisher | GitHub Actions |
| Organization or user | poolsideai |
| Repository | n8n-poolside-node |
| Workflow filename | publish.yml (filename only, no path) |
| Environment name | leave blank |
| Allowed actions | npm publish |

All fields are case-sensitive and must match exactly.

Every release after that

1. Bump the version and commit.
2. Tag it and push: git tag v0.1.1 && git push origin v0.1.1
3. Create a GitHub Release from the tag.

The workflow then runs typecheck → lint → build → smoke test → npm publish, with no
credentials involved.

Requirements this depends on

• GitHub-hosted runner. Self-hosted runners are not supported.
• id-token: write permission on the job.
• npm >= 11.5.1. Node 22 bundles npm 10.x, so the workflow runs

npm install -g npm@latest first; without it npm silently falls back to token auth.

• repository.url must match the GitHub repo exactly, or provenance fails.
• Public repository. Provenance is not generated from private repos, even for public

packages.

Development

npm install       # install dependencies
npm run typecheck # tsc --noEmit
npm run build     # compile to dist/ and copy the icon
npm test          # smoke test the compiled output
npm pack          # produce a tarball for local installation

To try the tarball in a live n8n instance:

npm pack
mkdir -p ~/.n8n/nodes
cd ~/.n8n/nodes
npm install /path/to/poolsideai-n8n-nodes-poolside-0.1.2.tgz

Then restart n8n.

Resources

• Poolside API overview
• n8n community nodes documentation

License

MIT