aws-bootstrap-skill

aws-bootstrap-g4dn

---

One command to go from zero to a fully configured GPU dev box on AWS — with CUDA-matched PyTorch, Jupyter, SSH aliases, and a GPU benchmark ready to run.

aws-bootstrap launch          # Spot g4dn.xlarge in ~3 minutes
ssh aws-gpu1                  # You're in, venv activated, PyTorch works

✨ Key Features

	Feature	Details
🚀	One-command launch	Spot (default) or on-demand, with automatic fallback on capacity errors
🔑	Auto SSH config	Adds aws-gpu1 alias to ~/.ssh/config — no IP juggling. Cleaned up on terminate
🐍	CUDA-aware PyTorch	Detects the installed CUDA toolkit (nvcc) and installs PyTorch from the matching wheel index — no more torch.version.cuda mismatches
✅	PyTorch smoke test	Runs a quick torch.cuda matmul after setup to verify the GPU stack works end-to-end
📊	GPU benchmark included	CNN (MNIST) + Transformer benchmarks with FP16/FP32/BF16 precision and tqdm progress
📓	Jupyter ready	Lab server auto-starts as a systemd service on port 8888 — just SSH tunnel and open
🖥️	status --gpu	Shows CUDA toolkit version, driver max, GPU architecture, spot pricing, uptime, and estimated cost
💾	EBS data volumes	Attach persistent storage at /data — survives spot interruptions and termination, reattach to new instances
🗑️	Clean terminate	Stops instances, removes SSH aliases, cleans up EBS volumes (or preserves with --keep-ebs)
🤖	Agent Skill	Included Claude Code plugin lets LLM agents autonomously provision, manage, and tear down GPU instances

🎯 Target Workflows

1. Jupyter server-client — Jupyter runs on the instance, connect from your local browser
2. VSCode Remote SSH — opens ~/workspace with pre-configured CUDA debug/build tasks and an example .cu file
3. NVIDIA Nsight remote debugging — GPU debugging over SSH

---

Requirements

1. AWS profile configured with relevant permissions (profile name can be passed via --profile or read from AWS_PROFILE env var)
2. AWS CLI v2 — see here
3. Python 3.12+ and uv
4. An SSH key pair (see below)

Installation

From PyPI

pip install aws-bootstrap-g4dn

With uvx (no install needed)

uvx runs the CLI directly in a temporary environment — no global install required:

uvx --from aws-bootstrap-g4dn aws-bootstrap launch
uvx --from aws-bootstrap-g4dn aws-bootstrap status
uvx --from aws-bootstrap-g4dn aws-bootstrap terminate

From source (development)

git clone https://github.com/promptromp/aws-bootstrap-g4dn.git
cd aws-bootstrap-g4dn
uv venv
uv sync

All methods install the aws-bootstrap CLI.

SSH Key Setup

The CLI expects an Ed25519 SSH public key at ~/.ssh/id_ed25519.pub by default. If you don't have one, generate it:

ssh-keygen -t ed25519

Accept the default path (~/.ssh/id_ed25519) and optionally set a passphrase. The key pair will be imported into AWS automatically on first launch.

To use a different key, pass --key-path:

aws-bootstrap launch --key-path ~/.ssh/my_other_key.pub

Usage

🚀 Launching an Instance

# Show available commands
aws-bootstrap --help

# Dry run — validates AMI lookup, key import, and security group without launching
aws-bootstrap launch --dry-run

# Launch a spot g4dn.xlarge (default)
aws-bootstrap launch

# Launch on-demand in a specific region with a custom instance type
aws-bootstrap launch --on-demand --instance-type g5.xlarge --region us-east-1

# Launch without running the remote setup script
aws-bootstrap launch --no-setup

# Use a specific Python version in the remote venv
aws-bootstrap launch --python-version 3.13

# Use a non-default SSH port
aws-bootstrap launch --ssh-port 2222

# Attach a persistent EBS data volume (96 GB gp3, mounted at /data)
aws-bootstrap launch --ebs-storage 96

# Reattach an existing EBS volume from a previous instance
aws-bootstrap launch --ebs-volume-id vol-0abc123def456

# Use a specific AWS profile
aws-bootstrap launch --profile my-aws-profile