GPUtw Docs

AI assistant

Let Claude Code, Codex CLI, Gemini CLI, Cursor, Copilot or any MCP client drive the GPUtw API for you.

Open dashboard API keys

Updating to the latest version

The current release is Skill v1.1.1 with MCP server 1.1.0 (the two are versioned separately; release notes). How you update depends on how you installed it:

  • Plugin: you ran /plugin install gputw@gputw in Claude Code. Most people.
  • npm: you added the MCP server with npx -y @gputw/mcp-server.
  • Clone: you ran git clone (Codex, Gemini, Cursor, Copilot, or a manual Claude Code install).

Plugin, inside Claude Code:

  1. Refresh the plugin list: /plugin marketplace update gputw
  2. Open /plugin → Installed → gputw → Update now.
  3. Load the new version: /reload-plugins (or start a new session).
Example
/plugin marketplace update gputw
# then /plugin → Installed → gputw → Update now
/reload-plugins

# or from a shell, in one step:
claude plugin update gputw@gputw
Tip

Step 1 alone only refreshes the list; it does not update the installed plugin. To stop doing this by hand, turn on auto-update once: /plugin → Marketplaces → gputw → Enable auto-update. It is off by default.

npm (MCP server): restart your MCP client and it fetches the latest version. To control exactly which version runs, pin it and raise the number when you update:

Example
claude mcp add gputw -s user -e GPUTW_API_KEY=gputw_live_xxx -- npx -y @gputw/[email protected]

Clone: pull the folder you cloned into, then restart the client.

Example
git -C ~/.gputw-skill pull            # or the folder you used, e.g. ~/.claude/skills/gputw, .gputw-skill

Check that it worked. claude plugin list shows the plugin version; a clone has it as metadata.version in SKILL.md; in Claude Code, /mcp shows the MCP server version. The plugin and skill should read 1.1.1, the MCP server 1.1.0. Full details are in the repository README's update section.

What it is

GPUtw publishes an open knowledge package, the GPUtw Skill, that teaches an AI coding assistant this API — the endpoints, the auth header, which scope each call needs, how to poll a deploy until it is running, and how to clean up afterwards. It ships for Claude Code, OpenAI Codex CLI, Google Gemini CLI, Cursor and GitHub Copilot, plus an official MCP server with 18 typed tools for any client that speaks MCP. Install it once and you can ask for a machine in plain language instead of writing the calls yourself.

github.com/GPUtw-ai/GPUtw-Skill — MIT licensed, pure Markdown plus a stdlib Python client; nothing in it sends your key anywhere.

Claude Code

Recommended: the plugin, which installs the skill, the slash commands and the MCP tools together and stores your API key in Claude Code's secure storage.

Example
/plugin marketplace add GPUtw-ai/GPUtw-Skill
/plugin install gputw@gputw

Manual alternative (skill only, no MCP tools):

Example
git clone https://github.com/GPUtw-ai/GPUtw-Skill.git ~/.claude/skills/gputw

Optional slash commands — /gputw-deploy, /gputw-monitor, /gputw-vault, /gputw-debug — are included by the plugin; with the manual install copy them from commands/ into ~/.claude/commands/.

Warning
Pick one install method. The plugin and the manual ~/.claude/skills/gputw copy share a name, and Claude Code silently prefers the plugin.

MCP server

The same repository ships @gputw/mcp-server: 18 structured tools covering the catalog (list-gpus, list-available-nodes, list-templates), the instance lifecycle (create-instance, stop-instance, delete-instance, restart-instance), live state (status, resources, logs, events) and the vault (list, stats, upload, Hugging Face / URL downloads). Tools are tagged read / write / destructive and API errors come back as actionable messages.

Example
claude mcp add gputw -s user -e GPUTW_API_KEY=gputw_live_xxx -- npx -y @gputw/mcp-server@latest

Prefer not to use npm? The server also ships prebuilt in the repository; run it from a clone instead:

Example
git clone https://github.com/GPUtw-ai/GPUtw-Skill.git ~/.gputw-skill
claude mcp add gputw -s user -e GPUTW_API_KEY=gputw_live_xxx -- node ~/.gputw-skill/mcp/dist/stdio.mjs

Claude Desktop, Cursor, VS Code, Windsurf and other MCP clients use the same stdio server:

Example
{
  "mcpServers": {
    "gputw": {
      "command": "npx",
      "args": ["-y", "@gputw/mcp-server@latest"],
      "env": { "GPUTW_API_KEY": "gputw_live_xxx" }
    }
  }
}

From a clone, use "command": "node" with "args": ["/absolute/path/GPUtw-Skill/mcp/dist/stdio.mjs"].

  • GPUTW_API_KEY: required for everything except the public catalog. Use the smallest preset that fits.
  • GPUTW_API_BASE: defaults to https://api.gputw.ai/api. Keep it on https — an http base redirects, and clients drop the key on the redirect.
  • GPUTW_MCP_ALLOW_EXEC: the root shell tool exec-in-instance is not registered unless this is set to 1.

