Metadata-Version: 2.4
Name: fcvm
Version: 0.7.0
Summary: A client for the fcvm HTTP API: Firecracker microVM sandboxes from Python
Author: Carlos Bravo
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/carlosbravoa/fcvm
Project-URL: Documentation, https://github.com/carlosbravoa/fcvm/blob/main/sdk/README.md
Project-URL: Issues, https://github.com/carlosbravoa/fcvm/issues
Project-URL: Changelog, https://github.com/carlosbravoa/fcvm/blob/main/CHANGELOG.md
Keywords: firecracker,microvm,sandbox,ai-agents,virtualization,isolation
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: System :: Emulators
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Dynamic: license-file

# fcvm for Python

A client for the HTTP API of [fcvm](https://github.com/carlosbravoa/fcvm),
which runs disposable, isolated Firecracker microVMs with container
ergonomics. Use it to give an agent framework, a test harness or a build
pipeline real VM sandboxes: create one from any OCI image, run commands,
move files, snapshot it and fork running copies in about 150 ms.

The client has no dependencies and needs Python 3.9 or newer. The VMs run
on a Linux host with KVM where fcvm is installed; the client itself runs
anywhere that can reach that host's API.

```sh
pip install fcvm
```

```python
from fcvm import Client

c = Client()
with c.create("box", template="python-sandbox", ttl="1h") as sb:      # removed when the block ends
    out = sb.run("pip install -q requests && python -c 'import requests; print(requests.__version__)'")
    sb.write_file("/work/app.py", "print('hi')\n")
    print(sb.exec("python /work/app.py").stdout)                      # ExecResult: exit_code, stdout, stderr
    job = sb.exec("python -m http.server 8000", background=True)      # a Job
    port = sb.publish(8000)                                           # http://127.0.0.1:{port} on the host
    job.kill()

snap = c.sandbox("prepared").snapshot("ready")
forks = snap.fork("try", count=3)                                     # three running Sandbox objects
```

`Client()` finds the local fcvm service by itself. For another host, set
`FCVM_URL` and `FCVM_TOKEN`. The token gives full control of fcvm, so treat
it like an SSH key.

- [All methods](https://github.com/carlosbravoa/fcvm/blob/main/sdk/README.md)
- [The HTTP API](https://github.com/carlosbravoa/fcvm/blob/main/docs/api.md)
- [Installing fcvm](https://github.com/carlosbravoa/fcvm/blob/main/docs/getting-started.md)

Apache License 2.0.
