brancher-spinup

Brancher Spinup

Creates a Brancher node, waits for it to become SSH-reachable, sanitizes it (anonymize PII, reset admin credentials, sandbox payment gateways/API keys), and only then reports it ready with its access URL. All of this happens in a single MCP tool call — brancher_create — because the underlying create -> wait -> sanitize -> report-ready sequence is non-bypassable by design: brancher_create IS the gated flow, not a raw/unsanitized creation call. It is structurally impossible to get an access URL back for a node that has not finished sanitizing, and there is no other tool that creates a node — brancher_create is the sole node-creation entry point this plugin exposes.

Flow

1. Identify which Hypernode/app. Hypernode API tokens are scoped per app, not account-wide — if the user's request doesn't say which app to target, call brancher_apps first and show the configured list before calling any other tool. Never guess an appname. If exactly one app is configured, it's fine to proceed with it — just tell the user which one you're using rather than asking a pointless confirmation question.

2. Ask for a label if the user hasn't given one. brancher_create requires at least one label (e.g. a ticket number like ticket-123 or a short description) — it is not optional, and the call will fail without one. Don't invent a label on the user's behalf; if they haven't mentioned a ticket/reason, ask.

3. Call brancher_create with appname, labels, and optionally clear_services (defaults to clearing cron if omitted). This one call covers the entire create -> wait -> sanitize -> ready sequence — do not poll or call other tools in between.

   • This call can take up to ~20 minutes (Hypernode's own Control Panel states node setup can take up to 15 minutes before the node even becomes SSH-reachable, before sanitization runs on top of that). Because of this, run brancher_create via a background Agent/Task call rather than blocking the current session inline — tell the user you're spinning it up in the background, then report back with the result (ready, or a clear failure) when the background agent completes. Do not poll for progress in the foreground; the background agent's single completion notification is the signal.
   • Run the background agent on the cheapest available model (e.g. Haiku), not the session's default model. This task is a single deterministic tool call plus reporting the structured result back verbatim — no real reasoning, judgment, or code-writing happens in that agent, so there's no reason to spend a larger model's tokens on it just because it runs a long time. If a background-agent invocation doesn't expose a model override, pick the smallest/cheapest agent type or model setting available rather than defaulting silently to whatever the session is already running.
   • If the calling session ends before the background agent completes, do not blindly retry brancher_create next session. Check brancher_list(appname) first — a real node may already exist and still be provisioning (or already sanitized-and-ready, if you're very unlucky with timing) from the interrupted attempt. There is no way to "resume" just the wait+sanitize step on an existing node (by design — brancher_create is the only entry point so sanitization can never be skipped), so if a stale node is found, delete it first (brancher_delete, confirming) rather than leaving it to accrue cost indefinitely, then start a fresh brancher_create call.
   • If the app has no configured token (HYPERNODE_API_TOKENS), or is not on a Falcons-eligible plan, or no label was provided, the call fails immediately before anything is created. Surface that error message to the user verbatim — it already explains which guardrail was tripped.