Deploy and run ML experiments on local, remote, Vast.ai, or Modal serverless GPU. Use when user says "run experiment", "deploy to server", "跑实验", or needs to launch training jobs.

Run Experiment Deploy and run ML experiment: $ARGUMENTS Workflow Step 1: Detect Environment Read the project's CLAUDE.md to determine the experiment environment: Local GPU ( gpu: local ): Look for local CUDA/MPS setup info Remote server ( gpu: remote ): Look for SSH alias, conda env, code directory Vast.ai ( gpu: vast ): Check for vast instances.json at project root — if a running instance exists, use it. Also check CLAUDE.md for a Vast.ai section. Modal ( gpu: modal ): Serverless GPU via Modal. No SSH, no Docker, auto scale to zero. Delegate to /serverless modal . Modal detection: If CLAUDE.md has gpu: modal or a Modal section, the entire deployment is handled by /serverless modal . Jump to Step 4: Deploy (Modal) — Steps 2 3 are not needed (Modal handles code sync and GPU allocation automatically). Environment contract ( ../shared references/compute env contract.md ): before building or trusting any environment, read the provider's env ledger ( .aris/compute/<provider .md ) — an unchanged spec hash means warm reuse, a changed one means rebuild. New env → write the declarative spec first, render it for this provider's shape, and never declare it ready on import success alone: run the seeded kernel witness, and after any rebuild/doc edit run the agent follows doc pass (a fresh subagent executes the documented invocation verbatim and reports doc vs reality divergence). Vast.ai detection priority: 1. If CLAUDE.md has gpu: vast or a Vast.ai section: If vast instances.json exists and has a running instance → use that instance If no running instance → call /vast gpu provision which analyzes the task, presents cost optimized GPU options, and rents the user's choice 2. If no server info is found in CLAUDE.md , ask the user. Step 2: Pre flight Check Check GPU availability on the target machine: Remote (SSH): Remote (Vast.ai): (Read ssh host and ssh port from vast instances.json , or run vastai ssh url <INSTANCE ID which returns ssh://root@HOST:PORT ) Local: Free GPU = memory.used < 500 MiB. Step 3: Sync Code (Remote Only) Check the project's CLAUDE.md for a code sync setting. If not specified, default to rsync . Option A: rsync (default) Only sync necessary files — NOT data, checkpoints, or large files: Option B: git (when code sync: git is set in CLAUDE.md) Push local changes to remote repo, then pull on the server: Benefits: version tracked, multi server sync with one push, no rsync include/exclude rules needed. Option C: Vast.ai instance Sync code to the vast.ai instance (always rsync, code dir is /workspace/project/ ): Install dependencies per the env contract (ordered phases — pins first, one pip install per phase; see ../shared references/compute env contract.md ): Legacy fallback — requirements.txt only, no env spec: install as one phase, and treat any version fight as the signal to convert to ordered phases: Step 3.5: W&B Integration (when wandb: true in CLAUDE.md) Skip this step entirely if wandb is not set or is false in CLAUDE.md. Before deploying, ensure the experiment scripts have W&B logging: 1. Check if wandb is already in the script — look for import wandb or wandb.init . If present, skip to Step 4. 2. If not present, add W&B logging to the training script: 3. Metrics to log (add whichever apply to the experiment): train/loss — training loss per step train/lr — learning rate eval/loss , eval/ppl , eval/accuracy — eval metrics per epoch gpu/memory used — GPU memory (via torch.cuda.max memory allocated() ) speed/samples per sec — throughput Any custom metrics the experiment already computes 4. Verify wandb login on the target machine: The W&B project name and API key come from CLAUDE.md (see example below). The experiment name is auto generated from the script name + timestamp. Step 4: Deploy Remote (via SSH + screen) For each experiment, create a dedicated screen session with GPU binding: Vast.ai instance No conda needed — the Docker image has the environment. Use /workspace/project/ as working dir: After launching, update the experiment field in vast instances.json for this instance. Modal (serverless) When gpu: modal is detected, delegate to /serverless modal : 1. Analyze task — determine VRAM needs, choose GPU, estimate cost 2. Generate launcher — create a modal launcher.py that wraps the training script using modal.Mount.from local dir for code and modal.Volume for results 3. Run — modal run modal launcher.py (runs locally, GPU executes remotely) 4. Collect results — results return via Volume or stdout, no manual download needed Key Modal settings from CLAUDE.md : modal gpu : GPU override (default: auto select based on VRAM analysis) modal timeout : Max seconds (default: 21600 = 6 hours) modal volume : Named volume for persistent results No SSH, no code sync, no screen sessions needed. Modal handles everything. Local For local long running jobs, use run in background: true to keep the conversation responsive. Step 5: Verify Launch Remote (SSH): Remote (Vast.ai): Modal: Local: Check process is running and GPU is allocated. Step 6: Feishu Notification (if configured) After deployment is verified, check ~/.claude/feishu.json : Send experiment done notification: which experiments launched, which GPUs, estimated time If config absent or mode "off" : skip entirely (no op) Step 7: Auto Destroy Vast.ai Instance (when gpu: vast and auto destroy: true ) Skip this step if not using vast.ai or auto destroy is false . After the experiment completes (detected via /monitor experiment or screen session ending): 1. Download results from the instance: 2. Download logs : 3. Destroy the instance to stop billing: 4. Update vast instances.json — mark status as destroyed . 5. Report cost : This ensures users are never billed for idle instances. When auto destroy: true (the default), the full lifecycle is automatic: rent → setup → run → collect → destroy. Key Rules ALWAYS check GPU availability first — never blindly assign GPUs (except Modal, which manages allocation automatically) Each experiment gets its own screen session + GPU (remote) or background process (local) Use tee to save logs for later inspection Run deployment commands with run in background: true to keep conversation responsive Report back: which GPU, which screen/process, what command, estimated time If multiple experiments, launch them in parallel on different GPUs Vast.ai cost awareness : When using gpu: vast , always report the running cost. If auto destroy: true , destroy the instance as soon as all experiments on it complete Modal cost awareness : Always estimate and display cost before running. Modal auto scales to zero — no idle billing, no manual cleanup CLAUDE.md Example Users should add their server info to their project's CLAUDE.md : Vast.ai setup : Run pip install vastai && vastai set api key YOUR KEY . Upload your SSH public key at https://cloud.vast.ai/manage keys/. Set gpu: vast in your CLAUDE.md — /run experiment will automatically rent an instance, run the experiment, and destroy it when done. Modal setup : Run pip install modal && modal setup . Bind a payment method at https://modal.com/settings (NEVER through CLI) to unlock the full $30/month free tier (without card: $5/month only). Set a workspace spending limit to prevent accidental charges. Set gpu: modal in your CLAUDE.md — ideal for users without a local GPU who need to debug code or run small scale tests. W&B setup : Run wandb login on your server once (or set WANDB API KEY env var). The skill reads project/entity from CLAUDE.md and adds wandb.init() + wandb.log() to your training scripts automatically. Dashboard: https://wandb.ai/<entity /<project .

run-experiment