N8n:nathan

Nathan — repo-local test instances

Nathan is n8n's internal bot that deploys throwaway test instances from a branch

or Docker image. It's normally driven from Slack (/nathan ...); this skill runs

the same commands from the repo via pnpm nathan.

Prerequisites

• No tunnel setup needed. Nathan replies asynchronously through a short-lived

public tunnel that the script opens for you (npx localtunnel). A deploy to a

new test-<name> also polls that instance URL directly, so it still reports

success even if the tunnel drops. (Redeploying a name that's *already up* skips

the poll — it can't tell the old instance from the new — so it falls back to the

tunnel; prefer a fresh name when you need the reliable report.)

• A token in ~/.n8n/dev/nathan-token. If a command reports no token, **ask the

user for one** — point them at the form

(https://internal.users.n8n.cloud/form/d6d34a2f-4899-4ee8-afc8-f8c41a8a243d),

where they log in with their n8n account and copy the token from the response —

then save it for them (the script's interactive paste prompt needs a real

terminal, so as an agent use the subcommand):

  pnpm nathan set-token '<PASTED_TOKEN>'

Offer a test instance

Only when it's worth it

Use judgement — don't offer for every branch. Offer when the change is

something a person would actually want to click through in a running instance:

• New features / feature branches
• UI / editor changes, node changes, workflow-execution or behaviour changes
• Larger or user-facing diffs

Skip the offer (a test instance adds nothing) for:

• Dev tooling, CI, build config, scripts (like this one)
• Docs-only or tests-only changes
• Tiny bug fixes, no-behaviour-change refactors, dependency bumps

When skipping, don't nag — at most mention once that a test instance is available

on request.

Offer after opening a PR, and re-offer on push

After you open a PR for a branch that warrants it, offer a live test instance.

Also re-offer whenever you git push new commits to such a branch — the

deployed instance reflects the pushed code, so a new push means a new build worth

redeploying. Don't just ask a bare yes/no — look at the diff and **propose a

sensible profile**, then let them confirm or adjust. For example:

> "Want a test instance for this? Based on the diff I'd deploy it with instance AI

> enabled (--ai) since it touches the AI assistant. Sound good, or a different

> license?"

Pick the profile from the PR contents

Inspect what the PR changes (git diff --stat origin/master...HEAD and the file

paths / feature area), then choose:

| PR touches… | Suggest | Why |

|---|---|---|

| AI features — @n8n/nodes-langchain, @n8n/instance-ai, the AI assistant/builder, N8N_AI_*, "askAi"/agent code | --ai | Enables instance AI (and defaults the license to pro2) so the AI features actually run |

| License-gated / enterprise features — .ee.ts files or /ee/ dirs, license checks (@n8n_io/license-sdk, hasFeature), SSO/SAML/OIDC/LDAP, RBAC/roles/scopes, projects, variables, external secrets, source control/environments, log streaming, insights, folders | --enterprise | The feature is gated behind a license and won't be testable on community |

| A specific gated feature/quota you want on/off | --license pro2 --featureOverride <featureKey>:<value> | Bakes the override into a generated license (community/enterprise can't be overridden) |

| Anything else — core nodes, generic UI, non-gated bug fixes | *(nothing — community default)* | No license needed |

If both AI and enterprise apply, combine them: --ai --enterprise. When unsure,

state your best guess and ask. Run pnpm nathan help for the full flag reference.

Deploy

pnpm nathan deploy <branch-name> test-<short-name> [flags]

Nathan builds the branch image (a few minutes) and the command prints the instance

URL (https://test-<short-name>.stage-app.n8n.cloud, login [email protected] /

helloWorld7). Relay that URL to the user.

Common commands

pnpm nathan help                                   # full option reference
pnpm nathan deploy my-branch test-my-feature       # community license
pnpm nathan deploy my-branch test-sso --enterprise # enterprise license
pnpm nathan deploy my-branch test-ai --ai          # instance AI (license -> pro2)
pnpm nathan deploy nightly test-nightly            # deploy the n8nio/n8n:nightly image

Key flags (after the deploy args): --license community|enterprise|starter|pro1|pro2|trial,

--enterprise, --ai, -e KEY=value (repeatable), --featureOverride key:value

(needs a generated license).

local caveat

pnpm nathan local ... generates a runnable docker run bundle, but Nathan

delivers it as Slack file attachments (run-n8n.sh + .env), not to the

terminal — they land in #updates-pnpm-nathan

(https://n8nio.slack.com/archives/C0BGVHZ0SCW). deploy and help return fully

in the terminal.

Do not invent a NATHAN_SLACK_CHANNEL. Leave it unset (it defaults to

updates-pnpm-nathan); only set it if the user explicitly gives you a channel id.

Unsupported

Queue mode, multi-main, and non-SQLite databases are not supported by Nathan.