Quickstart

This walks a cell from nothing to gone, twice: first one somebody already wrote, then one of your own. It assumes solitary is built and on your PATH.

Start with one that existsCopy Anchor Link

The repository ships two finished cells. Take the editor one:

solitary clone balakin/solitary/examples/vscode
solitary up vscode --detach

clone shows you what the definition asks for — its image, its machine, the secrets it wants, what it may reach — and installs a copy only after you say yes. up then creates the machine and builds the image inside it, so nothing in that Containerfile runs on your host. Expect the first build to take a while; it is downloading an editor and its extensions.

When it finishes, run limactl shell solitary-vscode podman logs solitary and open the authenticated URL printed by the editor. It uses http://localhost:9797 with a connection token. The forward reaches host localhost; the token protects access from other local processes and users.

solitary shell vscode      # a shell in the same cell
solitary ls                # every cell and its state

--detach is what leaves you at your own prompt rather than in the cell's shell; without it, up attaches one. See example cells for what is inside this one and how to change it.

Then write your ownCopy Anchor Link

solitary init demo

That writes ~/.config/solitary/cells/demo/cell.yaml — a commented file that explains its own options. The cell's name is the directory name, never a field inside the file, so the two cannot disagree.

The only line that is active out of the box is the image:

image: docker.io/library/ubuntu:24.04

Everything else — secrets, network, ports, vm, git — is commented out, which is also the default behaviour: no secrets, no port restriction, no egress restriction. See the configuration reference for the full surface.

Bring it upCopy Anchor Link

solitary up demo

up creates the machine if it is missing, boots it if it is stopped, replaces the container if the image or the secrets changed, asks for any declared secret that has no value, and then opens a shell inside the container. A cell on a published image is up in a couple of minutes; every run after is seconds.

up is the only command that changes state, and it is idempotent. Editing cell.yaml and running up again is the entire change workflow.

Work in itCopy Anchor Link

You are in the container, in /home/cell. That directory lives on the machine's disk rather than in the container, so it survives a new image, a stop and start, and anything a tool installs into the home directory.

git clone https://github.com/you/project
cd project && npm install && npm test

Nothing is mounted from the host, so the work starts by cloning rather than by finding your files already there. That is the point: an agent in this cell cannot write to your .git/hooks, your package.json scripts, or your editor configuration.

Drive it from the hostCopy Anchor Link

Leave the shell and run one command at a time:

solitary exec demo git status
solitary exec demo bash -lc 'npm test | tail -20'

exec exits with the command's status and leaves its streams alone, so a cell can be scripted from the host. The command is run directly rather than through a shell, so flags after it belong to it.

Get work outCopy Anchor Link

The cell publishes; the host collects.

solitary exec demo bash -lc 'artifact /home/cell/project/dist/app'
solitary fetch demo --list
solitary fetch demo

The file lands in your current directory, not executable. See moving work in and out.

Stop or destroy itCopy Anchor Link

solitary ls             # every cell and its state
solitary down demo      # stop the machine, keep the disk
solitary rm demo        # destroy the machine and its disk
solitary rm vscode      # and the one you cloned, if you are done with it

rm leaves the definition and the host-held secret values behind, so solitary up demo gives you a clean cell that is still authenticated. A clean rebuild is a normal operation here, not incident response.