Skip to content
Get packs

Guide · Agent skill

How to use the Node Connect Troubleshooter agent skill

Updated · written with AI from the project's own documentation and checked against our catalogue data

Node Connect is an agent skill that teaches an AI agent to troubleshoot why a Brigade companion app on Android, iOS, or macOS cannot connect to a Brigade gateway. Instead of guessing, the agent works out which network route is in use, runs Brigade's diagnostic commands, and matches the error message to a specific fix. This guide explains what the skill does, how to install it, how to trigger it, and what to watch for before letting it change gateway settings.

Node Connect Troubleshooterspinabot/brigade · MIT

Quick start

  1. 1Download the ZIP. Download the node-connect skill ZIP from this page.
  2. 2Install the skill. Unzip it into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder, or upload it under Settings → Capabilities → Skills in the Claude apps.
  3. 3Confirm the Brigade CLI works. Make sure the Brigade CLI is installed and you can reach the gateway host. Install the Tailscale CLI only if your setup uses Tailscale.
  4. 4Describe the failure. Tell the agent your route (same machine, local Wi-Fi, Tailscale, or public URL), whether you used QR or manual entry, and the exact error text from the app.
  5. 5Let the agent run the checks. The agent runs the Brigade config and QR checks and reads gatewayUrl and urlSource to see which route the app will use.
  6. 6Apply one fix and rescan. Follow the single recommended diagnosis, generate a fresh setup code, rescan it in the app, and approve any pending device with brigade devices approve --latest.

What is an agent skill, and what does node-connect make the agent do?

An agent skill is a folder containing a SKILL.md file and any supporting files that an AI agent loads when a request matches the skill's description. The node-connect skill is aimed at pairing and connection failures between a Brigade gateway and its companion apps.

When it applies, the agent first decides which case it is in: same machine, emulator or USB tunnel; same local Wi-Fi or LAN; same Tailscale tailnet; or public URL and reverse proxy. It then checks the gateway configuration, reads the setup-code output, and only then proposes a fix. If the setup is unclear, it asks short clarifying questions rather than guessing from a vague report like "can't connect".

  • Works out the one real route from the node to the gateway
  • Runs Brigade's canonical configuration and device checks
  • Maps errors such as "pairing required", "bootstrap token invalid or expired", and "unauthorized" to specific causes
  • Recommends one diagnosis and one route, not a list of possibilities

How do you install the node-connect skill?

Download the ZIP for the skill from this page. You can install it in one of two ways, depending on where you run your agent.

For Claude Code, unzip the download into ~/.claude/skills/ to make it available to you across projects, or into a project's .claude/skills/ folder to limit it to that project. For the Claude apps, open Settings, go to Capabilities, and upload the skill under Skills.

  • Personal install: unzip into ~/.claude/skills/
  • Project install: unzip into the project's .claude/skills/ folder
  • Claude apps: Settings → Capabilities → Skills, then upload the ZIP

What do you need before using it?

The skill assumes the Brigade CLI is installed and that you have access to the gateway host, because its checks run Brigade commands. The Tailscale CLI is only needed if Tailscale is part of your setup.

The skill runs scripts and uses the network, so review what it will execute on a machine you care about.

  • Brigade CLI installed, with access to the gateway host
  • Tailscale CLI, only if Tailscale is part of the setup
  • Permission for the agent to run scripts and use the network

How do you trigger the skill with a natural request?

You do not need a special command. Describe the problem in plain language, ideally including the route you intend to use and the exact message shown in the app. The skill's description covers QR or setup-code failures, cases where local Wi-Fi works but a VPS or tailnet does not, and errors that mention pairing, tokens, or specific config keys.

Quoting the app text exactly helps. The agent will also ask for it if you leave it out.

  • "My Android app says pairing required after I scanned the QR code. Help me fix it."
  • "Local Wi-Fi pairing works, but my phone can't reach my VPS gateway over Tailscale."
  • "The iOS app says bootstrap token invalid or expired. What do I do?"
  • "Brigade qr shows a loopback gateway URL, so my remote phone can't connect. Diagnose it."

What checks does the agent run?

