Files your agent reads, writes and edits

Your agent reads, writes and changes the files in its files folder, as its sandbox file allows. Ask it to keep a list, fix a typo in a note or find where it wrote something, and Link Harness has it on already.

lnk agent start               # Link Harness, with file

Ask it to change a file

Ask it to "add tomatoes to my garden list" and it reads work/garden.md, replaces the line, and answers with what it changed.

What it needs

You need the agents plugins, which lnk up agents installs and which bring Link File, and Link Harness. There's nothing to set up, because each start gives the agent its file.

What your agent can do

Your agent sees four tools, each over a path in its files folder, such as work/garden.md.

file__read

It gives a text file, at most 24 KB a call, and says where it stopped so the next call reads on. An image (PNG, JPEG, GIF or WebP) or a PDF it gives whole, as MCP's image or resource content, so a model that reads them sees it.

file__write and file__replace

file__write writes a file whole, making it and its folders. file__replace replaces text it gives exactly, found once, or every time with all.

file__find

It finds files by a glob of their name, any case (*.rs), or of their path below the folder it looks in when the glob holds / (src/**/test_*.py, where **/ is any folders or none), and the lines a regular expression matches (fn \w+\().

Its diffs

file__write and file__replace answer with the change as a unified diff, as git diff shows one, so your agent sees what it changed. A diff over 16 KB, or of a file that wasn't text, is left out: the answer says so (diff_cut) and gives the new text's SHA-256 instead.

Turn it off

Its agent's spec turns it off ([tool.file] enabled = false), or only file__find (find = false), or the diffs (diffs = false): what it turns off isn't listed to the model, and the answers carry no diff.

Choose what it may write

Your agent writes only the folders its sandbox file's [files] lets it. Link's is work/: its instructions and skills are yours, and chats/ is never written but by its harness.

# ~/Link/Agents/main/Config/sandbox.toml
[files]
write = ["skills", "work"]                 # it may add skills
read = ["instructions", "chats"]   # nor may its memory note anything
lnk agent start --sandbox sandbox.toml

The whole of Home

write = ["."] is the whole files folder, its Home: an agent whose files folder is a repository (lnk agent start --files <repo>) changes any file of it.

Its own folder

Its instructions/, skills/ and chats/ are in its own folder beside Home (~/Link/Agents/<agent>/Agent), named as Home's folders are: beside ., "instructions" or "skills" lets it change those, and chats/ is never written but by its harness.

Its sandbox

Its calls run in a sandbox made from that file, with no network, so the sandbox holds to [files] whatever the tool is asked. One sandbox serves a session's calls, started at its first call, and runs nothing but File itself.

File never follows a link, and reads and writes text files up to 4 MiB, and reads images and PDFs up to the same: a replace that would make one larger is refused before it's made, and a pipe is never read or waited on.

Home in a bucket

Where your agent's files folder is kept in a bucket instead of on the machine that runs it, on a cloud that runs agents only while they answer, the same four tools reach it through the files bridge: a program outside the sandbox that reaches the bucket and nothing else, each call proved as your agent. Nothing of your files is kept on that machine. The paths, the folders [files] lets it write and the sizes are the same.

Its teams' folders there

Its teams' folders are at teams/<team>/ as on a machine, reached as the cloud says your agent is on each team at that call, and another account's team at teams/<account>/<team>/, where your agent reaches what that team's owner let it. A find with no folder looks in its own files folder alone.

A file changed meanwhile

A replace, and a write of a file your agent read or wrote before, names the version of the file it last saw: if the file changed meanwhile, from another of your agent's conversations, the write is refused, saying so, and your agent reads it again. Neither change is lost unseen. A write of a file your agent never read replaces whatever is there.

Reading on

A read that goes on from a later line gives the rest of the file as your agent read it from its first line, so all its pages are of one version and the bucket is read once for them. Reading from the first line again reads the file anew, as does a read after your agent changes the file.

Reach its team's folder

On a team, your agent's paths reach the team's shared folder at teams/<team>/, as teams/research/drafts/report.md. It reads and writes only the folders of it its sandbox file grants, [teams.<team>], which lnk agent team add writes.

lnk agent team add research --agent writer --write drafts --read sources

More about it

Agents Security has the guarantees and gaps, and Decisions why it works this way. To work on its code, see Developing Link File, and when it can't write or read a file, Troubleshooting.

Docs

  • Developing: lnk-file-tool is Link File: an MCP server over stdio that reads and writes an agent's files, its calls in a sandbox
  • Decisions: Why file keeps to [files] before its sandbox does, and how it works through a files bridge and in a bucket
  • Troubleshooting: What to do when your agent can't write or read one of its files (Link File)