gabrielmoreira 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). Adeployto a newtest-<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 test@n8n.io /
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.