Overview
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
Install solitary
What a host needs, and how to build it from source.
Quickstart
Create a cell, work in it, throw it away.
Why Solitary exists
Why a mounted directory is not a boundary.
Security model
What the VM boundary and explicit permissions protect.
Operate a cell
Commands
The whole command surface, and what each one changes.
Networking
Egress control, DNS, ports and VPN routing.
Moving work in and out
Fetch what a cell published; send files to its inbox.
The dashboard
Every cell and its state in one live view.
Troubleshooting
The failure modes a cell actually has.
Configuration reference
Every field in cell.yaml and config.yaml.
Guides
Use an image or build a container
Choose the toolset that runs inside a cell.
Restrict network access
Give a cell only the egress it needs.
Pass secrets safely
Select and rotate the credentials a cell may receive.
Route a cell through a VPN
Send a cell's traffic through a WireGuard tunnel.
Shareable workflows
Keep the environment in code, then reuse it for teams and experiments.
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
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 and what solitary does not protect against before trusting it with credentials.