Skip to content

t1k:marketing:store:vps-management

FieldValue
Modulestore
Version0.14.9
Effortmedium
Tools—
/t1k:marketing:store:vps-management

Three surfaces, all on https://vps.the1studio.org (NetBird-only; run netbird up first):

  1. REST via vps.sh (scripts/) — list + rename + describe + power. Bearer AGENT_TOKEN.
  2. GUI via vps-gui.mjs (scripts/) — drive the machine’s remote desktop (browser RDP through Guacamole) with a headless browser. Uses your GitHub SSO session, not a token.
  3. Headless desktop via vps-screen.mjs (scripts/) — same remote-desktop control over the agent token, no SSO login or local browser (no file upload).

Paths below are relative to this skill’s directory. scripts/vps.sh takes the agent token from VPS_API_TOKEN when it is set, and otherwise reads it from the studio vault (see “Agent token”). Never print or log any token.

Each VPS signs in to exactly 1 account, ever. The mapping is strictly 1-1 and permanent (one Google/AdMob/store account per machine; rule set by the user on 2026-11-05, replacing the 2026-10-21 wording). A VPS is never reused for a different account, even after its account is dropped, sold, banned or moved. A new account always gets a new VPS.

Before signing in on a machine, shot it and check that no other account is already signed in. A machine that has ever held another account is not eligible, so the answer is a new VPS, never a different machine chosen case by case. The machine’s dashboard description records which account it holds, so the mapping can be read with vps.sh list.

  • Taking over an account bought from a seller: references/acquire-account-from-seller.md covers vaulting the seller’s values, the rotation, and the Google limits that can stretch it to about two weeks.
  • Human sign-in, the owner pastes the password (the agent never types it): references/human-sign-in-no-see.md.
Terminal window
bun add -g playwright && bunx playwright install chromium # or playwright-core + system chromium
./scripts/vps-gui.mjs login # opens a real window; log in with GitHub once (~24h session)

The global install is found via Bun’s global root (scripts/lib/playwright-loader.mjs) — a bare ESM import('playwright') cannot see a global package, so a plain bun add playwright beside the script also works.

Terminal window
./scripts/vps.sh list # provider, id, displayName (store alias, e.g. DoubleCat), powerState, ip, os, description
./scripts/vps.sh alias <provider> <id> "New Name" # PUT rename of the machine (dashboard display name; screen route reads it)
./scripts/vps.sh alias <provider> <id> --clear # DELETE the alias, back to the provider label
./scripts/vps.sh desc <provider> <id> "text" # set the machine's description (agent + human editable)
./scripts/vps.sh desc <provider> <id> --clear
./scripts/vps-gui.mjs list # same fleet + which machines have an RDP connection

A provider whose login expired shows an ERROR row; the others still list.

Terminal window
./scripts/vps.sh power <provider> <id> <start|stop|reboot|pause|resume> --confirm
  1. Ask the user first, naming the exact machine (label + id) and action. --confirm is a friction gate, not authorization.
  2. Take provider/id from list. Never test against a live machine: on 2026-09-27 a “rejection test” paused the real Geliyun box.
  3. Geliyun is an energy-saving SKU: it freezes when idle and wakes with start; after waking, give it ~1 min before RDP.
  4. Re-run list after the call and report the resulting powerState.

Same capability as vps-gui.mjs (view + drive the remote desktop) but fully headless over the agent token (VPS_API_TOKEN, see “Agent token”) — no SSO login, no local playwright; the browser runs inside the dashboard container. Use this for automated flows.

Terminal window
./scripts/vps-screen.mjs shot "PartyUs" # screenshot -> PNG path (read-only)
./scripts/vps-screen.mjs click "PartyUs" 800 450 --confirm
./scripts/vps-screen.mjs type "PartyUs" "text" --confirm
./scripts/vps-screen.mjs key "PartyUs" Control+s --confirm
  • Reference machines by displayName (store alias) or <provider>/<id>; the script resolves it via GET /servers and addresses /servers/<provider>/<id>/screen. GET /servers reports the alias as displayName and falls back to the provider label when none is pinned, so a machine you cannot yet address by name is the one to pin: vps.sh alias <provider> <id> "New Name" (PUT /servers/<provider>/<id>/alias; see “Read” above).
  • Key combos use Playwright names (Control+s, Alt+F4); ctrl/alt/shift/cmd are normalized.
  • Sessions are attributed to a human: identity auto-derives from the gh CLI login (e.g. junchenttd → agent-junchenttd in the Discord usage thread). VPS_AGENT_USER overrides; OS user is the fallback.
  • Mutating commands need --confirm, same rules as power actions.
  • A shot opens a real RDP session. Windows RDP is single-session: shooting a machine someone is using can disconnect them. Check nobody is active (Discord usage thread / dashboard) before shooting; never shoot PartyUs while it is occupied.
  • Input lands in whatever is focused — open a new tab first. A shot often shows a remote Chrome already holding a live store-console session (Play Console, App Store Connect). Typing or clicking into that page drives a real, logged-in console; a stray keystroke there can edit a live listing. Open a new tab with the tab strip’s ”+” button, then type the URL into that tab — never type into the page the console is already showing. Verify with shot what is focused before any typing or clicking anywhere.
  • No file upload here — use vps-gui.mjs when a build must be dropped into the session (it also covers interactive SSO use).

