gcloud-vm
Skill29 starsChanged 5 days agoMITView on GitHub
Provision, start, reach and use Google Cloud VMs — for any real-OS work the macOS host and Docker cannot do. Above all: REAL WINDOWS, which is the only way to check that Frizz still runs there now that tmux is gone. Invoke whenever you think "I need a Windows box" or "I need a Linux box": you can START the standing `nub-linux`/`nub-win` instances or CREATE a fresh one on demand. Carries the gotchas that each cost a cycle — IPs change on every restart, the SSH user is `nub` with a throwaway key per box under `~/.cache/nub/vm-keys/<name>/`, a RUNNING box can be a wedged box (read the serial console), and the whole Windows-SSH bring-up sequence, which is NOT the documented one. AUTH IS NOT A BLOCKER: run each command as `keyward --reason "<what it is for>" -- gcloud …`, and never conclude the VMs are unavailable from a "Reauthentication failed" error, which is the user login, not Keyward.
- Reads credentials
- Deletes or force-pushes
- Installs packages
1 other project uses a version of this.
Adopted by
Most recently taken up by
- nubjs/nubtheir own version, first seen Oct 8, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
- nubjs/nub★ 4.4ksame name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository6 other files it gives its agents.
- AGENTS.mdAGENTS.md
- frizz-artifact-e2eSkill
- frizz-stackSkill
- headless-browserSkill
- real-subsystem-harnessSkill
- visual-reviewSkill
The file
We split this skill into the rules it gives an agent
1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 106
Always reachability-guard a dispatch (ConnectTimeout, timeout) and retry with backoff after a fresh start — sshd is not up the instant …
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Google Cloud VMs
You have gcloud and can create/start/stop VMs yourself. Any time a task needs a real OS the Mac host
and Docker cannot give you, spin one up. Project pullfrog, zone us-central1-a. gcloud runs
through Keyward with no saved configuration, so always pass --project pullfrog and
--zone us-central1-a explicitly. Every gcloud below runs as
keyward --reason "<what it is for>" -- gcloud …; see Auth.
For Frizz specifically, the case that matters is Windows. tmux is gone, so Windows is a supported platform on paper; the only way to keep that true is to actually run there. See the Windows section below — the bring-up is fiddly and the recipe here is the one that works.
Auth: Keyward holds the service-account key
The user credential's refresh token gets revoked periodically by org session-control policy, so an interactive gcloud sign-in is not durable, and none is kept on this Mac. Keyward keeps a service-account key sealed and writes it out for one run at a time:
keyward --reason "frizz: list the VMs" -- gcloud compute instances list --project pullfrog- One Touch ID covers ten minutes of this repository's gcloud runs, and locking the screen ends that.
Tell the maintainer before you raise the sheet. On a locked screen it fails at once with
keyward: not released: screen locked: wait for the unlock (thekeywardskill has how), then run it again. Ifkeyward lsshows no key, ask for one; never sign gcloud in. - The command's first word must be
gcloud. A runner orsh -cis refused, so each gcloud call gets its ownkeyward; the shell around it is fine (IP=$(keyward … -- gcloud …)). - gcloud runs with an empty configuration, and the key's own project is the wrong one. Pass
--project pullfrogon every command and--zoneon everything that takes one. With no terminal attached, pass--quiet, or gcloud's yes/no questions wait forever. - The key manages compute instances and nothing else, so
list/describe/start/stop/create/deletework, and a box must be created with--no-service-account --no-scopes(attaching the default compute account needs a permission the key lacks).
The standing instances, and when to make your own
| Name | OS | Purpose |
nub-linux | Ubuntu 24.04, e2-standard-4 | Real Linux-kernel enforcement (Landlock/seccomp/netns) |
nub-win | Windows Server 2022 | Real Windows |
They belong to the nub project and may be stopped, wedged, or configured for someone else's key —
do not assume you can reach them. (Measured 2026-08-03: nub-win timed out during banner exchange
and nub-win2 refused its key with "Too many authentication failures".) When that happens,
create your own throwaway box rather than fighting theirs, and delete it when done.
keyward --reason "frizz: create a Windows VM" -- \
gcloud compute instances create frizz-win-tmp \
--zone us-central1-a --project pullfrog \
--machine-type e2-standard-4 \
--image-family windows-2022 --image-project windows-cloud \
--boot-disk-size 50GB \
--no-service-account --no-scopes
keyward --reason "frizz: delete the Windows VM" -- \
gcloud compute instances delete frizz-win-tmp --zone us-central1-a --project pullfrog --quiet # a created VM bills its disk even when STOPPEDSSH — user nub, a throwaway key per box, and the IP is DYNAMIC
Each box has its own key, at ~/.cache/nub/vm-keys/<name>/id_ed25519. There is no shared key. Make it
if it is missing; on a Linux box, add-metadata ssh-keys=… then installs it (Windows is below). That
replaces the box's whole ssh-keys value, so a second key would lock the first out: reuse the one there.
KEY=~/.cache/nub/vm-keys/$NAME/id_ed25519
mkdir -p ~/.cache/nub/vm-keys && chmod 700 ~/.cache/nub/vm-keys
mkdir -p -m 700 "$(dirname "$KEY")"
[ -f "$KEY" ] || ssh-keygen -q -t ed25519 -N "" -C "$NAME" -f "$KEY"Re-read the IP on every reconnect, not once per session. A box can be stopped out from under you mid-run and come back on a different address, so a sudden timeout on a previously-working box usually means "it moved", not "it wedged".
IP=$(keyward --reason "frizz: look up the address of $NAME" -- \
gcloud compute instances describe "$NAME" --zone us-central1-a --project pullfrog \
--format='value(networkInterfaces[0].accessConfigs[0].natIP)')
ssh -i "$KEY" -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null \
-o IdentitiesOnly=yes -o IdentityAgent=none -o ConnectTimeout=15 nub@"$IP" 'echo ok'-o IdentitiesOnly=yes -o IdentityAgent=none matters: the maintainer's ssh config routes every connection
through the Keyward agent, where each signature can raise a Touch ID sheet, and IdentitiesOnly alone
still asks the agent. Pass both to every ssh and scp.
Always reachability-guard a dispatch (ConnectTimeout, timeout) and retry with backoff after a fresh
start — sshd is not up the instant STATUS flips RUNNING.
Windows bring-up — the part that is NOT documented anywhere else
A fresh windows-2022 image will NOT accept SSH, and the failure is silent. Four things must be true,
and the official enable-windows-ssh=TRUE metadata alone gets you none of them. Do all of it in ONE
create so you only pay for one reset:
- The image ships no OpenSSH Server. The guest agent logs
Could not determine if openssh version is compatible: could not find versionand gives up. Install it from a startup script. - The guest agent only creates the
nubaccount when it seesssh-keysmetadata, and after the first pass it saysNo new keys found, skipping account setupand never writesauthorized_keys. So pass the metadata AND write the key yourself. nubis an Administrator, and Windows OpenSSH ignores~/.ssh/authorized_keysfor admins. The key must go inC:\ProgramData\ssh\administrators_authorized_keys, with inheritance stripped.- A startup script only runs at boot, so
add-metadatamust be followed bygcloud compute instances reset.
# win-ssh-setup.ps1 — ASCII ONLY (see the codepage gotcha below)
Add-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0 -ErrorAction SilentlyContinue
Set-Service -Name sshd -StartupType Automatic
Start-Service sshd -ErrorAction SilentlyContinue
$key = '<contents of the box's $KEY.pub>'
New-Item -ItemType Directory -Force -Path "C:\Users\nub\.ssh" | Out-Null
Set-Content -Path "C:\Users\nub\.ssh\authorized_keys" -Value $key -Encoding ascii
$adm = "C:\ProgramData\ssh\administrators_authorized_keys"
Set-Content -Path $adm -Value $key -Encoding ascii
icacls.exe $adm /inheritance:r /grant "Administrators:F" /grant "SYSTEM:F" | Out-Null
Restart-Service sshd -ErrorAction SilentlyContinuekeyward --reason "frizz: create a Windows VM that takes SSH" -- \
gcloud compute instances create frizz-win-tmp --zone us-central1-a --project pullfrog \
--machine-type e2-standard-4 --image-family windows-2022 --image-project windows-cloud \
--boot-disk-size 50GB --no-service-account --no-scopes \
--metadata enable-windows-ssh=TRUE,ssh-keys="nub:$(cat "$KEY.pub")" \
--metadata-from-file windows-startup-script-ps1=win-ssh-setup.ps1
keyward --reason "frizz: reset the Windows VM so its startup script runs" -- \
gcloud compute instances reset frizz-win-tmp --zone us-central1-a --project pullfrogThen poll for $env:PROCESSOR_ARCHITECTURE to come back AMD64. Read the progression: Operation
timed out → the network path or sshd is not up; Connection refused → the path is open and sshd is
not listening; Disconnected from … port 22 → sshd is up and your key is being rejected (go fix
administrators_authorized_keys).
Windows gotchas that each cost a cycle
- The home directory is
C:\Users\nub.<HOSTNAME>, notC:\Users\nub. Always use$env:USERPROFILE; a hardcodedC:\Users\nub\…silently misses. nub.exeneeds the MSVC runtime. A bare Server 2022 has none, and the only symptom is exit code-1073741515(0xC0000135, DLL_NOT_FOUND) with no message. Installvc_redist.x64.exefirst.- This repo needs pnpm, not npm.
npm installfailsEUNSUPPORTEDPROTOCOL Unsupported URL Type "workspace:". Installpnpm@10globally, thenpnpm install --no-frozen-lockfile. - Write every remote PowerShell script as ASCII + CRLF. PowerShell 5.1 reads a BOM-less script in
the ANSI codepage, so one UTF-8 character anywhere — an em-dash in a comment is the usual culprit —
fails with
The string is missing the terminator, and the error points at the LAST line of the file rather than the offending one. -Filewith a path containing the profile directory can fail to resolve; use-Command "& \"$env:USERPROFILE\script.ps1\""so the guest expands the path.- PowerShell's
Tee-Object/Out-Filewrite UTF-16LE by default. A log youscpback will look like it has NUL bytes between every character;iconv -f UTF-16LE -t UTF-8, or pass-Encoding utf8. IsOutputRedirectedis always True over SSH, so anyis_terminal()branch takes the non-TTY path and first-run console behavior cannot be exercised. That needs a ConPTY harness or RDP.- A long run will outlive a foreground command. Redirect to a file on the GUEST, run the SSH
command in the background, and poll the guest-side file — an SSH pipe left open for ten minutes gets
client_loop: send disconnect: Broken pipe, and the harness reports the pipeline's exit code, so a dead run arrives labelled "exit 0".
Other gotchas
- A RUNNING instance can be a DEAD instance — read the serial console FIRST.
This diagnosed an 11-day SSH-dead box instantly (an OOM had wedged sshd). It beats guessing "network problem" every time, and on Windows it is the only way to see what the guest agent is doing.keyward --reason "frizz: read $NAME's serial console" -- \ gcloud compute instances get-serial-port-output "$NAME" --zone us-central1-a --project pullfrog | tail -40 - Judge results by behavioral/differential evidence — EPERM vs success, a before/after delta, a control that must still fail — not wall-clock, since a shared VM may be contended.
- Delete your box.
keyward --reason "frizz: delete the VM <name>" -- gcloud compute instances delete <name> --zone us-central1-a --project pullfrog --quiet, andrm -rf ~/.cache/nub/vm-keys/<name>. Verify withinstances listthat only the pre-existing ones remain.
Worked example: what this caught
Driving a real windows-2022 box on 2026-08-03 found two Windows bugs that every local gate had
passed: a Codex cwd validator gated on startsWith("/") (rejecting every C:\ path — 41 tests), and
the broker resolving claude to npm's #!/bin/sh shim instead of the native claude.exe, which broke
every Claude dispatch on Windows. The second one also killed the obvious fix: preferring .cmd via
PATHEXT returns a path Node refuses to spawn without a shell (EINVAL, CVE-2024-27980). Only running
it on the real OS surfaced that — reasoning about it produced a confident wrong answer.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

