<!-- AUTO-GENERATED from SKILL.md.tmpl — do not edit directly --> <!-- Regenerate: bun run gen:skill-docs -->

/ubicloud — Ephemeral VMs for heavy runs

Telemetry (run last)

After workflow completion, log telemetry with ONE command. OUTCOME is success/error/abort/unknown; SESSION_ID and TEL_START are the values the preamble's skill-start output echoed. It also drains the artifacts-sync queue (the former skill-end sync step — do not run gstack-brain-sync separately).

PLAN MODE EXCEPTION — ALWAYS RUN: This writes telemetry to $GSTACK_STATE_ROOT/analytics/, matching preamble analytics writes.

~/.claude/skills/gstack/bin/gstack-skill-end --skill "ubicloud" --outcome OUTCOME \
  --session-id "SESSION_ID" --tel-start "TEL_START" --used-browse USED_BROWSE \
  --error-message "ERROR_MESSAGE" --failed-step "FAILED_STEP" 2>/dev/null || true

Replace OUTCOME and USED_BROWSE (yes/no) before running; substitute SESSION_ID/TEL_START from the skill-start echoes. ERROR_MESSAGE/FAILED_STEP are "" unless outcome is error. If the command is missing (stale install), skip telemetry — it never blocks the workflow.

Why this skill exists

A full suite or verify that takes an hour on a 4-core sandbox takes minutes on a standard-16 VM, and a VM that outlives its run costs the whole project its shared vCPU quota. This skill is one runner with the discipline built in: every VM carries its owner and a TTL in its name, any later run reaps expired VMs, the create is refused before the quota fills, a silent remote command is killed with its last output instead of hanging, and a repository's verify is one committed definition rather than a wrapper per lane.

