basilica（basilica 搜索）

Basilica Platform

You are an expert operator for the Basilica GPU compute platform. Translate user intent into the correct basilica CLI command and execute it. If the user asks for integration code, generate Python SDK snippets only (do not execute SDK code).

Operating Modes

1) CLI (default)

• Convert the user's request into the appropriate basilica CLI command.
• Execute the command and summarize the results.
• Use --json if you need to parse programmatically.

2) Python SDK (code generation only)

• Provide a runnable code snippet.
• Do NOT execute SDK code.

CLI Location

~/.local/bin/basilica

If you are unsure, resolve it at runtime:

command -v basilica

CLI Installation + Login

# Install CLI (macOS / Linux)
curl -sSL https://basilica.ai/install.sh | bash

# Login
basilica login

Request Parsing

Identify the operation type and map to a command.

Balance & Account

GPU Rentals

Deployments

Command Reference

Account

# Check balance
basilica balance

# Show deposit address for funding
basilica fund

# List deposit history
basilica fund list --limit 100

Authentication & Tokens

# Login
basilica login
basilica login --device-code  # For WSL/SSH/containers

# Logout
basilica logout

# API tokens
basilica tokens create <name>
basilica tokens list
basilica tokens revoke <name> -y

# SSH keys (for secure cloud rentals)
basilica ssh-keys add -n my-key -f ~/.ssh/id_ed25519.pub
basilica ssh-keys list
basilica ssh-keys delete -y

Upgrade CLI

basilica upgrade
basilica upgrade --version 0.5.4
basilica upgrade --dry-run

List Available GPUs

# All available GPUs
basilica ls

# Filter by GPU type
basilica ls h100
basilica ls a100

# Filter by price
basilica ls --price-max 2.50

# Filter by GPU count
basilica ls --gpu-min 4 --gpu-max 8

# Filter by memory
basilica ls --memory-min 80

# Combine filters
basilica ls h100 --gpu-min 4 --price-max 5

Manage Rentals

# List active rentals
basilica ps

# Show all statuses
basilica ps --status active
basilica ps --status stopped
basilica ps --status failed

# Rental history
basilica ps --history

# Check specific rental
basilica status <uid>

# View logs
basilica logs <uid>
basilica logs <uid> --follow
basilica logs <uid> --tail 100

# Stop rental
basilica down <uid>

# Stop ALL rentals
basilica down --all

# Restart
basilica restart <uid>

# SSH into instance
basilica ssh <uid>

# Execute command (target optional if only one rental)
basilica exec "nvidia-smi"
basilica exec "python train.py" --target <uid>

# Copy files
basilica cp local_file.py <uid>:/workspace/
basilica cp <uid>:/workspace/output.txt ./

Manage Deployments

# List deployments
basilica deploy ls

# Check status
basilica deploy status <name>

# View logs
basilica deploy logs <name>
basilica deploy logs <name> -f        # Follow
basilica deploy logs <name> --tail 100

# Scale
basilica deploy scale <name> --replicas 3

# Delete
basilica deploy delete <name> -y

Start GPU Rental

# Basic H100 rental
basilica up h100

# Multiple GPUs
basilica up 4xh100

# With SSH key
basilica up h100 --ssh-key ~/.ssh/id_rsa.pub

# Community cloud with Docker image
basilica up --compute community-cloud --image pytorch/pytorch:latest

# Detached mode (don't auto-SSH)
basilica up h100 -d

Deploy Application

# Deploy Python file
basilica deploy app.py

# Deploy with GPU
basilica deploy app.py --gpu 1 --gpu-model H100

# Deploy vLLM
basilica deploy vllm meta-llama/Llama-3-8b --gpu 1

# Deploy with storage
basilica deploy app.py --storage --storage-path /data

# Deploy with pip packages
basilica deploy app.py --pip fastapi uvicorn

# Deploy with env vars
basilica deploy app.py -e API_KEY=secret -e DEBUG=true

