install spore

spore runs on Linux, because the Linux kernel is what confines its agents. Pick the path for the machine in front of you, then run the first setup and try it in a git repository. Each step ends with the command that comes next.

Linux, x64 or arm64: spore runs on the machine itself.
macOS: spore setup makes a Linux VM (virtual machine) with Lima and runs spore there.
Windows: spore runs in WSL, which you set up yourself for now.

on Linux

needs	detail	check
Linux x64 or arm64	Both architectures install the same package.	`uname -m` prints `x86_64` or `aarch64`
Node 24+	Its bundled SQLite must be 3.51.3 or newer.	`node --version`, and the one-liner below
Linux kernel 5.13+	For Landlock, which limits the files an agent can reach. 6.12+ is best: it adds signal and abstract-socket scoping, so an agent can signal and reach only its own turn's processes.	`uname -r`
unprivileged user namespaces	Namespaces an ordinary, non-root user may create; spore uses them to shut each turn off from your other processes. Most distributions allow them. Ubuntu, from 23.10, restricts them through AppArmor, a Linux security module.	after install, `spore doctor` says how to allow them or how to run without. Where AppArmor restricts them, it and `spore setup` print the AppArmor profile that lets this install's `confine` — the spore program that makes a turn's namespaces — and no other program make them, with its real path and the command that loads it. They say when an existing profile names another `confine` than the installed one, as one written before 1.39.0 does, and when the path is one your user may replace.

Print the version of Node's bundled SQLite:

node -p "new (require('node:sqlite').DatabaseSync)(':memory:').prepare('select sqlite_version() v').get().v"

Then install the command, which puts spore on your path:

npm install -g @rhizogrip/spore-cli

next: spore setup

on macOS

macOS has no Linux kernel, so spore runs in a Linux VM on the Mac. You install two things; spore setup makes and prepares the VM.

1. the command

It needs Node 24+ on the Mac, whose bundled SQLite is 3.51.3 or newer: the VM gets the same version of Node, and spore checks its SQLite there.

npm install -g @rhizogrip/spore-cli

On a Mac this installs the command alone. Its core, which runs agents, installs only on Linux; it goes into the VM.

2. Lima

Lima runs Linux VMs on a Mac. spore does not install it for you: until limactl is on your path, spore setup stops and points to Lima's installation page.

3. setup, which makes the VM

spore setup

makes a VM named spore from Debian 13 with Lima, or starts it if it exists
installs in it the Debian packages spore needs, the version of Node the Mac runs, and the same version of spore
writes its name to ~/.config/spore/vm.json on the Mac
runs spore's own first run inside the VM, where the model and its key are chosen, so the Mac never holds a key

Each step looks first, so running it again changes nothing that is already in place. From then on, every spore command you type on the Mac runs in the VM, through limactl shell.

What this path costs:

The VM is a whole Debian system: it takes disk and memory on the Mac, and it is one more thing to install first, through Lima.
Only spore vm start and spore setup start the VM. A command given while it is stopped does nothing and says spore: the vm spore is stopped — run spore vm start. spore vm stop stops it.
Your spores live on the VM's own disk, not the Mac's. Lima shows your Mac home inside the VM read-only, so spore here works on a directory in the VM, not on one of the Mac's: clone a repository there to work on it.
The tick timer that setup offers runs in the VM, so schedules fire only while the VM runs.

spore vm startspore vm stop

next: answer the first run, which setup has started in the VM

on Windows

spore runs in WSL, Windows' own way of running Linux. Today you set WSL up yourself, from Microsoft's instructions, then follow the Linux path inside it. spore setup run on Windows itself stops and says spore: on Windows spore runs in WSL, which spore setup does not prepare yet.

The Linux kernel there is WSL's: run spore doctor inside WSL to see whether it has what spore needs and whether a confined command's ways out are refused there; where AppArmor restricts user namespaces, it prints the profile that allows them, as on Linux. A setup that prepares WSL itself, as macOS has for its VM, is coming.

