launcher/CLAUDE.md

sm121-launcher — Claude Code

Read CONVENTIONS.md before any git operation.

Project

Rust CLI for launching vLLM/SGLang inference containers across DGX Spark clusters via SSH. Docker default. tmux alternative.

Stack: Rust edition 2024. clap, tokio, russh, anyhow, tracing, fluent-i18n.

Commands

Action	Command
Build	cargo build
Test	cargo test (128 tests)
Lint	cargo clippy (-D warnings)
Preflight	make check (fmt→clippy→test→≤500 lines)
Dry-run	cargo run -- -d serve --recipe <name>
CI	gh pr checks (when a PR is open)

Architecture

CLI dispatches subcommands: serve, stop, logs, health, doctor, exec, power, tmux, build. orchestrate/ ties cluster selection, before_serve hooks, docker launch, ssh exec. config/ loads config.toml + recipes. docker/ owns build, sync, command, compose, mods. ssh.rs wraps russh for per-node remote execution. See specs/tech-architecture/tech-stack.md for the full architectural map.

Conventions

• Files MUST stay ≤500 lines. Extract submodules near the limit.
• make check MUST pass before every commit. No exceptions.
• NEVER add #[allow(...)] attributes. Refactor to fix clippy.
• NEVER add Co-authored-by footers. Author solely as the user.
• Use Conventional Commits: feat(...), fix(...), docs(...).
• Run sm121 health before stop or power off. The cluster serves live traffic.

Never

• Never run stop or power off without health + user confirmation.
• Never dismiss reproducible gate failures as pre-existing.
• Never proceed on red Preflight. Invoke quick-fix or fix-bug first.
• Never assume the cluster is idle. Verify with health first.

Context Routing

Glob	Source of truth
docker-images/**, host-scripts/**	AGENTS.md (recipe data itself: git.kilork.org/sm121/recipes)
src/**, locales/**	CONVENTIONS.md + specs/
Cluster/recipe/config format questions	AGENTS.md (cluster ops SoT)
Dev workflow / planning / lifecycle	specs/ (bigpowers SoT)

Learned User Preferences

• (none recorded yet)

Workspace Facts

• Project root: /Volumes/main/projects/git.kilork.org/kilork/sm121-launcher
• Remote: git.kilork.org/sm121/sm121-launcher.git
• SSH user: kilork (from config.toml)
• bigpowers scripts: ~/.pi/agent/npm/node_modules/bigpowers/scripts/

Agent Rules

• Workflow Mandate: Use bigpowers skills for tasks. DO NOT write code directly.
• Always Green: Preflight MUST pass before forward work.
• Read specs/ before writing code.
• Write minimum code that solves the stated problem. Nothing extra.
• Run tests after every change. Show evidence before declaring done.
• One clarifying question beats a wrong assumption baked into 200 lines of code.
• Dual SoT: AGENTS.md owns cluster/recipe ops. CONVENTIONS.md owns dev workflow.