t1k:marketing:store:vps-management
| Field | Value |
|---|---|
| Module | store |
| Version | 0.14.9 |
| Effort | medium |
| Tools | — |
How to invoke
Section titled “How to invoke”/t1k:marketing:store:vps-managementVPS management
Section titled “VPS management”Three surfaces, all on https://vps.the1studio.org (NetBird-only; run netbird up first):
- REST via
vps.sh(scripts/) — list + rename + describe + power. BearerAGENT_TOKEN. - 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. - 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.
One account per VPS
Section titled “One account per VPS”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.mdcovers 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.
One-time setup (per workstation)
Section titled “One-time setup (per workstation)”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.
./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 connectionA provider whose login expired shows an ERROR row; the others still list.
Power state
Section titled “Power state”./scripts/vps.sh power <provider> <id> <start|stop|reboot|pause|resume> --confirm- Ask the user first, naming the exact machine (label + id) and action.
--confirmis a friction gate, not authorization. - Take provider/id from
list. Never test against a live machine: on 2026-09-27 a “rejection test” paused the real Geliyun box. - Geliyun is an energy-saving SKU: it freezes when idle and wakes with
start; after waking, give it ~1 min before RDP. - Re-run
listafter the call and report the resulting powerState.
Headless desktop (vps-screen.mjs)
Section titled “Headless desktop (vps-screen.mjs)”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.
./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 viaGET /serversand addresses/servers/<provider>/<id>/screen.GET /serversreports the alias asdisplayNameand falls back to the providerlabelwhen 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/cmdare normalized. - Sessions are attributed to a human: identity auto-derives from the
ghCLI login (e.g.junchenttd→agent-junchenttdin the Discord usage thread).VPS_AGENT_USERoverrides; 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
PartyUswhile 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
shotwhat is focused before any typing or clicking anywhere. - No file upload here — use
vps-gui.mjswhen a build must be dropped into the session (it also covers interactive SSO use).
GUI operations (vps-gui.mjs)
Section titled “GUI operations (vps-gui.mjs)”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.
./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 --confirmRules:
shotis 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).- Machines may be in use RIGHT NOW. A new RDP connection can evict the
current user (or fail against a live session).
shotfirst — if a document/app is visibly open mid-work, confirm with the user before clicking around. - Workflow:
shot→ decide → act →shotagain 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’sdevicePixelRatiobefore 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). - If a machine has no RDP connection, say so and create one in the dashboard; never guess credentials.
- If the display never appears, the machine is probably off/frozen — check
scripts/vps.sh list, wake it, retry. - SSO expired (a
loginreminder is printed)? Run./scripts/vps-gui.mjs login— it needs a human to click through GitHub. - 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-
shotimmediately before every mutating command, and prefer one short flow per invocation over a long click chain.
Uploads need drive redirection (upload)
Section titled “Uploads need drive redirection (upload)”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 diskwhen the drop did become a transfer, and tells you to verify withls ~/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/GUACFSmount 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:
- Put the file in a Google Drive folder shared “anyone with link” (temporarily).
- Download it inside the remote Chrome from
https://drive.usercontent.google.com/download?id=<id>&export=download. - Set the folder back to Restricted in the same session. The sharing window is a real exposure — do not leave it open.
Google Play Console runbook
Section titled “Google Play Console runbook”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).
Out of scope
Section titled “Out of scope”No shell access to machines, no RDP passwords through this skill (they live only in Guacamole), no console links.
Agent token
Section titled “Agent token”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:
VPS_API_TOKEN="$(t1k vault get vps-management:agent-token)" ./scripts/vps.sh listRead 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.
Executed by
Section titled “Executed by”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:
| Step | Agent |
|---|---|
Run scripts/vps.sh list and relay the table verbatim | t1k-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 path | t1k-fact-fetcher — shot writes only a local screenshot and changes nothing on the machine |