Metadata-Version: 2.4
Name: mvm
Version: 0.1.2
Summary: Declarative microVM workloads for Python — author once, emit a Nix flake, boot under mvm.
Project-URL: Homepage, https://github.com/tinylabscom/mvmforge
Project-URL: Documentation, https://mvmforge-docs.pages.dev
Project-URL: Repository, https://github.com/tinylabscom/mvmforge
Project-URL: Issues, https://github.com/tinylabscom/mvmforge/issues
Project-URL: Changelog, https://github.com/tinylabscom/mvmforge/blob/main/CHANGELOG.md
Author: Tinylabs
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: firecracker,iac,infrastructure,microvm,mvm,nix
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.10
Provides-Extra: schema
Requires-Dist: pydantic>=2.0; extra == 'schema'
Description-Content-Type: text/markdown

# mvm — Python SDK

Declarative microVM workloads for Python. Decorate a function or describe a
workload, and the `mvmforge` host CLI emits a Nix flake plus a launch plan
that [`mvm`](https://gomicrovm.com/) can boot.

```sh
pip install mvm
```

The host CLI (`mvmforge`, written in Rust) is distributed separately. The
Python SDK ships only the authoring + runtime surfaces that the host
subprocesses to.

## Quick start

```python
# app.py
import mvm as mv

@mv.func(
    name="adder",
    image=mv.nix_packages(["python312"]),
    resources=mv.resources(cpu_cores=1, memory_mb=256, rootfs_size_mb=512),
)
def add(a: int, b: int) -> int:
    return a + b
```

```sh
mvmforge emit app.py        # canonical IR
mvmforge compile app.py     # flake.nix + launch.json
mvmforge up app.py          # boot under mvm (dev only)
```

## Three surfaces

| Surface | Purpose |
| --- | --- |
| **Authoring** | `@mv.app`, `@mv.func`, `mv.workload(...)`, factories for image / network / resources / deps. |
| **Runtime** | `f.remote(...)` and `mv.session(...)` — host-side calls into a function-entrypoint VM. **Dev-only by design.** |
| **Sandbox** | `mv.Sandbox`, `Process`, `FileEntry` — typed lifecycle handles over local mvm sandbox primitives. **Dev-only.** |

The runtime SDK exists to assist build-time emission and dev-time
introspection. Production microVMs are observed via `mvmctl logs` and output
streams; no host-side `.remote()` calls.

## Optional extras

```sh
pip install 'mvm[schema]'   # pydantic-based schema auto-derivation
```

## Documentation

Full documentation: https://mvmforge-docs.pages.dev/sdks/python/

## License

Apache-2.0
