Configuration

Configure an agent's behavior, sandbox permissions, and storage choices, and inspect the settings the agent uses at startup.

Inspect the Configuration

Inspect the resolved choices before editing an agent's TOML file. The command shows the opinions that apply to the selected agent, including defaults.

lnk agent spec show

Each value says whether it comes from Local Link, a built-in profile, a team, or your own settings. Expanding a built-in profile into the agent's file keeps the profile's default values attributed to that profile.

This Machine's Rules

Machine-wide policy lives in ~/.lnk/safe/agents/policy.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).

Know Who Writes the Rules

Only a person or their script writes the [storage] section. Machine identity is kept separately, and no agent's sandbox reaches the policy file.

Restrict the Sandbox

unsandboxed = false forbids running an agent without a sandbox on this machine. Computers and boxes both otherwise accept an explicit --no-sandbox; sandboxed remains the default. The policy file and its ancestors must be trusted, including a symlink's target. Malformed or untrusted policy is refused rather than treated as permission.

Share Processes

shared_harness = true shares one Link Harness process across an owner's agents on Linux. shared_bridge = true shares one bridge across agents. Both default to false and remain outside each agent's writable sandbox.

Agents' Ports

ports_from sets where agents' blocks of ports start on this machine: a new agent's, one arriving from another machine, and one moving off ports another program holds. It is 20000 by default and accepts a port from 1024 to 31768, which leaves a whole block below the system's range for outgoing connections. Several machines' agents sharing one computer's loopback, such as test fixtures standing in for boxes, each take a start of their own.

Keep Moved Files

keep_moved controls how long a moved agent's files, and a deleted agent's archive, remain here. The default is "30d". The setting accepts a number of days ending in d, and and accepts "never" to keep the files until you remove them.

home, instructions, skills, memory, conversations, and schedule

Each is a list of places, at least one, no place twice, the default first. The places are Local Link's file, sqlite, and bucket (Agent Spec), or a place whose driver this machine has. Left out, the list holds Local Link's places that serve the collection, file first.

Avoid a Place That Can't Serve a Collection

Local Link refuses a place for a collection its driver doesn't serve, such as home on sqlite, when it reads the file.

Install a Missing Driver

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

Run Agents Only While They Answer

A machine that runs agents only while they answer lists, for every collection, only places kept off the machine. An agent woken there reads its instructions, skills, and conversations as it left them before it slept.

Agents (lnk agent)

Agent Files lists every file lnk agent keeps for an agent, its harness, and its moves. An agent's folder, settings, and grants are below.

Pass Variables 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 module's tests.

Find What Each Command Reads

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

An Agent's Folder

~/Link/Agents/<name>/ (700) holds home/, the person's files, and agent/, the agent's own files, open to the person. Configuration is in ~/Link/Safe/Agents/<name>/, outside the agent's writable tree. lnk agent start --run.files <dir> makes another folder its Home (a repository it works in); agent/ stays here.

~/Link/Agents/<name>/
  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/

Reach Each Collection One Way

Each collection of the agent's (Agent Spec) kept on file is one folder here, so nothing has two ways in. A collection kept elsewhere has no folder here, and the storage bridge is the only way to reach it.

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, plain files you edit, and the agent too when you ask it ([files] write). 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, plain files you and the agent edit: 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-store), 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.

Grant Write Access

The agent's sandbox file grants what the agent may write of its own folder, or another agent's (below).

Know 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/Safe/Agents/<name>/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 Local Link's spec as concrete defaults, with built-in tools off and no extends line.

Recreate Files Automatically

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".

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.

[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.

Read the Machine Runtime Records

Local Link keeps these fields in this machine's private records, not in agent.toml. Identity and ownership are in identity.toml; ports, program paths and stopped services are in here.toml. Agent Files gives their full paths.

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.

stopped_services

The services of the install lnk agent migrate brought it in from, each kept from starting in ~/.lnk/safe/agents/stopped-services, 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). Every agent has its own, main too, given when it's made or arrives here, or at its next start when it has none. Its proxy, where it listens on this machine's loopback, takes the last port of the block.

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.

Sandbox Permissions

~/Link/Safe/Agents/<name>/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 permission add and remove, or written whole by lnk agent start --sandbox <file>; lnk agent show --permissions shows them.

Handle 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/.

Where It Finds Programs

Its run and code tools find a program on the PATH of whoever last ran lnk agent start, then the system's, so a toolchain your shell finds is found: rustup's cargo and rust-analyzer, nvm's node, uv's pyright. lnk agent start keeps those folders in this machine's record (here.toml's path); start it again after installing one elsewhere.

Give a Toolchain What It Needs

A toolchain in your home folder is read with what it needs beside it, ~/.cargo and ~/.rustup for rustup, a credential there hidden (~/.cargo/credentials.toml). A folder of your PATH no toolchain names is read alone. Its package caches are its own, in ~/.lnk/data/agents/<name>/caches/. [commands] still says which programs it may start: a coding agent's is ["*"], since a build or a test run starts programs no list names, its compilers' helpers and what the repository builds.

[files] write_dot_files

The dot files at the top of a folder it writes that run outside its sandbox, .git, .envrc, .vscode and .idea, stay read only to it unless write_dot_files names that folder, which write names too. A coding agent needs write_dot_files = ["."] to commit in the repository it works in, since a commit writes .git. The grant holds for its harness and for each call of its run and code alike, so git run through run commits. Its file never writes them, whatever the grant: it reads and edits files, and has no need to.

What It Opens

What it writes there runs as you, outside the sandbox, the next time you run git in the folder or open it in your editor: a hook in .git/hooks, git's settings in .git/config (an alias, a filter, core.fsmonitor), direnv's .envrc. So grant it only to an agent whose work you review, review a change's .git/hooks and .git/config before you run git there, and take it back with lnk agent permission remove --agent <name> --files.write_dot_files .. Import names it among what an archive's sandbox file opens. A later sandbox keeps the hooks and settings closed while the agent commits.

[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, or, with ["*"], any program on its PATH. Link's template has ["*"] beside its toolchains, so builds and what they make run: a stopgap until a sandbox made for toolchains and their builds' outputs replaces it. Drop it to keep only the toolchains.

[commands] without a file

No programs are granted. Adding run when none is allowed first asks which toolchains it may start: shell alone (the default, and what --yes takes), shell, git, python and node, or every toolchain Link's sandbox template grants. The choices are run_choices.toml, beside the tool setup's code. Adding code proposes installed language servers. Each proposal names the programs it lets the agent run and 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-permission list shows them. A harness without a file needs nothing.

Change a Harness's Grants

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

Name Paths in Grants

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

Read 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.

Where Things Live

Your agent's files, its harness, and its log each have a folder of their own.

  • ~/Link/Agents/<agent>/home holds your agent's files. lnk uninstall keeps them unless you pick agents.
  • ~/.lnk/data/agents/<agent>/harnesses/<name> is a harness's home, with its install, memory and conversations.
  • ~/.lnk/safe/agents/<agent>/logs/ holds its log.

Everything else Local Link keeps for an agent, and who can reach it, is in Security.