firevm-sdk 0.1.4
Python SDK for FireVM SaaS - Execute code in isolated Firecracker VMs
Requires Python: >=3.8

# FireVM Python SDK

Official Python client for executing code in isolated Firecracker VMs.

## Installation

```bash
pip install firevm-sdk
```

Or install from source:

```bash
cd sdk/python
pip install -e .
```

## Quick Start

```python
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

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

### Execute Bash Commands

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

### Handle Errors

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

### Multiple Languages

```python
# 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:

```python
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

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

Initialize the FireVM client.

### VM Management

#### create_vm()

```python
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()

```python
get_vm(vm_id: str) -> VM
```

Get VM details by ID.

#### list_vms()

```python
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()

```python
stop_vm(vm_id: str) -> VM
```

Stop a running VM. VM can be restarted later.

#### start_vm()

```python
start_vm(vm_id: str) -> VM
```

Start a stopped VM.

#### pause_vm()

```python
pause_vm(vm_id: str) -> VM
```

Pause a running VM (suspend to memory).

#### resume_vm()

```python
resume_vm(vm_id: str) -> VM
```

Resume a paused VM.

#### delete_vm()

```python
delete_vm(vm_id: str) -> VM
```

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

### Code Execution

#### execute()

```python
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()

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

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

#### execute_bash()

```python
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](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](https://docs.firevm.dev)
- Issues: [https://github.com/firevm/firevm-python-sdk/issues](https://github.com/firevm/firevm-python-sdk/issues)
- Email: support@firevm.dev

## License

MIT License - see LICENSE file for details.