FireVM Python SDK

Official Python client for executing code in isolated Firecracker VMs.

Installation

pip install firevm-sdk

Or install from source:

cd sdk/python
pip install -e .

Quick Start

from firevm_sdk import FireVMClient

# Initialize client with your API key
client = FireVMClient(api_key="your_api_key_here")

# Create a VM
vm = client.create_vm(name="my-vm")
print(f"VM created: {vm.vm_id}")

# Execute Python code
result = client.execute_python(vm.vm_id, """
print("Hello from FireVM!")
print(f"2 + 2 = {2 + 2}")
""")

print(result.stdout)  # Hello from FireVM!\n2 + 2 = 4
print(result.exit_code)  # 0

Examples

Execute Python Code

result = client.execute_python(vm.vm_id, "print('Hello World')")
print(result.stdout)  # Hello World

Execute Bash Commands

result = client.execute_bash(vm.vm_id, "ls -la && whoami")
print(result.stdout)

Handle Errors

result = client.execute_python(vm.vm_id, "1/0")
if result.exit_code != 0:
    print(f"Error: {result.stderr}")

Multiple Languages

# Python
client.execute(vm.vm_id, "print('Python!')", language="python")

# Bash
client.execute(vm.vm_id, "echo 'Bash!'", language="bash")

# Node.js
client.execute(vm.vm_id, "console.log('JavaScript!')", language="nodejs")

Error Handling

VM Quota Exceeded

When you reach your VM limit, the SDK raises a VMQuotaExceeded exception:

from firevm_sdk import FireVMClient, VMQuotaExceeded

client = FireVMClient(api_key="your_key")

try:
    vm = client.create_vm("my-vm")
except VMQuotaExceeded as e:
    print(f"❌ {e.message}")
    print(f"   Current VMs: {e.current_vms}/{e.max_vms}")
    print(f"   Your tier: {e.tier}")
    print(f"   Suggested: Stop unused VMs or upgrade your tier")

Tier Limits

• Free tier: 5 concurrent VMs, auto-stop after 10min idle
• Paid tier: 10 concurrent VMs, auto-stop after 10min idle
• Pro tier: 20 concurrent VMs, auto-stop after 10min idle
• Enterprise: 999 concurrent VMs, auto-stop after 10min idle

Upgrade at: https://firevm-frontend-345160625255.asia-northeast1.run.app/pricing

API Reference

FireVMClient

FireVMClient(api_key: str, base_url: str = "https://firevm-backend-345160625255.asia-northeast1.run.app")

Initialize the FireVM client.

VM Management

create_vm()

create_vm(name: str, tier: str = "small", wait: bool = True) -> VM

Create a new VM instance.

Parameters:

• name: VM name
• tier: VM size ("small", "medium", "large")
• wait: Wait for VM to be ready (default: True)

get_vm()

get_vm(vm_id: str) -> VM

Get VM details by ID.

list_vms()

list_vms(state: Optional[str] = None) -> List[VM]

List all VMs, optionally filtered by state.

Parameters:

• state: Optional filter ("running", "stopped", "paused", etc.)

stop_vm()

stop_vm(vm_id: str) -> VM

Stop a running VM. VM can be restarted later.

start_vm()

start_vm(vm_id: str) -> VM

Start a stopped VM.

pause_vm()

pause_vm(vm_id: str) -> VM

Pause a running VM (suspend to memory).

resume_vm()

resume_vm(vm_id: str) -> VM

Resume a paused VM.

delete_vm()

delete_vm(vm_id: str) -> VM

Delete (kill) a VM permanently. This action cannot be undone!

Code Execution

execute()

execute(vm_id: str, code: str, language: str = "python", timeout: int = 30, wait: bool = True) -> ExecutionResult

Execute code in a VM.

Parameters:

• vm_id: VM identifier
• code: Code to execute
• language: "python", "bash", or "nodejs"
• timeout: Execution timeout in seconds
• wait: Wait for execution to complete

Returns: ExecutionResult with:

• stdout: Standard output
• stderr: Standard error
• exit_code: Exit code (0 = success)
• execution_time: Time taken in seconds
• error: Error message if any

execute_python()

execute_python(vm_id: str, code: str, **kwargs) -> ExecutionResult

Shorthand for execute(..., language="python").

execute_bash()

execute_bash(vm_id: str, code: str, **kwargs) -> ExecutionResult

Shorthand for execute(..., language="bash").

Get Your API Key

1. Visit https://firevm-frontend-345160625255.asia-northeast1.run.app
2. Sign up for an account
3. Copy your API key from the dashboard

Support

• Documentation: https://docs.firevm.dev
• Issues: https://github.com/firevm/firevm-python-sdk/issues
• Email: support@firevm.dev

License

MIT License - see LICENSE file for details.