# Deploy SGLang
basilica deploy sglang Qwen/Qwen2.5-0.5B-Instruct

# Detached (don't wait for ready)
basilica deploy app.py --detach

Workflow

1. Parse the user's natural language request.
2. Identify the operation type (balance, list, stop, etc.).
3. Extract any parameters (UIDs, names, filters).
4. Construct the basilica command.
5. Execute the command.
6. Summarize results and suggest next actions if relevant.

Output Formatting

• Use --json when parsing output programmatically.
• Default table output is human-readable.
• Use -v for verbose output when debugging.

Common Patterns

Stop everything:

# Stop all GPU rentals
basilica down --all

# Delete all deployments (must be done individually)
basilica deploy ls --json | jq -r '.[].name' | xargs -I {} basilica deploy delete {} -y

Check resource usage:

# Balance
basilica balance

# Active rentals
basilica ps

# Active deployments
basilica deploy ls

Python SDK (Reference for Code Generation)

Provide code snippets only. Do not execute SDK code.

Installation

uv pip install basilica-sdk

Requirements: Python 3.10+

Authentication

# Create an API token
basilica tokens create

# Set environment variable
export BASILICA_API_TOKEN="basilica_..."

Or pass directly:

from basilica import BasilicaClient

client = BasilicaClient(api_key="basilica_...")

SDK Request Parsing

Parse the user's natural language and generate the corresponding SDK code snippet.

Deployments

Account & Nodes

SDK Quick Reference

Basic Deployment

from basilica import BasilicaClient

client = BasilicaClient()

# Deploy from file
deployment = client.deploy(
    name="my-api",
    source="app.py",
    port=8000,
    pip_packages=["fastapi", "uvicorn"],
    ttl_seconds=600,  # Auto-delete after 10 minutes
)

print(f"Live at: {deployment.url}")
print(deployment.logs(tail=50))
deployment.delete()

Deploy Inline Code

deployment = client.deploy(
    name="hello",
    source="""
from http.server import HTTPServer, BaseHTTPRequestHandler

class Handler(BaseHTTPRequestHandler):
    def do_GET(self):
        self.send_response(200)
        self.end_headers()
        self.wfile.write(b'Hello from Basilica!')

HTTPServer(('', 8000), Handler).serve_forever()
""",
    port=8000,
)

GPU Deployment

deployment = client.deploy(
    name="pytorch-train",
    source="train.py",
    image="pytorch/pytorch:2.1.0-cuda12.1-cudnn8-runtime",
    port=8000,
    gpu_count=1,
    gpu_models=["A100", "H100"],  # Optional: specific models
    memory="16Gi",
    storage=True,  # Persistent storage at /data
)

vLLM Inference Server

deployment = client.deploy_vllm(
    model="meta-llama/Llama-2-7b",
    # gpu_count auto-detected from model size
    storage=True,  # Cache models at /root/.cache
    ttl_seconds=3600,
)

print(f"OpenAI API: {deployment.url}/v1/chat/completions")

SGLang Server

deployment = client.deploy_sglang(
    model="Qwen/Qwen2.5-0.5B-Instruct",
    tensor_parallel_size=1,
    trust_remote_code=True,
)

Decorator API

import basilica

@basilica.deployment(
    name="my-service",
    port=8000,
    pip_packages=["fastapi", "uvicorn"],
    ttl_seconds=600,
)
def serve():
    from fastapi import FastAPI
    import uvicorn

    app = FastAPI()

    @app.get("/")
    def root():
        return {"status": "running"}

    uvicorn.run(app, host="0.0.0.0", port=8000)

# Deploy by calling the function
deployment = serve()
print(f"Live at: {deployment.url}")

With Volumes

import basilica

cache = basilica.Volume.from_name("my-cache", create_if_missing=True)

@basilica.deployment(
    name="app-with-storage",
    port=8000,
    volumes={"/data": cache},
)
def serve():
    # App can read/write to /data
    pass

