Metadata-Version: 2.4
Name: fastvm
Version: 0.2.0
Summary: Async Python SDK and CLI for the FastVM microVM platform
Project-URL: Homepage, https://fastvm.org
Project-URL: Documentation, https://fastvm.org/docs
Project-URL: Source, https://github.com/fastvm/fastvm-sdk
Author-email: FastVM <hello@fastvm.org>
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: AsyncIO
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: click>=8.1
Requires-Dist: httpx[http2]>=0.27
Requires-Dist: tabulate>=0.9
Requires-Dist: websockets>=13.0
Description-Content-Type: text/markdown

# FastVM Python SDK & CLI

Async Python SDK and CLI for the [FastVM](https://fastvm.org) microVM platform. Launch, snapshot, restore, and run commands on microVMs over HTTP/2 with multiplexed connections.

## Installation

```bash
pip install fastvm
```

or with [uv](https://docs.astral.sh/uv/):

```bash
uv add fastvm
```

For CLI-only use (isolated install, puts `fastvm` on your PATH):

```bash
pipx install fastvm
# or
uv tool install fastvm
```

## CLI Quick Start

```bash
# Set your API key (one-time)
export FASTVM_API_KEY=your-key
# or persist it:
fastvm config set api_key your-key

# Launch a VM and open an interactive console
fastvm launch --name dev --console

# List VMs
fastvm vm ls

# Run a command on a VM (by name or short ID)
fastvm vm exec dev "uname -a"

# Ephemeral one-shot: launch, run, destroy
fastvm run "apt update && python3 --version"

# Snapshots
fastvm snapshot create dev --name my-snap
fastvm snapshot restore my-snap --console

# Quotas
fastvm quota
```

VMs and snapshots can be referenced by full ID, short ID prefix (git-style), or name.

Enable tab completion (one-time):

```bash
# bash
eval "$(_FASTVM_COMPLETE=bash_source fastvm)"
# zsh
eval "$(_FASTVM_COMPLETE=zsh_source fastvm)"
```

Run `fastvm --help` for the full command reference.

## SDK Quick Start

```python
from fastvm import FastVM

# Also configurable via the FASTVM_API_KEY environment variable.
async with FastVM(api_key="your-key") as client:
    vm = await client.launch(machine="c1m2")
    snapshot = await client.snapshot(vm, name="my-snap")
    restored = await client.restore(snapshot)
    result = await client.run(restored, "echo hello")

    print(result.stdout)  # hello
```

## SDK API Overview

| Method                                   | Description                     |
| ---------------------------------------- | ------------------------------- |
| `launch()`                               | Launch a new microVM            |
| `restore()`                              | Restore a VM from a snapshot    |
| `run()`                                  | Execute a command on a VM       |
| `snapshot()`                             | Create a point-in-time snapshot |
| `get()` / `list()`                       | Fetch VM state                  |
| `remove()`                               | Delete a VM                     |
| `list_snapshots()` / `remove_snapshot()` | Manage snapshots                |
| `set_firewall()` / `patch_firewall()`    | Configure IPv6 ingress firewall |
| `console_token()`                        | Request a console session token |
| `quotas()`                               | Fetch organization quota usage  |

## Documentation

See the [FastVM documentation](https://fastvm.org/docs) for the full API reference and guides.

## Examples

```bash
uv run examples/create-vm.py      # launch a VM and run commands
uv run examples/large_fanout.py   # snapshot + restore 10 VMs concurrently
```

## License

Apache-2.0
