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 environmentThen 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 runlnk agent start --sandbox sandbox.toml # yours, kept for the agentA 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, neverconversations/. - It reaches what the file grants: the internet through a proxy of its
own with
network, only thehostsit 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.
| Call | What it does |
|---|---|
run__start | Starts a command as run__command would, and answers with its id |
run__list | Each command, running or ended: its state, how long it ran, its output's size |
run__read | Its output from a byte you give, or its end |
run__stop | Stops 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
| Symptom | Fix |
|---|---|
| Your agent says it can't run programs | Its 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 host | Add 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 timeout | Ask 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.
