> For the complete documentation index, see [llms.txt](https://firestonevm.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://firestonevm.gitbook.io/docs/readme.md).

# Firestone documentation

Run Linux VMs and container images on Cloud Hypervisor, from one binary.

Firestone runs Linux virtual machines on Cloud Hypervisor, and it runs OCI container images as virtual machines. One executable carries the VMM, `passt` and `qemu-img` inside it. It runs as your user, nothing keeps running between your commands, and every machine is a directory of files you can read.

<button type="button" class="button primary" data-action="ask" data-icon="gitbook-assistant">Ask the Firestone docs</button> <button type="button" class="button secondary" data-action="ask" data-query="How do I boot my first machine?" data-icon="bolt">First machine</button> <button type="button" class="button secondary" data-action="ask" data-query="How do I run a Docker image as a VM?" data-icon="box">Run a container image</button>

## Where to start

<table data-view="cards"><thead><tr><th></th><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><h3><i class="fa-download" style="color:$primary;">:download:</i></h3></td><td><h3><strong>Install</strong></h3></td><td>One command installs the release binary. No root, no daemon, no packages.</td><td><a href="/docs/install.md">Install</a></td></tr><tr><td><h3><i class="fa-bolt" style="color:$primary;">:bolt:</i></h3></td><td><h3><strong>Quick start</strong></h3></td><td>Check the host, boot Ubuntu, get a shell. About two minutes on a warm cache.</td><td><a href="/docs/quickstart.md">Quick start</a></td></tr><tr><td><h3><i class="fa-server" style="color:$primary;">:server:</i></h3></td><td><h3><strong>Machines</strong></h3></td><td>Lifecycle, snapshots, clone, live resize, logs and metrics.</td><td><a href="/docs/machines.md">Machines</a></td></tr><tr><td><h3><i class="fa-layer-group" style="color:$primary;">:layer-group:</i></h3></td><td><h3><strong>Images</strong></h3></td><td>Cloud images from the catalog, plus any OCI image from a registry.</td><td><a href="/docs/images.md">Images</a></td></tr></tbody></table>

## Go deeper

<table data-view="cards"><thead><tr><th></th><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><h3><i class="fa-browser" style="color:$primary;">:browser:</i></h3></td><td><h3><strong>Web interface</strong></h3></td><td>The embedded dashboard with a real terminal, served by <code>firestone ui</code>.</td><td><a href="/docs/web-ui.md">Web interface</a></td></tr><tr><td><h3><i class="fa-network-wired" style="color:$primary;">:network-wired:</i></h3></td><td><h3><strong>Networking</strong></h3></td><td>Port forwards, tap mode and shared folders.</td><td><a href="/docs/networking.md">Networking</a></td></tr><tr><td><h3><i class="fa-cloud" style="color:$primary;">:cloud:</i></h3></td><td><h3><strong>Cloud-init</strong></h3></td><td>SSH keys, passwords, user data and static addressing.</td><td><a href="/docs/cloud-init.md">Cloud-init</a></td></tr><tr><td><h3><i class="fa-terminal" style="color:$primary;">:terminal:</i></h3></td><td><h3><strong>CLI and REST</strong></h3></td><td>Every command, the REST server and the <code>--json</code> conventions.</td><td><a href="/docs/cli-and-rest.md">CLI and REST</a></td></tr><tr><td><h3><i class="fa-code" style="color:$primary;">:code:</i></h3></td><td><h3><strong>API reference</strong></h3></td><td>Every REST operation, generated from the tested OpenAPI contract.</td><td><a href="/docs/api-reference/api-reference.md">Overview</a></td></tr><tr><td><h3><i class="fa-wrench" style="color:$primary;">:wrench:</i></h3></td><td><h3><strong>Troubleshooting</strong></h3></td><td>The symptom table, plus the <a href="/docs/security.md">security model</a> behind the defaults.</td><td><a href="/docs/troubleshooting.md">Troubleshooting</a></td></tr></tbody></table>

## Platform

Firestone targets Linux x86\_64 hosts with KVM. The aarch64 target compiles and its catalog metadata exists, but there is no aarch64 runtime release and `doctor` refuses an aarch64 host. Non-Linux hosts, non-Linux guests, and cross-architecture emulation are not planned.

[`openapi.json`](https://github.com/0xchasercat/firestone/tree/main/docs/openapi.json) is the OpenAPI 3.1 contract for the REST API.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://firestonevm.gitbook.io/docs/readme.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.