Check the connection before relying on the tools: in Claude Code run /mcp and make sure gputw shows Connected. If the tools never appear, the server is not connected — reinstall, or fall back to the skill's curl / Python guides.

Info
The MCP server is stable as of 1.1.0, released together with the skill.

OpenAI Codex CLI

Clone the repository into the project (or globally) and point the project's AGENTS.md at it. Codex also honours its native skills directory, where the skill can be invoked explicitly as $gputw.

Example
npm install -g @openai/codex

# project-level (recommended)
git clone https://github.com/GPUtw-ai/GPUtw-Skill.git .gputw-skill
# or as a native Codex skill, callable as $gputw
git clone https://github.com/GPUtw-ai/GPUtw-Skill.git .agents/skills/gputw
# or globally
git clone https://github.com/GPUtw-ai/GPUtw-Skill.git ~/.codex/gputw-skill

Add to the project's AGENTS.md:

Example
## GPUtw Skill
For anything involving GPUtw / gputw.ai / /vault / gputw_live_ keys, read .gputw-skill/AGENTS.md (entry)
and .gputw-skill/SKILL.md (full knowledge base). Guides live in .gputw-skill/guides/, the endpoint list in
.gputw-skill/references/endpoints.md, official doc URLs in .gputw-skill/references/docs-site.md.

Verify: codex "What is the prefix of a GPUtw API key?" should answer gputw_live_.

Google Gemini CLI

Example
npm install -g @google/gemini-cli
git clone https://github.com/GPUtw-ai/GPUtw-Skill.git .gputw-skill   # or ~/.gemini/gputw-skill

Add to the project's GEMINI.md:

Example
## GPUtw Skill
For GPUtw-related requests, read .gputw-skill/GEMINI.md (entry) and .gputw-skill/SKILL.md.

Verify with gemini "What is the prefix of a GPUtw API key?" → gputw_live_.

Cursor and GitHub Copilot

Cursor: clone the repository to .gputw-skill and add the same block as for Codex to the project's AGENTS.md or Cursor Rules. Cursor reads .gputw-skill/SKILL.md on its own; use @web when it needs an official doc page. Cursor can also attach the MCP server with the JSON above.

GitHub Copilot (VS Code Copilot Chat, Copilot CLI, Visual Studio): clone to .gputw-skill and create .github/copilot-instructions.md telling Copilot to read .gputw-skill/SKILL.md first, follow its decision tree into guides/, cite only endpoints listed in references/endpoints.md, and base runnable examples on scripts/gputw_client.py. The repository's SETUP.md has the full file to paste.

Claude.ai and the Claude API: zip the folder and upload it under Settings → Features → Skills; the SKILL.md frontmatter already uses only the fields the spec allows.

Any other agent that understands the Agent Skills format (SKILL.md + references/ + scripts/) works by dropping the folder into its skills directory.

What it knows

  • Authentication: gputw_live_ keys, the 17 scopes and 5 presets (including the write-only Upload token for CI), which header the key goes in, and what can only be done in the console.
  • GPU inventory: reading the catalog, finding a node with free capacity, sold-out and queueing.
  • Instances: create (template, custom image, registry auth, env, args), the status machine, stop / delete / restart / reconfigure, SSH, OOM and data recovery — including the waits that are easy to get wrong.
  • Live state: status polling, resources and telemetry source, events, previous-container logs, exec, pod restart.
  • Networking: private / public / unlisted HTTP ports, raw TCP/UDP exposure, Web UI handoff URLs, port fees.
  • Vault: listing, single and resumable chunked uploads through upload.gputw.ai, server-side URL and Hugging Face downloads, ComfyUI model folders.
  • Billing, teams, debugging: the one-hour balance rule and 402, team limits, notifications, tickets, and status code → cause → action for 401 / 403 / 409 / 429 and Cloudflare 403.

Verify it loaded

Ask the assistant: "What is the prefix of a GPUtw API key?" — the answer gputw_live_ means the skill is active. Then try a real task:

Example
Using Python, start an RTX 4090 on GPUtw with the PyTorch template, wait until it is RUNNING,
print the SSH command, and make sure it is stopped at the end.

A loaded assistant will check /gpus/active and /nodes/available first, pick the template from /templates, poll /status, call /instances/stop in a finally, and list the scopes it needs.

Keys and base URL

Create a key under Dashboard → API Keys with the smallest preset that fits, and give it to the assistant only through the environment variable GPUTW_API_KEY. The skill's rules forbid putting the key in a query string, in code, or in logs, and reserve instances:exec for a dedicated key.

The API base is https://api.gputw.ai/api (https only) with the key in Authorization: Bearer gputw_live_… and a User-Agent on every request. Endpoints you can try without a key: /gpus/active, /templates, /config/time.

Check what it writes

The skill is a separate repository on its own release cycle, so it can lag a change to this API. Treat generated code as a draft: read the call it produced against these docs before running it against a live account, and keep an eye on anything that stops or deletes an instance. To pin a version: cd ~/.claude/skills/gputw && git tag -l && git checkout v1.0.0. Report problems through GitHub Issues — never paste an API key into an issue.