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

# Introduction

Run Linux virtual machines on your computer, from a terminal or an AI agent.

A virtual machine (VM) runs its own operating system inside your computer. Use one to try Linux, test software, or give an agent an environment to work in. Stoat manages local QEMU VMs through a command-line interface (CLI), an interactive terminal interface (TUI), and the Model Context Protocol (MCP).

![Stoat's terminal interface lists two running VMs and one stopped VM.](https://raw.githubusercontent.com/NovusEdge/stoat/main/assets/tui-list.png)

[Watch the 23-second demo](https://github.com/NovusEdge/stoat/blob/main/assets/demo.mp4) to see the terminal interface and an Alpine XFCE desktop running in QEMU.

## Start here

Choose a guide for your task:

| I want to…                                    | Guide                                                                                |
| --------------------------------------------- | ------------------------------------------------------------------------------------ |
| Install Stoat on my Linux computer            | [Installation](/stoat/getting-started/installation.md)                               |
| Create a VM and open a shell                  | [Your first VM](/stoat/getting-started/first-vm.md)                                  |
| Connect an AI agent                           | [MCP workflow](/stoat/workflows/mcp-workflow.md)                                     |
| Use Stoat from scripts or a shell-based agent | [CLI reference](/stoat/reference/cli.md) and [JSON output](/stoat/reference/json.md) |
| Keep a repeatable environment in a repository | [Project workflow](/stoat/workflows/project-workflow.md)                             |
| Run a VM on Google Cloud instead of locally   | [The GCP path](/stoat/workflows/gcp.md)                                              |

## Choose an environment

Alpine live VMs provide disposable sessions. Changes inside the guest are lost when it stops. Installed disk VMs and cloud-image VMs retain their disks between runs. See [Modes and backends](/stoat/concepts/modes-and-backends.md) before choosing where to keep work you need to save.

[Recipes](/stoat/recipes/overview.md) install software and configure a guest. They can set up a desktop, development tools, or other software after the VM starts.

## Requirements and limits

Stoat runs on Linux with KVM, QEMU, and OpenSSH. An Alpine disk install also requires `xorriso`. The [installation guide](/stoat/getting-started/installation.md) covers host packages and permissions; `stoat doctor` checks your setup.

Stoat is single-user. It manages VMs on the local machine and assumes it is the only process managing its data root. It does not provide multi-tenant isolation. Read [Access and auth](/stoat/concepts/access-and-auth.md) before granting an agent guest access or sharing host files.

If a command fails, start with [Troubleshooting](/stoat/troubleshooting/troubleshooting.md). See the [source code](https://github.com/NovusEdge/stoat) and [published releases](https://github.com/NovusEdge/stoat/releases).