Developing

lnk-link-run is Link Run: an MCP server over stdio that runs an agent's programs, each call in a sandbox of its own. How to use it: Link Run.

Build and test

From link-tools, with link-core beside it (LINK_CORE for another place):

cargo build -p link-plugin-link-run
# the sandboxed test skips without bubblewrap, unless LNK_REQUIRE_SANDBOX=1
cargo test -p link-plugin-link-run

How it's put together

  • serve --files <folder> --path <PATH> --timeout <duration> --output <bytes> --command <program>... -- <sandbox>... is the tool. Link gives it everything at a start: the programs of the sandbox file's [commands] this machine has, the spec's [tool.run], and the sandbox, lnk sandbox run with the flags the sandbox file makes. No number or grant is the program's own.
  • A call runs <sandbox> -- <program> <args>, the program found on --path, in the files folder or a folder of it, in a process group of its own. At its timeout the group is killed, and once the program exits, what it left running is too, a second later.
  • Each of its output and its errors keeps its start and its end, half of --output each, and how much there was.
  • Calls on one session run at once, each on a thread of its own.
  • tests/command.rs runs it without a sandbox, and on Linux under lnk-sandbox run from link-core.

Background commands

src/background.rs. With --state (and --way-in, --background, --background-timeout, --background-output, --background-keep, --hops), serve offers start, list, read and stop too.

  • start checks the call as command does, then, under a lock on <state>/start.lock, counts what runs, writes the record (<state>/<id>.json, outside the files folder: no sandbox writes it) and starts lnk-link-run supervise <state> <id>. It takes the record's lock (<id>.lock, flock) first and hands it to the supervisor as its input, so no sweep ever sees it free while it starts. The conversation and hops come from the call's _meta (link.local/thread, link.local/hops): without a conversation, or at --hops, it's refused.
  • supervise holds the lock for its whole life, which the kernel releases however it dies. It runs the sandbox in a process group of its own, with PR_SET_PDEATHSIG on Linux, so the sandbox, which bubblewrap ends with it, dies with the supervisor. Its output goes to background/<id>.out, opened with openat and never through a link; past --background-output, the newest half is copied beside and moved in place, and the record counts what was dropped. It stops the group at its timeout or on <id>.stop, records the end, then hands the bridge's way in a message from run:<id>. The record is marked told before, and unmarked only when the way in can't be reached. SIGTERM, SIGINT and SIGHUP, the agent's service stopping, end it lost, untold.
  • sweep <state>, run by the bridge as it starts and by serve at each start, takes each record's lock. A free one means its supervisor is gone. A running record is then marked lost, and what's left of its group is killed when it's surely its own: the same boot, and its leader the one recorded or gone. Ended records are told, tried again for ten minutes, and those told past their keep are removed with their output.
  • stop-all <state> (lnk agent stop) and forget <state> (lnk agent remove, a move) stop what runs. forget then removes everything.
  • tests/background.rs runs them as real processes: outliving the call and its server, told once through a stand-in way in, a stop leaving nothing, a supervisor killed or sent SIGTERM, the caps, the keep, and on Linux all of it under lnk-sandbox run.