Vastkit

Rent a temporary Vast.ai GPU from Codex or Claude, run a project, retrieve the results, and stop billing.

Vastkit is an installable agent plugin with a bundled, zero-dependency Python runtime. Agent users do not need pip, Node.js, npm, or npx.

What It Does

  • Searches verified Vast.ai offers and ranks them by estimated session cost.
  • Enforces GPU, VRAM, disk, reliability, bandwidth, and hourly price limits.
  • Asks before starting billing or performing destructive cleanup.
  • Waits for SSH, uploads the project, and runs foreground or detached jobs.
  • Retrieves and verifies outputs before destroying the instance.
  • Reports active instances and accrued cost so no rental is forgotten.

Requirements

  • A Vast.ai API key
  • Python 3.9+, ssh, and tar
  • Codex CLI 0.146+ or Claude Code with plugin support
  • An SSH key pair in ~/.ssh, or VASTKIT_SSH_KEY pointing to one

1. Configure Credentials

Vastkit reads the API key from VAST_API_KEY or from a file containing only the key:

~/.vast_api_key

Protect a key file after creating it:

chmod 600 ~/.vast_api_key

For a project-local .env:

VAST_API_KEY=your_key_here

Load it before starting the agent:

set -a
source .env
set +a

Never paste an API key into an agent prompt, command argument, issue, or commit. Vastkit excludes .env files from project uploads by default.

2. Install the Plugin

Both installation methods below download the GitHub repository into the agent's plugin cache. They do not use the current local checkout and do not install a global vastkit command.

Codex

Run in a terminal:

codex plugin marketplace add RazinAleksandr/vastkit
codex plugin add vastkit@vastkit

Start a new Codex conversation. Run /skills and confirm that vastkit appears.

Claude Code

Run in a terminal:

claude plugin marketplace add RazinAleksandr/vastkit
claude plugin install vastkit@vastkit

Restart Claude Code, or run /reload-plugins in the current session. The same installation can also be performed inside Claude Code:

/plugin marketplace add RazinAleksandr/vastkit
/plugin install vastkit@vastkit
/reload-plugins

3. Use the Skill

Use $vastkit in Codex and /vastkit:vastkit in Claude Code. The rest of the request can be normal language.

Safe First Test

Searches do not create an instance.

Codex:

$vastkit Find the three cheapest verified single GPUs with at least 24 GB
VRAM, a maximum price of $0.30/hour, and at least 95% reliability. Estimate a
two-hour session with 20 GB of downloads. Do not rent anything.

Claude Code:

/vastkit:vastkit Find the three cheapest verified single GPUs with at least
24 GB VRAM, a maximum price of $0.30/hour, and at least 95% reliability.
Estimate a two-hour session with 20 GB of downloads. Do not rent anything.

Run a Project End to End

$vastkit Inspect this repository and infer its GPU, CUDA, disk, and command
requirements. Find a verified Vast.ai GPU under $0.50/hour for at most two
hours. Show the selected offer and estimated session cost, then ask before
renting. After approval, upload only required files, run `python train.py`,
retrieve `outputs/`, verify the results, and destroy the instance.

For Claude Code, replace $vastkit with /vastkit:vastkit.

The agent records the exact instance ID, monitors the job, retrieves outputs before cleanup, and verifies that the instance is gone. If cleanup fails, it reports the live instance and its current price instead of hiding the problem.

Real Example: LUA + FLUX.1-dev

The repository includes a complete examples/deploy_lua_flux.sh runbook. It finds a 48 GB-class GPU, uploads LUA, generates one 2K and one 4K image with FLUX.1-dev, downloads the results, and destroys the instance in a cleanup trap. The script clones LUA from GitHub into a temporary directory, so it does not depend on a personal checkout. It needs git and an HF_TOKEN with FLUX.1-dev access.

Example request:

$vastkit Find a 48 GB GPU under $1/hr, run LUA with FLUX.1-dev, generate 2K/4K
images, download the results, then shut down the instance.

For Claude Code, replace $vastkit with /vastkit:vastkit.

Inspect Existing Rentals

$vastkit List all my Vast.ai instances with status, hourly price, age, and
accrued cost. Do not modify anything.

Clean Up an Exact Instance

$vastkit Show the current state and accrued cost for instance 12345678, then
ask before destroying that exact instance.

Spending and Safety Rules

  • Read-only discovery does not require approval.
  • rent and start require approval with a hard maximum hourly price.
  • Destructive operations require an exact instance or explicitly selected data.
  • destroy --all is never used unless the user explicitly requests every matching instance.
  • Stopping releases the GPU but can leave storage billing active. Destroying is the operation that ends instance billing.
  • Expected outputs are pulled and checked before approved automatic cleanup.

The complete agent contract is in skills/vastkit/SKILL.md.

Update

Codex:

codex plugin marketplace upgrade vastkit
codex plugin add vastkit@vastkit

Claude Code:

claude plugin marketplace update vastkit
claude plugin update vastkit@vastkit

Start a new agent session after updating.

Optional CLI Development

The plugin already contains the CLI. Install it separately only when developing Vastkit itself, and run the command from the repository root containing pyproject.toml:

git clone https://github.com/RazinAleksandr/vastkit.git
cd vastkit
python3 -m pip install -e .
vastkit --help

Without installing:

python3 -m vastkit --help
python3 -m vastkit whoami
python3 -m vastkit search --vram 24 --max-price 0.30 --hours 2

License

MIT