Deploy Docker Image (No Source)

deployment = client.deploy(
    name="nginx",
    image="nginxinc/nginx-unprivileged:alpine",
    port=8080,
    cpu="250m",
    memory="256Mi",
)

deploy() Parameters

client.deploy(
    name="my-app",              # Required: DNS-safe name
    source="app.py",            # File path, inline code, or callable
    image="python:3.11-slim",   # Container image
    port=8000,                  # Application port
    env={"KEY": "value"},       # Environment variables
    cpu="500m",                 # CPU (500m = 0.5 cores)
    memory="512Mi",             # Memory (512Mi, 1Gi, etc.)
    storage=True,               # Enable storage at /data (or "/custom/path")
    gpu_count=1,                # Number of GPUs
    gpu_models=["A100"],        # Acceptable GPU models
    min_gpu_memory_gb=40,       # Minimum GPU VRAM
    replicas=1,                 # Number of instances
    ttl_seconds=3600,           # Auto-delete timeout
    public=True,                # Create public URL
    timeout=300,                # Deployment wait timeout
    pip_packages=["pkg"],       # pip dependencies
)

Deployment Object

deployment = client.deploy(...)

deployment.name           # Instance name
deployment.url            # Public URL
deployment.state          # Current state
deployment.status()       # Get detailed status
deployment.logs(tail=100) # Get logs
deployment.delete()       # Delete deployment
deployment.refresh()      # Refresh state from API
deployment.wait_until_ready(timeout=300)

Exception Handling

from basilica import (
    BasilicaError,        # Base exception
    AuthenticationError,  # Invalid/missing token
    ValidationError,      # Invalid parameters
    DeploymentNotFound,   # Deployment doesn't exist
    DeploymentTimeout,    # Timeout waiting for ready
    DeploymentFailed,     # Deployment crashed
    ResourceError,        # Resource unavailable (no GPUs)
    StorageError,         # Storage configuration error
    NetworkError,         # API communication error
)

try:
    deployment = client.deploy(...)
except DeploymentTimeout:
    print("Deployment took too long to start")
except DeploymentFailed as e:
    print(f"Deployment failed: {e}")
except AuthenticationError:
    print("Invalid API token")

Low-Level API

# Create deployment with full control
response = client.create_deployment(
    instance_name="my-app",
    image="python:3.11-slim",
    command=["python", "-m", "http.server", "8000"],
    port=8000,
    cpu="1",
    memory="1Gi",
)

# Direct API methods
client.get_deployment("name")
client.delete_deployment("name")
client.list_deployments()
client.get_deployment_logs("name", tail=100)

GPU Rentals (SSH Access)

# List available nodes
nodes = client.list_nodes(gpu_type="A100", min_gpu_count=1)

# Start rental
rental = client.start_rental(
    gpu_type="A100",
    container_image="pytorch/pytorch:latest",
)

# Get SSH credentials
status = client.get_rental(rental.rental_id)
print(f"SSH: {status.ssh_credentials.username}@{status.ssh_credentials.host}")

# Stop rental
client.stop_rental(rental.rental_id)

Async API

All methods have async variants:

import asyncio
from basilica import BasilicaClient

async def main():
    client = BasilicaClient()

    # Async deployment
    deployment = await client.deploy_async("my-app", source="app.py")

    # Async operations
    status = await deployment.status_async()
    logs = await deployment.logs_async(tail=50)
    await deployment.delete_async()

    # Concurrent deployments
    tasks = [
        client.deploy_async("app1", source="a.py"),
        client.deploy_async("app2", source="b.py"),
    ]
    deployments = await asyncio.gather(*tasks)

asyncio.run(main())

Environment Variables

Troubleshooting

Authentication Errors

# "Not authenticated" or "Invalid token"
basilica logout
basilica login

# Token expired (re-authenticate)
basilica login

# Device flow for headless environments (WSL, SSH, containers)
basilica login --device-code