Works on any machine with an RDP connection (see list; create one in the dashboard — expand the server, fill the rdp row). Reference machines by display name (alias) or IP.

Terminal window
./scripts/vps-gui.mjs shot "DoubleCat" # screenshot -> PNG path (read-only)
./scripts/vps-gui.mjs click "DoubleCat" 800 450 --confirm
./scripts/vps-gui.mjs type "DoubleCat" "text" --confirm
./scripts/vps-gui.mjs key "DoubleCat" Control+s --confirm
./scripts/vps-gui.mjs upload "DoubleCat" ./build.aab --confirm

Rules:

  1. shot is read-only. click/type/key/upload need --confirm — same friction gate as power; ask the user before destructive in-GUI actions (closing apps, deleting files, submitting store releases).
  2. Machines may be in use RIGHT NOW. A new RDP connection can evict the current user (or fail against a live session). shot first — if a document/app is visibly open mid-work, confirm with the user before clicking around.
  3. Workflow: shot → decide → act → shot again to verify. Coordinates are pixels inside the last screenshot (viewport 1600x900). A saved browser zoom on the guac tab rescales them: the script divides by the page’s devicePixelRatio before clicking, so pass the pixel you measured in the PNG unchanged — never pre-scale it yourself, or the click lands short by the zoom factor (at 75% zoom, an unscaled click misses by a margin that grows toward the bottom-right).
  4. If a machine has no RDP connection, say so and create one in the dashboard; never guess credentials.
  5. If the display never appears, the machine is probably off/frozen — check scripts/vps.sh list, wake it, retry.
  6. SSO expired (a login reminder is printed)? Run ./scripts/vps-gui.mjs login — it needs a human to click through GitHub.
  7. A multi-step flow cannot be composed from separate invocations. Each command opens and closes its own browser, and every new connection resizes the remote desktop and re-lays-out its windows, so coordinates captured in step N are stale by step N+1 and a half-finished console form can scroll out from under the next click. Re-shot immediately before every mutating command, and prefer one short flow per invocation over a long click chain.

upload drops the file through Guacamole’s own drag-drop handler, which streams it over the tunnel to guacd. Delivery is decided on the remote host, not in the browser: guacd accepts the stream and then discards it silently when the RDP session negotiated no drive-redirection channel. The command therefore never claims the file landed:

  • It prints queued … unconfirmed on disk when the drop did become a transfer, and tells you to verify with ls ~/thinclient_drives/GUACFS (or the remote progress dialog) before treating it as delivered.
  • It exits non-zero when no transfer started at all — the usual cause is a missing ~/thinclient_drives/GUACFS mount on the machine, and Guacamole’s own Upload Files toolbar menu fails the same way on the same box.

When drive redirection is broken, the fallback that works:

  1. Put the file in a Google Drive folder shared “anyone with link” (temporarily).
  2. Download it inside the remote Chrome from https://drive.usercontent.google.com/download?id=<id>&export=download.
  3. Set the folder back to Restricted in the same session. The sharing window is a real exposure — do not leave it open.

The store sessions live in the VPS’s own Chrome (e.g. DoubleCat = Play Console account with the studio’s apps). Typical flow: shot → open a new tab with the tab strip’s ”+” button → type the URL into that tab → key Enter → open the app → Production/Testing → create release → upload the .aab → ask the user before any “Send to review”/rollout click — store releases are irreversible from the seat. Navigating in a new tab keeps the console session the shot revealed untouched; typing into the focused console page risks a stray keystroke on a live listing. Before uploading, shot and check the Chrome session isn’t mid-edit by a teammate (unsaved release draft = coordinate first).

No shell access to machines, no RDP passwords through this skill (they live only in Guacamole), no console links.

scripts/vps.sh reads the bearer token from VPS_API_TOKEN; when that is unset it reads the studio vault name vps-management:agent-token itself. To set it explicitly, or to feed another tool, use the vault CLI rather than a raw HTTP call — it resolves the credential and its grant for you:

Terminal window
VPS_API_TOKEN="$(t1k vault get vps-management:agent-token)" ./scripts/vps.sh list

Read access is a per-name grant; t1k vault list shows the names granted to you. Exit 2 means the name is missing or not granted to your account, exit 3 an auth problem, exit 4 the vault is unavailable — ask a marketing team owner for the read grant instead of working around it. Never print, echo, log or commit the value, and never store it in a plain file: pass it through the environment as above, or use the skill scripts directly.

Every power action and every in-GUI click/type/key/upload needs the user’s consent, and choosing the right machine is judgment — those stay on a reasoning tier (routing SSOT: rules/orchestration-rules.md § “Task-Type → Agent Routing”). Only the read-only runs are cheap-tier:

StepAgent
Run scripts/vps.sh list and relay the table verbatimt1k-fact-fetcher — read-only, and the work is running the script and tabulating its output
Run scripts/vps-gui.mjs list or shot "<machine>" and report the result / PNG patht1k-fact-fetcher — shot writes only a local screenshot and changes nothing on the machine