U=~/.claude/skills/gstack/bin/gstack-ubi is the only entry point (it runs scripts/ubicloud/ubi-runner.sh; $U help lists every command). Every fence below starts by binding U, because a host that runs each fence in a fresh shell (Capy's bash tool does) keeps nothing from the one before.

Step 0: Prerequisites (set/unset only)

U=~/.claude/skills/gstack/bin/gstack-ubi
[ -n "${UBICLOUD_API_KEY:-}" ] && echo "UBICLOUD_API_KEY: set" || echo "UBICLOUD_API_KEY: unset"
export UBI_OWNER=lane7   # your thread or session code: lowercase letters and digits; it names your VMs
$U owner

UBICLOUD_API_KEY (or UBICLOUD_API_TOKEN) is a project-scoped token. When it is unset, ask for it as an environment variable and stop; never echo it, write it to a file or commit, and never run env, printenv or set -x while it is in the environment. UBI_OWNER is required: up, run and verify refuse without it (UBI_OWNER_REQUIRED), because a VM nobody can name is a VM nobody cleans up. usage and list --mine key on it, so set it before the first up of every session and on every machine.

Step 1: Preflight the project

U=~/.claude/skills/gstack/bin/gstack-ubi
$U records        # VMs this machine created and never confirmed gone
$U list --mine    # this owner's VMs in the project
$U usage          # VMs and vCPUs per owner: who holds the shared quota

A VM in records but absent from list is already gone: $U down <name> forgets it. A VM in the project under another owner is theirs; leave it (its TTL will reap it). Every up runs $U reap first, destroying any VM whose -t<hours> TTL ended more than ten minutes ago, whichever owner made it, and this owner's own ubirun-<UBI_OWNER>-* names with no TTL once they are UBI_LEGACY_HOURS old (default 4). Another owner's TTL-less VM, an untagged one and names outside the ubirun- prefix are never reaped.

Quota: with UBI_QUOTA_VCPUS=<project ceiling> exported (or after one refusal, whose maximum the runner remembers), up adds the size's vCPUs to the project's running VMs and refuses before the create request when that exceeds the ceiling; UBI_QUOTA_WAIT=<seconds> waits for room instead. Prefer waiting or a smaller size over a second lane of VMs.

Step 2: Launch watched, with a TTL that covers the run

The runner destroys its VM on every exit path, but only while it is alive. A process killed by a sleeping machine, a dropped terminal or a cancelled background operation leaves its VM until the reaper. So:

• On Capy, run it with the bash tool in execution: "background" with a timeout that covers setup plus the run, then wait on the operation id. Never detach it, and never leave it unwatched when the thread goes idle.
• In Claude Code, run it under gstack-detach and poll the log for its ### gstack-detach EXIT=<code> ### sentinel.
• Set UBI_TTL_HOURS above the longest plausible run (default 3; 1-999) and name the expected duration in the thread before launching anything over an hour. A run that outlives its TTL is reaped by the next up anywhere.

The runner prints <name> carries a <n>h TTL ...; if this process dies first: <self> down <name> right after the VM is ready; quote that line in your report so the next turn can clean up without guessing.

U=~/.claude/skills/gstack/bin/gstack-ubi
cd /path/to/checkout
UBI_TTL_HOURS=3 $U run --setup scripts/ubicloud/bootstrap.sh -- 'make test'

run creates the VM (-s SIZE, default standard-16; -l LOCATION, default eu-central-h1), streams the checkout (tracked files, untracked files that are not ignored, and .git, so uncommitted edits are tested), runs the bootstrap once, runs the command in a login shell with umask 022, copies --pull REMOTE_GLOB:LOCAL_DIR artifacts back and destroys the VM. It exits with the command's status. --env K=V passes a literal; --pass NAME forwards a local variable's value without printing it (never UBICLOUD_*: the runner's own credentials stay on this machine); --keep skips teardown for debugging, and then $U down <name> is yours to run.

Step 3: One committed verify per repository

Per-lane wrappers drift: a stale one skipped a service start and failed a full verify for nothing. Commit the definition once as .gstack/ubicloud.json and run it through verify, which refuses when the file is missing:

{
  "setup": "scripts/ubicloud/bootstrap.sh",
  "command": "bash scripts/ubicloud/verify.sh",
  "size": "standard-16",
  "env": ["CI=1"],
  "pass": ["ANTHROPIC_API_KEY"],
  "pull": ["work/<repo>/.context/verify-logs:.context/ubicloud"]
}

U=~/.claude/skills/gstack/bin/gstack-ubi
$U verify --pass ANTHROPIC_API_KEY   # the committed definition; grant each name it lists under pass
$U verify --trust-config             # or grant every name the file lists
$U verify -s standard-30             # flags override the file
$U verify -- 'pnpm e2e'              # a different command on the same bootstrap

The file is repository content, so it gets no reach beyond the checkout on its own: setup and the local side of each pull must be relative paths that resolve inside --src (absolute, ~ and .. paths are refused before any API call, and each destination is resolved again right before its pull), and a name under pass is forwarded only when your command line grants it with --pass NAME or --trust-config. Run verify only on a tree you have reviewed: its bootstrap and command run on the VM with whatever you granted.

The bootstrap mirrors the repository's CI job: toolchain, dependencies, services, and for browser tests xvfb plus sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0 (a stock Ubuntu 24.04 VM has neither; clang and python3-venv are absent too). Relative setup paths resolve against --src (default .). gstack's own definition is bun run test:ubicloud (the free suite with the CI lane's environment) and gstack-pregate --stage tests --remote under 8 cores.

A long verify can list tiers: [{"name": "unit", "command": "make unit"}] for command. A rerun reuses recent passes (UBI_VERIFY_RESUME:), reruns a fail only with --rerun-failed, and ends with UBI_VERIFY: ….

Step 4: Read the result

• ubi-runner: command exited <rc> after <n>s is the verdict line; the exit status is the command's.
• UBICLOUD: left=<n> owner=<o> vm=<name> others=<n> follows teardown. Report it with every result: left=0 means this run's VM is confirmed gone. left=1 or left=unknown turns a passing command into exit 1; run the printed down command now. others counts this owner's other VMs, for information. run --keep prints left=1 ... kept=1 instead and keeps its exit status.
• Exit 124 with watchdog: <phase> printed nothing for <n>s (or ran <n>s) means the remote hung or exceeded its budget; the last 40 lines follow. Diagnose from them before rerunning; a hang is a failure, not infrastructure. Defaults: UBI_IDLE_TIMEOUT=1800, UBI_RUN_TIMEOUT=0 (unlimited), UBI_HEARTBEAT=300 (a heartbeat: line with elapsed time and output age).
• quota preflight refused or quota refused lists the project's VMs by owner; wait (UBI_QUOTA_WAIT), reap, or use a smaller size. Do not start more lanes.
• WARNING: failed to destroy <name> or could not confirm ... is gone: run the printed down command now and report it; never end a turn with that line unanswered.

Report the VM name, size, wall time and verdict line in the thread so the cost is visible: a standard-16 run is billed from create to confirmed teardown.

Resume checklist after a wake or a machine swap

1. Rerun the same command first: a run whose runner died or detached (UBI_DETACHED, exit 129 after a HUP) reattaches to its live VM and skips a finished setup (UBI_ATTACH_BUSY: another runner owns it; exit 125 UBI_ATTACH_LOST: no status; UBI_REATTACH_TTL_SHORT: a fresh VM took over).
2. $U records and $U list --mine, then $U down anything of yours that no rerun will reattach to.
3. After a machine swap nothing reattaches; tier checkpoints on a Drive (UBI_CHECKPOINT_DIR) still count.
4. A background log with no exit sentinel and no VM is an interrupted run, not a pass; rerun it.
5. Measure before/after pairs on the same size and location, never one side local and the other remote.