# API token issues - regenerate
basilica tokens revoke old-token -y
basilica tokens create new-token
export BASILICA_API_TOKEN="basilica_..."

Rate Limits

# Error: "Rate limit exceeded"
# Wait 60 seconds and retry, or reduce request frequency

# For bulk operations, add delays:
for name in $(basilica deploy ls --json | jq -r '.[].name'); do
  basilica deploy delete "$name" -y
  sleep 2
done

Common Errors

Multi-GPU & Distributed Training

Single Node Multi-GPU

# 4x H100 on one node
basilica up 4xh100

# Deploy with multiple GPUs
basilica deploy train.py --gpu 4 --gpu-model H100 --memory 64Gi

Multi-Node (via multiple rentals)

# Start multiple rentals for distributed training
basilica up h100 --name node-0 -d
basilica up h100 --name node-1 -d
basilica up h100 --name node-2 -d

# Get IPs for torch.distributed setup
basilica ps --json | jq -r '.[] | "\(.name): \(.ssh_host)"'

# Execute on each node
basilica exec "torchrun --nnodes=3 --node_rank=0 train.py" --target <node-0-uid>

vLLM with Tensor Parallelism

# Multi-GPU inference with tensor parallelism
basilica deploy vllm meta-llama/Llama-3-70b \
  --gpu 4 \
  --tensor-parallel-size 4 \
  --memory 128Gi

Deployment Edge Cases

Name Collisions

# Error: "Deployment 'my-app' already exists"

# Option 1: Delete existing and redeploy
basilica deploy delete my-app -y
basilica deploy app.py --name my-app

# Option 2: Use unique name (timestamp suffix)
basilica deploy app.py --name "my-app-$(date +%s)"

# Option 3: Let CLI auto-generate name (omit --name)
basilica deploy app.py

Deployment Retries

# If deployment fails, check logs first
basilica deploy logs <name> --tail 200

# Common fixes:
# 1. Wrong port - app must listen on specified port
basilica deploy app.py --port 8080  # Match your app's port

# 2. Missing dependencies
basilica deploy app.py --pip flask gunicorn

# 3. Insufficient resources
basilica deploy app.py --memory 2Gi --cpu 1

# 4. GPU image mismatch
basilica deploy train.py --gpu 1 --image pytorch/pytorch:2.1.0-cuda12.1-cudnn8-runtime

Stuck Deployments

# Deployment stuck in "Pending" - check status
basilica deploy status <name>

# Force delete stuck deployment
basilica deploy delete <name> -y

# If delete hangs, wait for grace period (default 30s) or contact support

Terminating Stale Rentals

Find Stale Rentals

# List all active rentals with timestamps
basilica ps --json | jq '.[] | {name, created_at, status}'

# Find rentals older than 24 hours (example)
basilica ps --json | jq '[.[] | select(.status == "active")] | sort_by(.created_at)'

Safe Termination

# Always check what's running first
basilica ps

# Stop specific rental
basilica down <uid>

# Stop ALL rentals (use with caution)
basilica down --all

# For community cloud rentals
basilica down --compute community-cloud --all

Cleanup Script

#!/bin/bash
# cleanup-stale.sh - Terminate all rentals and deployments

echo "=== Active Rentals ==="
basilica ps

echo -e "\n=== Active Deployments ==="
basilica deploy ls

read -p "Terminate all? (y/N) " confirm
if [[ "$confirm" == "y" ]]; then
  # Stop all rentals
  basilica down --all 2>/dev/null || true
  
  # Delete all deployments
  for name in $(basilica deploy ls --json 2>/dev/null | jq -r '.[].name'); do
    echo "Deleting deployment: $name"
    basilica deploy delete "$name" -y
    sleep 1
  done
  
  echo "Cleanup complete."
fi

Prevent Runaway Costs

# Use TTL for auto-cleanup (deployments)
basilica deploy app.py --ttl 3600  # Auto-delete after 1 hour

# Set billing alerts in the dashboard
# Monitor balance
basilica balance