Configuration

The files lnk agent keeps for this machine and for each agent, and what each one holds.

This machine's rules (machine.toml)

[storage] says, for each of an agent's collections, the places this machine supports, its default first. An agent's own [storage] is a preference: it holds where the machine lists it, and the collection is kept at the machine's default otherwise (Specs).

Who writes it

Only a person or their script writes its [storage]: lnk box create writes a box's ID and name alone, and no agent's sandbox reaches the file.

home, instructions, skills, memory, conversations and schedule

Each a list of places, at least one, no place twice, its default first: Link's file, sqlite and bucket (Agent Spec), or a place whose driver this machine has. Left out, Link's places that serve it, file first.

A place that can't serve it

A place for a collection its driver doesn't serve, such as home on sqlite, is refused when the file is read.

A driver not installed

A place listed whose driver isn't installed installs at an agent's start, as a plugin a feature needs does.

A machine that runs agents only while they answer

It lists, for every collection, only places kept off the machine, so an agent woken there reads its instructions, skills and conversations as it left them before it slept.

Agents (lnk agent)

Every file lnk agent keeps for an agent, its harness and its moves is on Agent Files; an agent's folder, settings and grants are below.

Variables passed to the bridge

lnk agent start passes each LNK_<NAME>_API and _CLI variable it's run with (never one naming a key, token, secret, password or auth) to the agent's bridge service, or the one bridge every agent shares, for a connection plugin's tests.

What each command reads

lnk help <command> lists the environment variables each command reads, as plugin.toml declares them.

An agent's folder

~/Link/Agents/<name>/ (700) holds Config/, the person's configuration, Home/, the person's files, and Agent/, the agent's own files, open to the person. lnk agent start --files <dir> makes another folder its Home (a repository it works in); Agent/ stays here.

~/Link/Agents/<name>/
  Config/
    agent.toml          setup and behavior
    sandbox.toml        approved permissions
  Home/                 the person's: documents, work
    memory/             documents memory searches, the person's to edit
  Agent/                the agent's: its brain, open to the person
    instructions/       its instructions
    skills/
    memory/             its notes and memory's index
    chats/
    schedule/

One way in

Each collection of the agent's (Agent Spec) kept on file is one folder here, so nothing has two ways in; kept elsewhere, its folder isn't here, and it's reached only through the storage bridge.

Home/

The home collection: the person's documents and the agent's work (Home/work/, anything else it makes). Home/memory/ is the documents its memory searches: Link Memory indexes this folder and the conversations, and nothing else of Home/. Read only by default.

Agent/instructions/

The instructions collection, yours to edit as plain files. instruction.md, optional, is your standing instructions, a section of Link Harness's prompt, read at each message (lnk agent show --instructions prints the prompt).

Who it is, and you

persona.md and owner.md, optional: who it is and who you are, two sections more. models/<maker>/<model>/instruction.md, optional: yours for that model, the model named as OpenRouter names it, another section of it.

Agent/skills/<name>/SKILL.md

The skills collection, yours to edit as plain files: a skill, as the Agent Skills standard writes one. lnk agent skill add copies its folder here, and Link Harness lists its name and what it's for in its prompt.

Agent/memory/ (700)

The memory collection: notes.md, the agent's notes, written by remember up to [tool.memory] notes and read into its prompt; and <engine>/, its memory engine's index and what else it keeps, such as Link Memory's index.sqlite.

Agent/chats/<thread>/

The conversations collection: Link Harness's chats, each events.jsonl, a line per message, only added to, and conversation.md, a copy to read; beside them tools.json, and while a turn runs turn.json.

Agent/chats/events.sqlite (600)

The collections the agent keeps on sqlite (lnk-sqlite), as rows, with their leases: in chats/, the one folder of Agent/ its harness writes, as a driver run in its sandbox writes it.

Agent/schedule/ (700)

The schedule collection, as lnk-file-store keeps it: its jobs (jobs/, firing/) written by its scheduler's tool and fired by its bridge.

What it may write

What the agent may write of its own folder, or another agent's, is its sandbox file's to grant (below).

What Home keeps

An agent is laid out as two folders wherever it is made, comes in a move or returns from a backup. Nothing is moved from Home into Agent/: what Home holds, a repository's skills/ or a folder the agent wrote there, stays Home's, and a move leaves such a folder behind, saying so.

Agent configuration

~/Link/Agents/<name>/Config/agent.toml holds setup and behavior together. Commands such as start, connect, model set and tool add save choices here. You may also edit it, then run lnk agent restart. Credentials stay in the secret store. New agents get concrete personal defaults, with built-in tools off and no extends pointer.

Automatic creation

Creation writes both configuration files. When an existing agent's file is missing, the next agent command recreates it with defaults and says so. Deleted custom configuration is not restored. The stable identity is retained separately in private runtime state, and recreation leaves stored credentials untouched. Invalid or unreadable files cause an error rather than being replaced.

