t1k:arc-node
| Field | Value |
|---|---|
| Module | t1k-base |
| Version | 5.15.36 |
| Effort | low |
| 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
How to invoke
Section titled “How to invoke”/t1k:arc-nodeinventory | auto-join | join | check | status | leaveARC 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.
Decision Tree
Section titled “Decision Tree”| Intent | Do | Touches |
|---|---|---|
| “What is this machine?” | inventory | read-only |
| Unattended join — the hook’s own pipeline, run by hand | auto-join | this host |
| “Join this machine to ARC / add a donor node” (a human is present) | join | this host |
| “Is a joined node still conformant?” | check | cluster, read-only |
| “How much capacity is left?” | status | read-only |
| “Undo the join on this machine” | leave | this host |
Step 0 — locate the checkout (runs before every subcommand)
Section titled “Step 0 — locate the checkout (runs before every subcommand)”REPO="${T1K_ARC_RUNNERS_DIR:-$HOME/arc-github-runners}"if [ -d "$REPO/.git" ]; then git -C "$REPO" pull --ff-onlyelse gh repo clone The1Studio/arc-github-runners "$REPO"fiState 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.
inventory
Section titled “inventory”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.
auto-join
Section titled “auto-join”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:
-
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.showns lane, tier, labels and every refusal. This skill re-implements none of it. Read the script’s own usage header for what it accepts, andreferences/container-runtime.mdfor the exit-code contract behind its runtime step.T1K_AUTO_JOIN_DRY_RUN=1in 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. -
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 asfailed:auto-join.sh produced no OUTCOME line— never as a success. Unknown is never good, and the absence of a verdict is not one. -
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. -
Report the outcome after the run —
joined,skipped:<reason>orfailed:<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:
- Plan —
sh "$REPO/scripts/join-node.sh" --dry-runPrints every command it would run and exits without changing anything. - 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.
- 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. - Run —
sh "$REPO/scripts/join-node.sh", only after an explicit yes. Pass a--tieror--laneoverride 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. - 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.
Where the join key comes from
Section titled “Where the join key comes from”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.
status
Section titled “status”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:
sh "$REPO/scripts/show-node-capacity.sh" # needs a kubectl context on the clustergh api orgs/The1Studio/actions/runners # needs org read on the The1Studio orgPrint 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.
Out of scope — refuse and route
Section titled “Out of scope — refuse and route”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.
Executed by
Section titled “Executed by”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 — thearc-auto-joinSessionStart hook offers one directive frame (action=auto-join status=pending) namingbun arc-auto-join.cjs --run. The session starts that command as a background task it owns (Bashrun_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 withT1K_AUTO_JOIN_DRY_RUN=1to 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.joinstays inline. ItsAskUserQuestiongate 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.