Get Started

Everything you'd describe about an agent, a box or a sandbox is a TOML file you write. Hand it to the command that makes the thing, keep it in git, and you get the same agent, machine or sandbox every time.

lnk agent start --spec agent.toml          # an agent, as the file says
lnk box start aws --spec web.toml          # a machine in your cloud
lnk sandbox run --spec app.toml -- npm test   # a program, reaching only what the file allows

The three specs

Spec	What it describes	Read by
Agent Spec	An agent's opinions: its harness, model, window, channels, tools and instructions	`lnk agent start --spec`, and `lnk agent spec` prints the one it runs
Box Spec	A machine in your own cloud: its CPUs, memory, disk, system and region	`lnk box start --spec`, and `lnk box spec` prints the one a box was made from
Sandbox Spec	What a program may write, read and reach	`lnk sandbox run --spec` and `lnk sandbox guest add --spec`

Each page has a short description, then one example with every option, each with a comment saying what it does.

How every spec works

Learn one spec and you know the shape of the others. They share a few rules:

One format. Each starts with a name and a version, both yours, to tell your specs apart and to mark a change. The rest is sections of keys.
A file and flags say the same things. A command's flags and its spec come from one definition, so anything you can type, you can write down, and the other way round.
Left out means the least that works. A key you don't write gets the narrowest access and the lowest cost, never something wider. Wide open is written down, as ["*"], so reading a spec shows everything it opens.
Nothing of yours is in it. Accounts, keys and which machine it runs on are the command's to say, never the file's, so you can hand a spec to someone else. What it would grant on their machine is shown to them before it runs.
Every example is checked. Each spec on these pages is read by Link in its tests, so an example that stops working fails the build.

Why each rule is what it is: Decisions.

Settings you can write

A few more files are yours to write by hand, for what isn't one agent, box or sandbox:

File	What it holds	More
`~/.config/lnk/agents/<name>/sandbox.toml`	What you grant an agent, whichever harness runs it	Permissions
`~/.config/lnk/teams/<team>.toml`	Opinions a team's agents share	Agent Spec
`~/.config/lnk/model-facts.toml`	Models you describe, or Link's figures you correct	Model Provider
`~/.config/lnk/machine.toml`	This machine's own rules, such as never running an agent unsandboxed	Configuration

Every other file under ~/.config/lnk is Link's to keep. Each one, and every environment variable, is on Configuration.