Config files for agents, boxes and sandboxes

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 create --cloud aws --spec web.toml          # a machine in your cloud
# a program, reaching only what the file allows
lnk sandbox run --spec app.toml -- npm test

The specs

Each spec and its shared sections have an owning reference page. This index follows the published reference pages, so newly added formats and sections appear when the inventories are regenerated.

Agent Spec

An agent's opinions: its harness, model, window, connections, tools and instructions (Agent Spec). lnk agent start --spec reads it, and lnk agent show --opinions prints the one it runs.

Box Spec

A machine in your own cloud: its CPUs, memory, disk, system and region (Box Spec). lnk box create --spec reads it, and lnk box spec prints the one a box was made from.

Sandbox Spec

What a program may write, read and reach (Sandbox Spec), read by lnk sandbox run --spec and lnk box user add --sandbox.

Tunnel Spec

A tunnel: its name, who may visit it, and whether it stands by (Tunnel Spec), proposed for lnk tunnel open. Spec-file support is not built yet. The command currently takes flags alone.

Relay Spec

A relay's opinions: how long a token it takes may last, and what each user may ask of it (Relay Spec). link-relay --spec reads it, and link-relay spec prints the one it runs. It's not built yet.

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.
  • Read where it really is. A spec's relative paths are from its own folder, and a spec reached through a link is read where the link points: sandbox.toml linked to ~/specs/common.toml with [files] write = ["."] grants ~/specs, never the folder the link is in.
  • 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.

Where an agent's things are kept

An agent prefers; its machine decides. Where each of its collections is kept ([storage]) is settled in layers, a later one winning:

  1. Link's spec: file for every collection.
  2. A team's, then the agent's own [storage]: the place it prefers for each collection, as specs meet as sets (Agent Spec).
  3. The machine's [storage] in ~/.lnk/machine.toml: for each collection, the places this machine supports, its default first (Machine settings). The agent's preference holds where the machine lists it; otherwise the collection is kept at the machine's default.

Nothing is hidden: lnk agent show --opinions prints the resolved spec, marking each key the machine overrode, and the agent's own file is never rewritten. A move says, before it starts, what is kept elsewhere where the agent lands; at a later move to a machine that supports its preference, the agent's spec holds again.

Settings you can write

A few more files are yours to edit. Each agent keeps setup and behavior in ~/Link/Agents/<name>/Config/agent.toml, and its permissions in Config/sandbox.toml, whichever harness runs it (Permissions); ~/.lnk/teams/<team>.toml, opinions a team's agents share (Agent Spec); and ~/.lnk/model-facts.toml, models you describe, or Link's figures you correct (Model Provider).

~/.lnk/machine.toml

This machine's own rules, such as never running an agent unsandboxed, and where its agents' things may be kept (Machine settings).

Every other file

Every other file under ~/.lnk is Link's to keep: each is on its plugin's Configuration page, and lnk variable list <command> lists the environment variables a command reads.

Credentials and secrets

A spec holds no credential: accounts and keys are the command's to say. Credentials is every credential Link mints, holds or checks, and who it authorizes, and Secrets keeps yours on this computer, given only where you grant them.

Docs

  • Environment Variables: Find the environment variables declared by Link's commands and libraries, including internal and test overrides
  • Decisions: Why Link's specs are what they are: first what holds for every spec, then each one's own