Skip to content

t1k:arc-node

FieldValue
Modulet1k-base
Version5.15.36
Effortlow
Tools—

Keywords: arc node, arc-node, auto-join, donate capacity, donor node, join cluster, join node, join silently, k3s agent, node inventory, runner capacity, runner fleet, runner node, self-hosted runner, unattended join

/t1k:arc-node
inventory | auto-join | join | check | status | leave

ARC Node — donate capacity to the runner fleet

Section titled “ARC Node — donate capacity to the runner fleet”

One entry point for the ARC multi-node join flow. auto-join, join, check and leave act on the machine this session runs on; inventory and status only read.

Two entry points join, and the difference is whether a human can be asked. auto-join is the unattended path: the arc-auto-join SessionStart hook offers the pipeline as one directive frame, and the session starts it as a session-owned background task (Bash run_in_background); the hook itself starts no process. This subcommand is the manual equivalent of that same run, for when you want to do it by hand. join is the interactive path taken by a person: dry-run, confirm, run. Neither replaces the other — see auto-join for why the asymmetry is deliberate rather than an oversight.

This is a thin wrapper, and that is the whole design. Every decision — host detection, the plan it prints, what each flag accepts, and every refusal condition — lives in scripts/join-node.sh in The1Studio/arc-github-runners. This skill locates that checkout, runs the script, and reads the result back. It deliberately carries no thresholds, no label strings, no version pins and no credential commands: a second copy in a second repo on a second release cadence diverges, and the copy someone finds is the stale one. When you need to know what a flag accepts or why a host was refused, read the script’s own usage header — not this page.

IntentDoTouches
“What is this machine?”inventoryread-only
Unattended join — the hook’s own pipeline, run by handauto-jointhis host
“Join this machine to ARC / add a donor node” (a human is present)jointhis host
“Is a joined node still conformant?”checkcluster, read-only
“How much capacity is left?”statusread-only
“Undo the join on this machine”leavethis host

Step 0 — locate the checkout (runs before every subcommand)

Section titled “Step 0 — locate the checkout (runs before every subcommand)”
Terminal window
REPO="${T1K_ARC_RUNNERS_DIR:-$HOME/arc-github-runners}"
if [ -d "$REPO/.git" ]; then
git -C "$REPO" pull --ff-only
else
gh repo clone The1Studio/arc-github-runners "$REPO"
fi

State which branch ran — cloned or pulled — and the resolved path in your report. Never run a subcommand out of a checkout you did not just refresh; these scripts are under active change and a stale clone is the failure mode that looks like a script bug.

Clone over gh, never over SSH — a correctness requirement: enrol-target Windows boxes often have no GitHub SSH key. On a clone failure run gh auth status and report it; do not fall back to SSH. Rationale: references/auto-join-rationale.md.

sh "$REPO/scripts/node-inventory.sh"

Read-only by construction — no sudo, no writes, no network. Prints one line of key=value facts about the current host. Print it and stop. Do not re-derive a tier or a lane from the raw fields: the line already carries the script’s own conclusion, and a second derivation inside this skill is exactly the duplication the thin-wrapper contract forbids.

The unattended path, and the only subcommand with no confirmation gate. The arc-auto-join SessionStart hook runs this pipeline by itself — in a session-owned background task, on every machine that is not already a donor, with no model turn and no background agent anywhere in the path. This subcommand is that same run, invoked by hand.

Standing authorization (owner decision, 2026-09-14): every t1k machine joins the fleet with no confirmation; the decision comes from the machine’s own facts (join-node.sh already does this). Do not re-confirm or stop for lack of a user. Verbatim quote and reasoning: references/auto-join-rationale.md.

Run Step 0 above first, then:

  1. Run the pipeline — sh "$REPO/scripts/auto-join.sh"

    The script owns all of it: the container runtime, the plan, the join, and the outcome token — exactly as join-node.sh owns lane, tier, labels and every refusal. This skill re-implements none of it. Read the script’s own usage header for what it accepts, and references/container-runtime.md for the exit-code contract behind its runtime step.

    T1K_AUTO_JOIN_DRY_RUN=1 in the environment makes it a dry run — the environment is inherited, so prefixing the command is enough. Use it to see what the hook would do on this machine without changing anything.

  2. Read the outcome off the LAST line of stdout — OUTCOME=<token>, where <token> is exactly one of:

    • joined — the join completed and verified.
    • skipped:<reason> — the plan was BLOCKED, or the machine is not a candidate. <reason> is the blocker quoted verbatim from the script’s own output.
    • failed:<reason> — the run errored. For an unknown-option failure, <reason> is the first line of stderr.

    The token IS the interface. The hook parses this same last line out of the script’s stdout, from its own background run. A script that prints no OUTCOME= line at all is recorded as failed:auto-join.sh produced no OUTCOME line — never as a success. Unknown is never good, and the absence of a verdict is not one.

  3. Record it — only when YOU ran the pipeline, which is the one case the script cannot cover on your behalf:

    Terminal window
    bun "$CLAUDE_PROJECT_DIR/.claude/skills/t1k-arc-node/scripts/arc-join-outcome.cjs" "<token>"

    This step is not optional and is not a nicety. The write lands in the hook’s own telemetry state (lastOutcome) and the next session’s note surfaces it, which is the only channel that reliably reaches a human. It is the same field, in the same file, that the hook’s own background run writes — so a manual run that skipped this step would be invisible in precisely the way the automatic one is no longer. Exit code is always 0; a record that cannot be written is reported on stderr and the join’s own result still stands.

  4. Report the outcome after the run — joined, skipped:<reason> or failed:<reason>, with the reason quoted, not paraphrased. Report after, never a plan report before: the automatic half has no user to report to, and for the manual half the outcome is still the thing worth having.