[behavior]

The Agent Spec describes these keys. In this file they live beneath behavior, such as [behavior.tool.file] enabled and [behavior.model] thinking. The root [model] selects the provider and model ID, while [behavior.model] sets inference preferences. command_response belongs directly in [behavior] and can label harness answers with "🤖 Automated Response".

id

The agent's ID, which never changes and moves with it, wherever the agent goes. A move here refuses an agent whose name another agent of another ID has, and one whose ID an agent of another name has.

owner

Whose it is: the account signed in (acct-<id>), or before you sign in, <user>@<machine>, which the account replaces at its next start. Left out, the latter.

kept_off

The services of the install lnk agent migrate brought it in from, each kept from starting in ~/.lnk/kept-off, by its path in your home folder: lnk agent delete puts each back. Left out, none.

port and block

Its first port and how many from there are its harness's (left out: 200); none for main.

tools_offered and meaning_offered

Whether the agent was asked which of Link's tools it gets, and whether it was asked for memory's embedding model, whatever it answered: not asked again. Left out, false.

webhook_port

The port on 127.0.0.1 its bridge takes its webhooks' posts at, chosen at its first lnk agent webhook create and kept.

[webhooks.<name>]

Each of its webhooks: id, its hook's id, the last part of its address; from, github for one GitHub signs (left out, Link's scheme); and while its secret rolls, previous_until, until when its previous secret is taken. Its secrets are your secrets' (lnk secret list), never this file's.

Sandbox permissions

~/Link/Agents/<name>/Config/sandbox.toml holds what you grant the agent, whichever harness runs it, as a sandbox's spec in the agent's own terms. Changed by lnk agent allow and deny, or written whole by lnk agent start --sandbox <file>; lnk agent show --permissions shows them.

Missing or invalid permissions

A missing file grants no additional files, programs or network, even before recreation runs or if writing the replacement fails. Agent commands recreate it with closed permissions and report the path. A section left out stays closed, and an unknown key is an error. Sandbox on means OS isolation is enabled. The status also shows the sandbox file and its saved grants. Restart a running agent after changing permissions so the next process uses them.

[files] write and read

The folders it may write, and those it may only read, by name, side by side: one of its Home's (work), or its instructions, skills or chats, in Agent/. write = ["."] is the whole of Home, beside which only those three are named, and read = ["~"] is your whole home.

[files] without a file

No additional folders are granted. Tool setup can propose access to work with your confirmation. The harness still accesses its own chat storage, while memory writes notes through its separate remember tool.

Which harness it holds for

It holds for a harness that keeps to the layout (Link Harness), whose sandbox then writes only these and chats/; a harness that doesn't writes all of Home, and never reaches Agent/.

[internet]

hosts, the hosts its proxy lets it reach (["*"], any), tcp, endpoints beyond HTTPS and HTTP (host:port), and per_minute, the most calls a minute on its proxy.

[localhost], [lan] and [network]

[localhost] ports is this machine's localhost ports it may reach, each (a database or a service running here); ["*"] only with [network] mode = "host". [lan] hosts is machines of your network it reaches through its proxy. [network] mode = "host" is the network as it is, with no proxy.

[tools] and [browser]

[tools] names is the tools that run outside it it may call. [browser] hosts is the hosts whose pages it may open in your browser, asking you each time.

[commands] allow

The programs it may start, by its run tool or its harness (beyond the harness's own program, which Link starts), each a name on the system's PATH or an absolute path, or ["*"] for any; [], no run. Only those this machine has are offered.

[commands] without a file

No programs are granted. Adding run proposes a shell when none is allowed, and adding code proposes installed language servers. Each proposal is displayed for confirmation before the tool is enabled.

[teams.<team>]

write and read: the folders of a team's shared folder it may write, and those it may only read, by name, or "." for all of it; written by lnk agent team add. A team it's on that isn't here, it reaches none of. Holds in whichever harness runs it, and in Link's tools.

A harness's grants (harnesses/<harness>.toml)

What the harness said it needs (lnk-<harness> needs) and you allowed, held while it runs, for every agent here that runs it. lnk agent harness permissions shows them. A harness without a file needs nothing.

How it changes

By answering what it asks, by lnk agent harness allow and deny (only for what it asks for), and by reset. This file holds harness needs separately from the agent's own approved permissions.

Its paths

Each path in it is absolute or from ~, and none is inside the Link folder's Agents, Teams or History, where agents' settings and files are: a file naming one is refused.

A spec's sections, and risks

A spec's sections hold what it asked for that you allowed ([network] mode = "host"), and risks the risks of its own it named that you allowed (browser).

answered and [asked]

answered is the risks it asked for that you answered. [asked] is a spec: every need it asked for that you answered, allowed or not, not asked again until reset.