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 nametier: 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 identifiercode: Code to executelanguage:"python","bash", or"nodejs"timeout: Execution timeout in secondswait: Wait for execution to complete
Returns: ExecutionResult with:
stdout: Standard outputstderr: Standard errorexit_code: Exit code (0 = success)execution_time: Time taken in secondserror: 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
- Visit https://firevm-frontend-345160625255.asia-northeast1.run.app
- Sign up for an account
- 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.
Metadata
Release files for firevm-sdk 0.1.4
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_sdk-0.1.4.tar.gz | 6.3 kB | Without provenance | Details for firevm_sdk-0.1.4.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| firevm_sdk-0.1.4-py3-none-any.whl | Python 3 | none | any | Details for firevm_sdk-0.1.4-py3-none-any.whl |
Total release size: 12.8 kB
Release files / firevm_sdk-0.1.4.tar.gz
| Download URL | firevm_sdk-0.1.4.tar.gz |
|---|---|
| Size | 6.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c84f436840c094a328d9a84157f309c2518ac8007c33c5da9249d8e03d6cab95
|
|
BLAKE2b-256 checksum How to use checksums |
2126f37299f591e58c78503c6c46a22d41e001d4bd17f5fee5179815abeb88ad
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.2
|
Release files / firevm_sdk-0.1.4-py3-none-any.whl
| Download URL | firevm_sdk-0.1.4-py3-none-any.whl |
|---|---|
| Size | 6.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2ebf0175d72bc9418c65350bc507b0d9089e953637d56abf6bb817024c0ca83d
|
|
BLAKE2b-256 checksum How to use checksums |
22334f1b4181d8b772ae6e44385e6fc92b669a9fcc2d3049b8796a68459da58b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.2
|
Security for firevm-sdk 0.1.4
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.