diegosouzapw Basilica CLI Helper
Rent GPUs and run ML training jobs on Basilica's decentralized compute platform.
This skill helps access high-performance GPUs through Basilica's CLI. Use this when needing to:
- Rent GPUs for machine learning training
- Run distributed training jobs
- Manage compute resources and costs
- Execute code on remote GPU instances
Claude Code TTY Limitation
IMPORTANT: The basilica up command requires interactive TTY selection, which fails in Claude Code's non-terminal environment.
Workaround: Use the bundled script
# List available GPUs (non-interactive)
python ~/.claude/skills/basilica-cli-helper/scripts/basilica_up.py list
# Filter by GPU type and cloud
python ~/.claude/skills/basilica-cli-helper/scripts/basilica_up.py list --gpu-type h100 --compute secure-cloud
# Rent by selection number (from list output)
python ~/.claude/skills/basilica-cli-helper/scripts/basilica_up.py rent --select 1
# Rent by offering ID directly
python ~/.claude/skills/basilica-cli-helper/scripts/basilica_up.py rent hyperstack-165
This script uses the Basilica REST API directly, bypassing the interactive selection.
Quick Reference
Essential Commands
| Command | Description |
|---|---|
basilica login |
Authenticate with Basilica |
basilica ls |
List available GPUs with pricing |
basilica ps |
List your active rentals |
basilica status <uid> |
Check rental status |
basilica exec "cmd" --target <uid> |
Execute command on rental |
basilica ssh <uid> |
SSH into instance |
basilica cp <src> <dst> |
Copy files to/from instance |
basilica down <uid> |
Terminate rental |
basilica balance |
Check account balance |
Cloud Types
Basilica offers two compute sources:
| Cloud | Flag | Description |
|---|---|---|
| Secure Cloud | --compute secure-cloud |
Datacenter GPUs (Hyperstack, DataCrunch, Lambda) |
| Community Cloud | --compute community-cloud |
Decentralized miner GPUs (Bittensor network) |
Command Reference
Authentication
# Standard login (opens browser)
basilica login
# Device code flow (for WSL, SSH, containers)
basilica login --device-code
# Logout
basilica logout
# Check balance
basilica balance
Listing GPUs
# List all available GPUs
basilica ls
# Filter by GPU type
basilica ls h100
basilica ls a100
# Filter by cloud type
basilica ls --compute secure-cloud
basilica ls --compute community-cloud
# Additional filters
basilica ls --gpu-min 2 --gpu-max 8
basilica ls --price-max 5.00
basilica ls --memory-min 80
basilica ls --country US
# JSON output
basilica ls --json
Starting Rentals
Note: basilica up requires interactive TTY. In Claude Code, use the workaround script above.
In a terminal:
# Interactive GPU selection
basilica up
# Filter to GPU type (still requires selection)
basilica up h100
basilica up a100
# Specify cloud type
basilica up --compute secure-cloud
basilica up --compute community-cloud
# Detached mode (don't auto-connect)
basilica up -d
# Additional options
basilica up --gpu-count 4
basilica up --country US
basilica up --no-ssh # Faster startup without SSH
Managing Rentals
# List active rentals
basilica ps
# Show rental history
basilica ps --history
# Filter by cloud type
basilica ps --compute secure-cloud
# Check specific rental
basilica status <rental-id>
# Terminate rental
basilica down <rental-id>
# Terminate all rentals
basilica down --all
# Restart container
basilica restart <rental-id>
Executing Code
# Execute command on rental
basilica exec "python train.py" --target <rental-id>
# If only one active rental, --target is optional
basilica exec "nvidia-smi"
basilica exec "pip install -r requirements.txt"
File Transfer
# Copy file to rental
basilica cp train.py <rental-id>:/workspace/
# Copy directory to rental
basilica cp ./project/ <rental-id>:/workspace/project/
# Download file from rental
basilica cp <rental-id>:/workspace/model.pth ./
# Download directory
basilica cp <rental-id>:/workspace/checkpoints/ ./checkpoints/
SSH Access
# SSH into instance
basilica ssh <rental-id>
# Port forwarding (e.g., Jupyter)
basilica ssh <rental-id> -L 8888:localhost:8888
# Remote port forwarding
basilica ssh <rental-id> -R 9999:localhost:9999
Logs
# View logs
basilica logs <rental-id>
# Follow logs in real-time
basilica logs <rental-id> --follow
# Tail last N lines
basilica logs <rental-id> --tail 100
SSH Key Management
# Add SSH key
basilica ssh-keys add
# Add with specific file
basilica ssh-keys add --file ~/.ssh/id_rsa.pub
# List registered keys
basilica ssh-keys list
# Delete key
basilica ssh-keys delete
API Token Management
# Create API token
basilica tokens create <name>
# List tokens
basilica tokens list
# Revoke token
basilica tokens revoke <name>
Funding
# Show deposit address
basilica fund
# List deposit history
basilica fund list --limit 100
Common Workflows
PyTorch Training (Claude Code)
# 1. List available GPUs using workaround script
python ~/.claude/skills/basilica-cli-helper/scripts/basilica_up.py list --compute secure-cloud
# 2. Rent GPU by selection number
python ~/.claude/skills/basilica-cli-helper/scripts/basilica_up.py rent --select 1
# Note the rental ID from output
# 3. Copy training files
basilica cp train.py <rental-id>:/workspace/
basilica cp requirements.txt <rental-id>:/workspace/
# 4. Install dependencies and run training
basilica exec "pip install -r /workspace/requirements.txt" --target <rental-id>
basilica exec "python /workspace/train.py --epochs 10" --target <rental-id>
# 5. Download results
basilica cp <rental-id>:/workspace/model.pth ./
# 6. Terminate when done
basilica down <rental-id>
PyTorch Training (Terminal with TTY)
# 1. Start GPU rental (interactive selection)
basilica up h100 --compute secure-cloud -d
# Note the rental ID
# 2. Copy training files
basilica cp train.py <rental-id>:/workspace/
# 3. Run training
basilica exec "python /workspace/train.py" --target <rental-id>
# 4. Download results and cleanup
basilica cp <rental-id>:/workspace/model.pth ./
basilica down <rental-id>
Jupyter Notebook
# 1. Start rental and SSH with port forward
basilica up h100 -d
basilica ssh <rental-id> -L 8888:localhost:8888
# 2. In SSH session, start Jupyter
jupyter lab --ip=0.0.0.0 --port=8888 --no-browser
# 3. Open http://localhost:8888 in browser
Check Costs
# Check current balance
basilica balance
# View rental history with costs
basilica ps --history
# Get deposit address if needed
basilica fund
Troubleshooting
"Selection failed: not a terminal"
This occurs when running basilica up in Claude Code. Use the workaround script:
python ~/.claude/skills/basilica-cli-helper/scripts/basilica_up.py list
python ~/.claude/skills/basilica-cli-helper/scripts/basilica_up.py rent --select <number>
"Not logged in"
basilica login
# Or for non-browser environments:
basilica login --device-code
"Insufficient balance"
basilica balance # Check current balance
basilica fund # Get deposit address
"No GPUs available"
basilica ls # Check different GPU types
basilica ls --compute community-cloud # Try community cloud
"SSH key not registered"
basilica ssh-keys add
"Connection timeout"
basilica status <rental-id> # Check if still running
basilica logs <rental-id> # Check for errors
GPU Selection Guide
| Use Case | Recommended GPU | Typical Price |
|---|---|---|
| Small models, fine-tuning | A100 (1x) | $1-2/hr |
| Medium models | H100 (1x) | $2-3/hr |
| Large models | 4-8x A100/H100 | $5-20/hr |
| Inference testing | Any 1x GPU | $1-3/hr |
Resources
- Basilica Homepage: https://basilica.ai
- CLI Help:
basilica help <command> - Version: Check with
basilica --version
Scripts Reference
basilica_up.py
Non-interactive GPU rental script for Claude Code and other non-TTY environments.
# Show help
python ~/.claude/skills/basilica-cli-helper/scripts/basilica_up.py --help
# List offerings
python ~/.claude/skills/basilica-cli-helper/scripts/basilica_up.py list [--gpu-type TYPE] [--compute CLOUD]
# Rent by selection
python ~/.claude/skills/basilica-cli-helper/scripts/basilica_up.py rent --select NUMBER
# Rent by offering ID
python ~/.claude/skills/basilica-cli-helper/scripts/basilica_up.py rent OFFERING_ID
The script caches offering data to /tmp/basilica_offerings.json for the --select option.