FireVM Python SDK
Official Python client library for FireVM - A microVM management platform built on AWS Firecracker.
Features
- Simple & Pythonic API: Easy-to-use interface for managing microVMs
- Type-Safe: Full type hints and Pydantic models
- Async Support: Built-in async/await support with
aiohttp - Automatic Retries: Configurable retry logic for network errors
- Well-Documented: Comprehensive documentation and examples
Installation
# Basic installation
pip install firevm
# With async support
pip install firevm[async]
# Development installation
pip install firevm[dev]
Quick Start
Authentication
from firevm import FireVM
# Using API key
client = FireVM(api_key="fvm_live_your_api_key_here")
# Using JWT token (from OAuth)
client = FireVM(token="your_jwt_token_here")
Managing VMs
# Create a new VM
vm = client.vms.create(
name="my-app-vm",
tier="small", # small, medium, or large
image="ubuntu-22.04"
)
print(f"Created VM: {vm.id}")
# List all VMs
vms = client.vms.list()
for vm in vms:
print(f"{vm.name}: {vm.state}")
# Get VM details
vm = client.vms.get("vm_abc123")
print(f"VM {vm.name} is {vm.state}")
# Start/Stop/Restart a VM
client.vms.start(vm.id)
client.vms.stop(vm.id)
client.vms.restart(vm.id)
# Pause and resume
client.vms.pause(vm.id)
client.vms.resume(vm.id)
# Get VM logs
logs = client.vms.logs(vm.id, lines=100)
print(logs)
# Terminate a VM
client.vms.kill(vm.id)
API Key Management
# Create a new API key
key = client.api_keys.create(
name="production-key",
scopes=["vms:read", "vms:write"]
)
print(f"API Key: {key.key}") # Save this securely!
# List API keys
keys = client.api_keys.list()
for key in keys:
print(f"{key.name}: {key.scopes}")
# Revoke an API key
client.api_keys.revoke(key.id)
Async Usage
import asyncio
from firevm import AsyncFireVM
async def main():
async with AsyncFireVM(api_key="fvm_live_...") as client:
# Create VM
vm = await client.vms.create(
name="async-vm",
tier="small",
image="ubuntu-22.04"
)
# Start it
await client.vms.start(vm.id)
# Get status
status = await client.vms.get(vm.id)
print(f"VM state: {status.state}")
asyncio.run(main())
Advanced Usage
Error Handling
from firevm import FireVM, FireVMError, VMNotFoundError, QuotaExceededError
client = FireVM(api_key="fvm_live_...")
try:
vm = client.vms.create(name="test", tier="small", image="ubuntu-22.04")
except QuotaExceededError as e:
print(f"Quota exceeded: {e.message}")
except FireVMError as e:
print(f"API error: {e.status_code} - {e.message}")
Pagination
# Get all VMs with pagination
all_vms = []
page = 1
while True:
response = client.vms.list(page=page, limit=50)
all_vms.extend(response.data)
if page >= response.total_pages:
break
page += 1
Filtering VMs
# Filter by state
running_vms = client.vms.list(state="running")
# Filter by tier
small_vms = client.vms.list(tier="small")
Custom Configuration
from firevm import FireVM
client = FireVM(
api_key="fvm_live_...",
base_url="https://api.firevm.dev", # Custom API endpoint
timeout=30, # Request timeout in seconds
max_retries=3, # Max retry attempts
retry_delay=1.0, # Delay between retries (seconds)
)
API Reference
Client
FireVM(api_key=None, token=None, base_url=None, timeout=30, max_retries=3)
Main client for interacting with FireVM API.
Parameters:
api_key(str, optional): Your FireVM API key (starts withfvm_live_)token(str, optional): JWT token from OAuth authenticationbase_url(str, optional): Custom API base URL (defaults to production)timeout(int, optional): Request timeout in secondsmax_retries(int, optional): Number of retry attempts for failed requests
VM Operations
client.vms.create(name, tier, image, **kwargs)
Create a new microVM.
Parameters:
name(str): VM name (3-50 chars, alphanumeric + hyphens)tier(str): VM size tier (small,medium,large)image(str): OS image name (e.g.,ubuntu-22.04)
Returns: VM object
client.vms.list(state=None, tier=None, page=1, limit=20)
List all VMs for the authenticated user.
Returns: PaginatedResponse[VM]
client.vms.get(vm_id)
Get details of a specific VM.
Returns: VM object
client.vms.start(vm_id) / stop(vm_id) / restart(vm_id)
Control VM lifecycle.
Returns: VM object with updated state
client.vms.pause(vm_id) / resume(vm_id)
Pause and resume a running VM.
client.vms.kill(vm_id)
Forcefully terminate a VM.
client.vms.logs(vm_id, lines=100)
Get VM console logs.
Returns: str (log content)
API Key Operations
client.api_keys.create(name, scopes=None)
Create a new API key.
Parameters:
name(str): Key name for identificationscopes(list[str], optional): Permission scopes
Returns: APIKey object (includes plaintext key - save it!)
client.api_keys.list()
List all API keys (without plaintext values).
client.api_keys.revoke(key_id)
Revoke an API key.
Models
VM
class VM:
id: str
name: str
user_id: str
tier: str # "small" | "medium" | "large"
image: str
state: str # "creating" | "running" | "stopped" | "paused" | "terminated"
worker_id: Optional[str]
created_at: datetime
updated_at: datetime
metadata: dict
APIKey
class APIKey:
id: str
user_id: str
name: str
key_hash: str
key: Optional[str] # Only present when creating
scopes: list[str]
last_used_at: Optional[datetime]
created_at: datetime
revoked: bool
Error Handling
All errors inherit from FireVMError:
AuthenticationError: Invalid API key or tokenPermissionDeniedError: Insufficient permissionsVMNotFoundError: VM does not existQuotaExceededError: VM quota limit reachedRateLimitError: Too many requestsValidationError: Invalid request parametersServerError: Internal server error
Development
# Clone the repository
git clone https://github.com/firevm/firevm-python
cd firevm-python
# Install development dependencies
pip install -e ".[dev]"
# Run tests
pytest
# Format code
black firevm tests
# Type checking
mypy firevm
# Lint
ruff check firevm
Requirements
- Python 3.8+
requests>= 2.31.0pydantic>= 2.0.0aiohttp>= 3.9.0 (for async support)
Support
- Documentation: https://docs.firevm.dev
- Issues: https://github.com/firevm/firevm-python/issues
- Email: support@firevm.dev
License
MIT License - see LICENSE file for details.
Contributing
Contributions are welcome! Please read our Contributing Guide for details.
Metadata
Release files for firevm 0.4.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| firevm-0.4.1.tar.gz | 16.1 kB | Without provenance | Details for firevm-0.4.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| firevm-0.4.1-py3-none-any.whl | Python 3 | none | any | Details for firevm-0.4.1-py3-none-any.whl |
Total release size: 32.9 kB
Release files / firevm-0.4.1.tar.gz
| Download URL | firevm-0.4.1.tar.gz |
|---|---|
| Size | 16.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
70887cec00f93f501c4f7ae77c0ac2ccfa1119c8c469be813d4859ad9f273425
|
|
BLAKE2b-256 checksum How to use checksums |
8b3b9a4a29e08c3ad359bb4ba63783d4b99ebc35e2ab0374ce0318cda6b32195
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.2
|
Release files / firevm-0.4.1-py3-none-any.whl
| Download URL | firevm-0.4.1-py3-none-any.whl |
|---|---|
| Size | 16.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
39440c877c9f3643ec42a44f7bded8ec70c0bc1b4c22b45cbfc775545c922ddf
|
|
BLAKE2b-256 checksum How to use checksums |
240e60079d1bf6bad09997e98ad5748f6506780fd0ce8937d9c643fbc50ea747
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.2
|
Security for firevm 0.4.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.