Overview

Deploy applications and manage infrastructure from Python.

Installation

pip install basilica-sdk

Or with uv:

uv pip install basilica-sdk

Quick Start

import basilica

@basilica.deployment(name="hello-world", port=8000)
def serve():
    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 World!')

    HTTPServer(('', 8000), Handler).serve_forever()

deployment = serve()
print(f"Live at: {deployment.url}")

Client Initialization

The BasilicaClient is your entry point.

from basilica import BasilicaClient

# Auto-detect from BASILICA_API_TOKEN environment variable
client = BasilicaClient()

# Explicit configuration
client = BasilicaClient(
    base_url="https://api.basilica.ai",
    api_key="basilica_..."
)

API key sources (in order of preference):

api_key parameter passed to constructor
BASILICA_API_TOKEN environment variable
BASILICA_API_URL for custom endpoint (defaults to https://api.basilica.ai)

To obtain an API token, use the CLI:

basilica tokens create

Core Features

Deployment Methods

Method	Description
`client.deploy()`	Deploy any application with full control
`client.deploy_vllm()`	Deploy vLLM inference server
`client.deploy_sglang()`	Deploy SGLang inference server

Management Methods

Method	Description
`client.get(name)`	Get a deployment by name
`client.list()`	List all deployments

Deployment Object

Every deployment returns a Deployment object:

deployment = client.deploy(name="my-app", source="app.py")

# Properties
deployment.url        # Public URL
deployment.name       # Deployment name
deployment.state      # Current state
deployment.namespace  # Kubernetes namespace
deployment.user_id    # Owner user ID
deployment.created_at # Creation timestamp

# Methods
deployment.status()   # Get detailed status
deployment.logs()     # Get container logs
deployment.delete()   # Delete the deployment
deployment.refresh()  # Refresh cached state

Environment Variables

# Required for authentication
export BASILICA_API_TOKEN="basilica_..."

# Optional custom endpoint
export BASILICA_API_URL="https://api.basilica.ai"

Error Handling

The SDK provides detailed error information.

from basilica import (
    BasilicaError,
    DeploymentTimeout,
    DeploymentFailed,
    DeploymentNotFound,
    ValidationError,
)

try:
    deployment = client.deploy("my-app", source="app.py")
except DeploymentTimeout as e:
    print(f"Deployment timed out after {e.timeout_seconds}s")
    print(f"Last state: {e.last_state}")
except DeploymentFailed as e:
    print(f"Deployment failed: {e.reason}")
except DeploymentNotFound as e:
    print(f"Deployment {e.instance_name} not found")
except ValidationError as e:
    print(f"Invalid parameter {e.field}: {e.value}")
except BasilicaError as e:
    print(f"Error: {e.message}")
    print(f"Retryable: {e.retryable}")

Exception hierarchy:

BasilicaError (base)
├── AuthenticationError
├── AuthorizationError
├── ValidationError
├── DeploymentError
│   ├── DeploymentNotFound
│   ├── DeploymentTimeout
│   └── DeploymentFailed
├── ResourceError
├── StorageError
├── NetworkError
├── RateLimitError
└── SourceError

Next Steps

Deployments: Deploy applications
Storage: Persist data across restarts
GPU Workloads: Deploy on GPU hardware
Examples: More patterns and use cases

On this page