# Overview (/docs)

Understand solitary before you run it.

Solitary runs coding agents in **hypervisor-isolated cells**. A cell is a Lima virtual machine with a container inside it: the VM is the security boundary, while the container is the replaceable toolset.

These docs explain the problem, the model, and the capabilities. The project is on its `0.x` line, so the shape of a cell's configuration can still change between releases.

## Start here [#start-here]

<Cards>
  <Card title="Install solitary" href="/docs/installation" description="What a host needs, and how to build it from source." />

  <Card title="Quickstart" href="/docs/quickstart" description="Create a cell, work in it, throw it away." />

  <Card title="Why Solitary exists" href="/docs/why-solitary" description="Why a mounted directory is not a boundary." />

  <Card title="Security model" href="/docs/security" description="What the VM boundary and explicit permissions protect." />
</Cards>

## Operate a cell [#operate-a-cell]

<Cards>
  <Card title="Commands" href="/docs/commands" description="The whole command surface, and what each one changes." />

  <Card title="Networking" href="/docs/networking" description="Egress control, DNS, ports and VPN routing." />

  <Card title="Moving work in and out" href="/docs/artifacts" description="Fetch what a cell published; send files to its inbox." />

  <Card title="The dashboard" href="/docs/dashboard" description="Every cell and its state in one live view." />

  <Card title="Troubleshooting" href="/docs/troubleshooting" description="The failure modes a cell actually has." />

  <Card title="Configuration reference" href="/docs/configuration" description="Every field in cell.yaml and config.yaml." />
</Cards>

## Guides [#guides]

<Cards>
  <Card title="Use an image or build a container" href="/docs/guides-images" description="Choose the toolset that runs inside a cell." />

  <Card title="Restrict network access" href="/docs/guides-network-policy" description="Give a cell only the egress it needs." />

  <Card title="Pass secrets safely" href="/docs/guides-secrets" description="Select and rotate the credentials a cell may receive." />

  <Card title="Route a cell through a VPN" href="/docs/guides-vpn" description="Send a cell's traffic through a WireGuard tunnel." />

  <Card title="Shareable workflows" href="/docs/guides-workflows" description="Keep the environment in code, then reuse it for teams and experiments." />
</Cards>

## What you can do [#what-you-can-do]

* Run an agent without mounting your repository into its environment.
* Replace the container image without replacing the cell's persistent VM disk.
* Pass only named secrets to the cells that need them.
* Control which ports reach the host and which domains the cell can reach.
* Send inputs in and fetch published artifacts out through explicit host commands.
* Route everything a cell reaches through a WireGuard tunnel, with no fallback when it is down.
* Watch every name a cell looks up and every connection it was refused, in a live dashboard.
* Throw away a cell and recreate it without losing its host-held secrets.
* Share the environment definition while keeping credentials and VPN files local.

## Important boundary [#important-boundary]

Isolation protects the host from a compromised cell. It does **not** make an agent harmless: it can still misuse any token, network destination, image, or other authority you grant it. Read [the security model](/docs/security) and [what solitary does not protect against](/docs/limitations) before trusting it with credentials.