Security model

Solitary is designed to stop a compromised coding agent from modifying or executing through your host. Its primary defense is a hypervisor-backed VM with no host filesystem mounts.

Protected by defaultCopy Anchor Link

• A container-root process cannot directly access the host kernel.
• The agent cannot read the host project, home directory, Git credentials, SSH agent, or Docker socket unless you deliberately provide an equivalent path.
• Files produced in the cell do not silently appear on the host.
• Secrets are selected by name and passed to individual cells rather than mounted as the host .env file.
• Cells have no integration that launches a host browser. Open a sign-in URL yourself, or authenticate on the host and pass the credential in as a secret. This is separate from network isolation: an unrestricted cell can reach host services, including services bound only to host localhost on Lima user-mode networks.

These are design goals, enforced by the hypervisor, Lima, the guest and Solitary together. A bug in any of them can break one, so read them as what the boundary is built to hold, not as a guarantee — see the boundary itself can fail.

Explicit permissionsCopy Anchor Link

The boundary is only as useful as the permissions around it. Keep secrets lists narrow, allow only the domains required by the task, and expose only the ports you intend to open. A cell with no network allow list follows the host's network by default, so use an allow list when egress matters.

gpu is the one setting that widens the boundary itself. The OpenGL and Vulkan commands a cell sends are carried out on the host, by virglrenderer inside qemu and by the host's GPU driver beneath it, so a flaw in either is reachable from inside the cell. Give a GPU only to a cell that renders.

Secrets lifecycleCopy Anchor Link

Secret values live on the host and are passed into the container as environment variables. The .env file itself does not enter the VM, but the values do. Values travel over standard input rather than host process arguments. Environment identity labels use a host-only HMAC key. Podman may record a container environment in the VM's metadata. Destroying the cell removes that metadata with the cell; rotate credentials if they may have been exposed.

Trusted inputsCopy Anchor Link

The image or Containerfile is trusted code. Building happens inside the VM, but a malicious image can still misuse the authority granted to its container. Review images and build definitions, and treat an outbox as untrusted input when fetching files onto the host.

Principle of useCopy Anchor Link

Give an agent a fresh cell, the minimum credentials, a narrow network, and an explicit path for artifacts. Assume the agent can do anything those permissions allow.