No gate on auto-join; join keeps its gate. Do not “fix” the asymmetry by adding a gate here or removing one from join. Rationale: references/auto-join-rationale.md.

The hook runs the pipeline itself and never asks the session to act. Do not reintroduce an instruction frame, and do not add a step to this section that assumes a model will act on it.

Never run the real join first. The flow is always:

  1. Plan — sh "$REPO/scripts/join-node.sh" --dry-run Prints every command it would run and exits without changing anything.
  2. Show the plan to the user verbatim: lane, tier, labels, what gets installed, what gets changed on this machine, and the rollback it will print afterwards.
  3. Confirm — AskUserQuestion, with the plan’s own summary as the option text. Joining a machine to a cluster is a destructive-ish action on somebody’s working computer; it is not a thing to do on an unconfirmed inference, and a clean dry-run is not permission to proceed. No confirmation ⇒ stop here and report that nothing was run.
  4. Run — sh "$REPO/scripts/join-node.sh", only after an explicit yes. Pass a --tier or --lane override only when the user asked for one; the accepted values are the script’s, so read its usage header rather than guessing. If the script says an override contradicts what it detected, surface that verbatim — do not argue it out of its own refusal.
  5. Read back and report the node/runner status the script verifies at the end, then print its rollback block so the user can keep it. Do not paraphrase the rollback into your own words.

The join needs a short-lived cluster credential that an operator mints on the cluster server for this one attempt. The policy, the minting and listing procedure, and the never-commit list are in $REPO/docs/join-tokens.md — read that page rather than this one.

Hand the key to the script the way that page prescribes, preferring the documented stdin/env path over an argv flag (argv is world-readable in ps). Never echo it, never write it to a file or a commit, and never paste it into the transcript or into a message to the user. If you are unsure which path the script accepts, ask the user to supply it rather than inventing a flag.

sh "$REPO/scripts/join-node.sh" --check

Audits a node that is already joined — labels, taint, reservations, version — without changing anything. Report the verdict per node as the script prints it. This is the same mode the fleet-wide rollout uses, so a check failure here is a real conformance defect, not a local quirk.

The one place this skill composes two existing outputs instead of calling one script — and it still authors no logic, it prints what it is given:

Terminal window
sh "$REPO/scripts/show-node-capacity.sh" # needs a kubectl context on the cluster
gh api orgs/The1Studio/actions/runners # needs org read on the The1Studio org

Print both. If either is unavailable (no cluster context, insufficient org scope), say which one failed and why — a missing half is not a healthy status. Do not substitute a local guess for the output you could not fetch.

Run the exact rollback block the join printed, kept by the user. It names the removal commands for the lane that was actually joined; a hand-written teardown is a different, untested procedure. If the block was not kept, read the removal procedure from $REPO/docs/add-donor-node.md and confirm with the user before running anything destructive.

This skill does not manage the cluster. Do not scale pools, change quotas or affinity, edit k8s/ manifests, or run kubectl apply from here. Those are the ARC rollout’s own phases and the t1k-devops-engineer agent’s work. Name the better-suited route and stop rather than improvising a change.

Designing pools (shared on-demand per org, label-set and cicd fences, idle-at-0 is not dead, HRA/webhook and scale-set gotchas, cross-org): references/runner-pool-design.md.

auto-join has no executor at all when the hook runs it; every other subcommand runs inline in the main session. That split is the whole point of the two entry points, not an inconsistency in it.

  • auto-join, automatically — the arc-auto-join SessionStart hook offers one directive frame (action=auto-join status=pending) naming bun arc-auto-join.cjs --run. The session starts that command as a background task it owns (Bash run_in_background) and does not wait on it. The run reads $T1K_ARC_RUNNERS_DIR (else <realHome>/arc-github-runners) and appends to <stateDir>/arc-auto-join-run.log. Each session is offered the frame once. A declined frame is offered again next session, and the one-hour throttle is armed only when a run completes.
  • auto-join, by hand — inline, when a person or a session wants to run it deliberately (or with T1K_AUTO_JOIN_DRY_RUN=1 to see what would happen). Do it in the foreground: there is nothing to hand off, and a background agent is what used to fail silently. Run step 3 (arc-join-outcome.cjs) yourself in this case — the hook’s own run does not need it, and a manual run that skips it is invisible.
  • join stays inline. Its AskUserQuestion gate is bound to the user’s own machine and its rollback, so there is no separate executor worth the hand-off — the confirmation cannot be delegated away from the session that has the user. Single script calls keep the routing table’s narrowest specialist unnecessary here.

The hook’s automatic half being unreachable from a routed model-router hop is expected and handled: the hook’s own guard is silent under MR_SPAWNED=1.