principles

How a spore — an AI agent kept in a folder of its own — does its work, and then what bounds it. The design aims at two things: not paying the model, the large language model the agent thinks with, to redo work already done, and controlling what each call to it has to read. Every principle, with how spore itself is made, is in PRINCIPLES.md in the spore repository.

how a spore works

It keeps work that repeats as programs.

When a job repeats, the agent does not work it out again on every call to the model. It writes a small program, tests it and runs it: a program costs almost nothing to run again and gives the same result. The program stays in the agent's workspace — the folder that holds its definition, its files and the record of every turn, a turn being its work on one message — so a later turn, or a later week, can run it again. The agent still chooses when to write one, and still has to check what it produces.

One general agent creates narrow specialists.

A spore can do anything its definition allows. When a job needs focus — a narrow task, a few tools, a small budget — it does not narrow itself. It writes a precursor, a short text file naming a job, what may be used for it and how much time and money it may take, and starts a cell from it: a specialist made on the spot for that one job. A cell works in a smaller folder of its own, runs once and reports back. There are only two levels: a cell cannot create cells, so the agent on top keeps the others in check.

Programs are lent by name.

A program the agent wrote looks different from each side. The agent sees the file, and can change, run and test it. A cell sees only a name: the program is lent to it as an enzyme, which the cell calls by that name with arguments and input, and gets back its output and whether it succeeded. The cell is never told where the file is. What the two sides share is what any process has, so an enzyme can be written in any language. The agent does not lend programs to itself: it wrote them, so it simply runs them.

Seven tools, and programs for the rest.

A tool is a built-in action the model can call. There are seven, and each does something nothing else can: read brings a file into the agent's attention; write and edit change one; exec runs a command, confined, without changing the workspace; wsexec runs one that may change it; ask ends the turn with a question for the person; quiet ends it with nothing to say. Everything else is an ordinary program: searching is find and grep, fetching a page is curl, and a service that needs a key is reached by a plugin's program whose key the runner holds.

Big results stay in files.

When a command produces a lot of output, the output goes into a file. The agent is told the file exists and what it is, not shown all of it, so its context — what the model reads on each call — stays small, and so does the bill for it. It searches, filters and reads the parts it needs, and reads a file whole only when it chooses to. A turn that hands back work lists the files it made instead of pasting them into its answer.

A copy takes the skills, not the conversations.

A spore holds two different things: the conversations it had, and the programs and helpers it built. A new spore made from an old one takes the skills and none of the conversations. That also shows whether those skills work on their own, without the history of how they were made.

An agent is a file.

Each spore and each cell is described by one short text file, its definition: its model, its tools, how much time and money it may spend, what it may read and change, and in a few paragraphs who it is. The file is checked strictly: an unknown word or a missing limit is an error, never filled in by a guess. Anything that can write a file can make an agent — the agent writing a precursor, or your application making one spore per customer. A cell picks between the few model names its spore offers, such as “cheap” or “strong”, never a model of its own choosing.

execution boundaries

The agent does all of this inside limits it cannot move. Five principles draw them, each with what it implies and what it forbids. security sets out where they hold and where they stop.

principle	implies	forbids
The agent is untrusted; the operator is trusted.	Anything the agent reads — a web page, a document, a message, a tool's output — can steer it, so the boundary is drawn between the agent and everything else. The operator is the Unix user who runs spore and writes its configuration.	Pretending to defend the operator from their own processes. Another process of the same user that spore does not confine can read every spore's folder and every key, and spore says so.
The Linux kernel enforces the sandbox, not spore's code.	Every turn and everything it runs sits in user, PID and mount namespaces of its own, so it sees only the processes it started, and under Landlock, which limits the files it can reach, whatever the tool list says.	The tool list as the boundary. A host that cannot contain a turn runs no turn, unless the operator switches the `contain` setting off.
The key never reaches the agent.	Brokers — go-betweens in spore's runner — hold the credentials and accept only a key made for that one turn.	A provider key, bot token or source secret in an agent's environment.
The record is not the agent's to edit.	Spend is settled — counted and recorded — turn by turn; events, the log of what each turn did, are appended out of its reach; `~/.config/spore` is unreadable to it.	An account the agent could rewrite.
One folder per agent.	One spore per customer, per ticket or per conversation, driven from Node, the command line or HTTP.	An assistant you install once and share.

an agent is a folder; it keeps its work as programs and files; the Linux kernel fences in each of its turns; what it spent and did is recorded where it cannot reach.