next: the Linux path, inside WSL

why Linux

spore is built on five firm principles, and one of them decides where it runs: the sandbox around each agent is enforced by the operating system itself, not by spore's own code. The Linux kernel is where spore finds what it takes to fence a process in: Landlock, which limits the files it can reach; user, PID and mount namespaces of its own, so it sees only its own processes; and a syscall filter, which refuses requests such as mounting a filesystem. An operating system without them cannot hold that boundary, and spore never softens the boundary by itself to run where it cannot be enforced: a machine that cannot give a turn its namespaces runs no turn, unless you switch that off on purpose. So on macOS spore runs in a Linux VM and on Windows in WSL, not as a native port with the confinement dropped: the Linux kernel there is the VM's or WSL's, and the boundary is not weaker for it.

1 first run

spore setup

What it will do and ask, in order — on macOS, inside the VM, where it checks the VM's Linux, not the Mac:

on Linux, the first time, asks where spore runs: on this machine, the default, or in a VM made with Lima, as on macOS
checks this machine: Node's SQLite, Landlock, whether turns — an agent's work on one message — can be contained
asks where spores live (it offers ~/.spore)
sets up a provider through mohdel's mo onboard — a ChatGPT plan, OpenRouter, or another
sets the model new spores run on
offers the tick timer, which fires the spores' schedules when they fall due
runs spore doctor, and says how many ways out of the boundary were tried and refused
makes a first spore, called main

Each step looks first, so running it again is a check. Configuration lives under ~/.config/spore/; keys go in ~/.config/spore/environment — on macOS, the VM's — and the agent never sees the value.

what you can do with a spore once it exists

next: cd into a git repository, then spore here

2 first useful thing

cd path/to/a/git/repositoryspore here

On macOS the repository must be in the VM: limactl shell spore opens a shell there, where you clone it and run these two commands.

A terminal screen opens. Make one request. It reads the project, edits files where they are, and runs commands. Then, in the same screen:

/diff: shows what changed since the session opened
/undo: puts the directory back as this session found it

Git is the undo: each session starts with a snapshot of the directory.

next, if anything was missing along the way: spore doctor

3 when something is missing

spore doctor

It says what is missing on this machine — on macOS, in the VM — and how to fix it. It also tries the boundary rather than only reading what the machine offers: a command, confined the way spore confines a job (work a turn starts that outlives it), tries to read a file outside what it is granted, to write outside its directory and into one it may only read, to see and signal a process outside it, and to make namespaces of its own. Doctor lists each as refused, crossed or untried; a crossing the host should have refused is a problem. No model is called, and it takes well under a second.

spore doctor --report

--report prints this machine — versions, system, Linux kernel, Landlock, AppArmor, whether it can contain turns in namespaces of their own, any container or VM — with the boundary as tried and what doctor found, as a GitHub issue, and a link that opens the repository's host-report form filled with it. It names no path, user, host, spore or model, and spore sends nothing: you file it or not.

the spec

licence	Apache-2.0
runtime and library	`@rhizogrip/spore`: runs the agents, and is the library your Node code imports
command and terminal	`@rhizogrip/spore-cli`: the `spore` command and its terminal screen
runs on	Linux x64 or arm64, Linux kernel 5.13+ (6.12+ best). Agents always run on Linux: on macOS in a Lima VM, on Windows in WSL
needs	Node 24+ with SQLite 3.51.3+, unprivileged user namespaces
state	persistent, on disk: one directory per spore (`~/.spore`) holding its definition, its files and a SQLite database of its messages, turns and events, kept between turns — no Redis, no Postgres, no Docker
driven from	your own Node code, the command line, an HTTP API on a unix socket or a loopback address, with a token on every request
models	anything mohdel supports, chosen per spore
does not	ship a GUI, host anything for you, or run natively on macOS or Windows