Get Started

Your agent runs programs in its files folder, each in a sandbox of its own. Ask it to work something out in Python, convert a file or check a repository, and Link Harness has it on already.

You need the agents plugins, which lnk up agents installs and which bring Link Run, and Link Harness. There's nothing to set up, because each start gives the agent its run. Nothing costs anything: the programs run on your computer.

Quickstart

lnk agent start               # Link Harness, with run
lnk agent instructions        # "You may run sh, python3, ..." in its environment

Then ask it "what's 2 to the power of 100, in Python?" and it runs python3 -c 'print(2**100)'.

Choose what it may run

Your agent may run the programs its sandbox file's [commands] names, of those your computer has. Link's are a shell, Python, Node, git, curl, jq and the usual file tools.

# ~/.config/lnk/agents/main/sandbox.toml
[commands]
allow = ["sh", "python3", "/opt/tools/bin/convert"]   # ["*"]: any program; []: no run
lnk agent start --sandbox sandbox.toml   # yours, kept for the agent

A name is found on the system's PATH, and a program your computer doesn't have isn't offered, so without Python your agent is never told it has Python. There's no asking: [commands] allows or refuses. Permissions has the whole file.

How your agent calls it

Your agent sees one tool, run__command, which takes a program, its arguments as they are, what it reads on its input, and the folder of its files it runs in. A pipeline is sh -c. The answer is the exit status and what the program printed.

Each call runs in a sandbox of its own, made from the agent's sandbox file, which ends with the call:

  • It reads the files folder and writes only the folders its [files] lets it write, work/ among them, never conversations/.
  • It reaches what the file grants: the internet through a proxy of its own with network, only the hosts it names, and its tools.
  • Nothing it starts outlives the call, and the next call starts afresh.

Run a command in the background

A build, a test suite or a download runs on after the turn that started it, and your agent is told in the same conversation when it ends.

Ask it to "run the tests in the background and tell me how they went". It calls run__start, which answers at once with the command's id, and goes on with its turn. When the command ends, a message from it, never from you, tells the agent how it ended and the end of its output, and the agent answers in your chat.

CallWhat it does
run__startStarts a command as run__command would, and answers with its id
run__listEach command, running or ended: its state, how long it ran, its output's size
run__readIts output from a byte you give, or its end
run__stopStops it, with everything it started

A background command runs in the same sandbox a run__command call gets, and its output, both streams as one, is background/<id>.out in the files folder, which the agent reads but can't write. It lives as long as your agent runs: stopping or restarting the agent, or the computer, ends it, and the agent is told it was lost when it's back. Moving or deleting the agent stops every one, and none moves with it. Its ports are its own sandbox's, so start a server and its tests in one command (sh -c "server & tests"). Background commands are offered to a harness that takes messages from others, which Link Harness does.

Its limits and settings

A command runs for at most two minutes, and 16 KB are kept of each of its output and its errors, their start and their end. Both are keys of your agent's spec under [tool.run], timeout and output, and Agent Spec lists them all.

Four background commands run at once, each for at most an hour. The last 16 MB of each one's output are kept, and an ended one's record and output stay a day once the agent was told. The keys are background (0 turns them off), background_timeout, background_output and background_keep.

Troubleshooting

SymptomFix
Your agent says it can't run programsIts sandbox is off (--no-sandbox), or [commands] names nothing this computer has.
"isn't a program you may run here"Add it to [commands], then lnk agent start --sandbox your file.
A command can't reach a hostAdd network, or the host, with lnk agent allow.
"stopped after ..., still running at its timeout"A larger [tool.run] timeout in its spec.
A long command keeps stopping at its timeoutAsk your agent to start it in the background (run__start).
"... background commands run already"Wait for one to end, stop one, or raise [tool.run] background.
A background command was "lost"Your agent or your computer stopped or restarted while it ran: ask your agent to start it again.

Agents Security has the guarantees and gaps, and Agents Decisions why it works this way. To work on its code, see Developing Link Run.