The skill prefers brigade qr --json, because it uses the same setup-code payload that the Android app scans. The agent reads gatewayUrl, which is the endpoint the app should use, and urlSource, which shows which config path won. It also reads several gateway and device-pair settings.

If the gateway points at a remote gateway, the agent also runs brigade qr --remote --json. If Tailscale is involved, it runs tailscale status --json.

brigade config get gateway.mode brigade config get gateway.bind brigade config get gateway.tailscale.mode brigade config get gateway.remote.url brigade config get gateway.auth.mode brigade config get gateway.auth.allowTailscale brigade config get plugins.entries.device-pair.config.publicUrl brigade qr --json brigade devices list brigade nodes status

How do common errors get fixed?

The skill maps each error to a cause. "Pairing required" means the network route and authentication worked, so the pending device needs approval. "Bootstrap token invalid or expired" usually means an old setup code is being used, so a fresh one should be generated and scanned again, including after any URL or auth change.

"Gateway is only bound to loopback" means a remote node cannot connect yet. The fix depends on the route: gateway.bind=lan for same LAN, gateway.tailscale.mode=serve or gateway.bind=tailnet for a tailnet, and a real publicUrl or gateway.remote.url for the public internet. "Unauthorized" points to a wrong token or password, or a Tailscale expectation that does not match gateway.auth.allowTailscale.

  • pairing required: run brigade devices list, then brigade devices approve --latest
  • bootstrap token invalid or expired: generate a fresh setup code and rescan
  • Gateway is only bound to loopback: fix the route, then generate a new setup code
  • unauthorized: check the token or password, or the Tailscale auth setting
brigade devices list brigade devices approve --latest

What safety points should you know about?

The fixes involve auth modes, bind addresses, and public URLs. Changing these can expose the gateway to your network, so review every proposed change before the agent applies it, especially on a production gateway. The skill is not meant for problems unrelated to Brigade node pairing, because its steps only cover Brigade's gateway and device-pair setup.

Pending device requests are a reason to pause. If brigade devices list shows pending requests, the skill says to stop changing network configuration and approve the request first.

  • Review auth, bind, and publicUrl changes before applying them
  • Do not use it for production security changes without a review
  • Approve pending devices only when you recognize them

What people use it for

  • Pairing an Android phone with a Brigade gateway running on a home server on the same Wi-Fi network
  • Getting a phone outside the home to reach a Brigade gateway on a VPS through Tailscale
  • Recovering from an expired setup code that keeps failing with bootstrap token errors
  • Finding out why a QR code advertises a loopback address that remote devices cannot reach
  • Checking whether a pending device pairing request is waiting for approval

Frequently asked questions

How do I install the node-connect agent skill?

Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder. In the Claude apps, you can upload it under Settings → Capabilities → Skills instead.

What do I need to run the node-connect skill?

You need the Brigade CLI installed with access to the gateway host. The Tailscale CLI is only required if Tailscale is part of your setup. The skill runs scripts and uses the network.

Why does my Brigade app say pairing required?

According to the skill, pairing required means the network route and authentication worked and the device is waiting for approval. Run brigade devices list to see the pending request, then approve it with brigade devices approve --latest.

What does bootstrap token invalid or expired mean?

It usually means the setup code is old. Generate a fresh one with Brigade, rescan it in the app, and do this again after any URL or auth change.

Why does local Wi-Fi work but my VPS or Tailscale connection does not?

The skill's guidance is that the route matters. A gateway bound to loopback or a LAN address cannot serve a remote node, so the route needs to match the setup, such as Tailscale Serve, gateway.bind=tailnet, or a real public URL. Do not switch to Tailscale if you only need local Wi-Fi.

Is the node-connect skill free and MIT licensed?

The skill is listed under the MIT licence in the source for this directory entry. Check the licence file in the repository for full terms.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Node Connect suits developers who run Brigade on a VPS or home server and cannot pair a phone, or who see errors like pairing required, unauthorized, or an expired bootstrap token. It asks clarifying questions and works from real command output, which makes it more reliable than guessing. It is not suited to problems outside Brigade's gateway and device-pair setup, or to making production security changes without a careful review.

Download the skill