Configuration
The files lnk sandbox keeps, and what each one holds. Check this machine’s sandbox support before reviewing its saved configuration.
lnk sandbox check --readySandbox (lnk sandbox)
A program run by lnk sandbox run keeps only PATH, HOME, TERM,
COLORTERM, LANG, LC_ALL, LC_CTYPE, TZ, USER, LOGNAME,
SHELL and SSL_CERT_FILE from your shell. lnk help <command> lists the environment
variables each command reads, as module.toml
declares them.
A proxied policy's files
What ~/.lnk/safe/sandboxes/ (700) holds for each policy: its rules, one
Seatbelt profile per policy, and these.
~/.lnk/safe/sandboxes/<name>.routes.json (600)
A proxied policy's routes (its tools, models, secrets, pages it opens)
and who calls them, which its proxy hands each call's route to its
bridge with. Never for lnk sandbox run, which hands its proxy them on
a pipe.
Nothing secret
A hosted model's key and the secrets are named, each read by its bridge from your secrets at each call; one holding a value is refused, written or read.
~/.lnk/safe/sandboxes/<name>.url-secret (600)
The secret the URLs of a proxied policy's routes carry, which its proxy requires on each of them.
Bridges
<runtime>/lnk/sandbox/bridges/<module>.sock is a module's bridge for its proxies'
routes (models, secret, sandbox), this user's. Its calls are
proved against the machine's keyring.
How long it runs
It's started by the first proxy that needs it, and gone once idle, or as soon as the keyring binds no one (the last agent stopped, the last sandbox ended), ending any call still open there, a long poll's among them. A lock beside it keeps it to one. An upgrade that replaces its program ends it once no call is in flight, and the next call starts the new build.
Its own service
On Linux, where systemd runs Link's services, it runs in a user unit of
its own, lnk-bridge-<module>, so no agent's service holds it.
Restarting one agent leaves the bridge, and every other agent's tool
sessions, running. Its warnings go to <module>.log beside its socket,
kept once as <module>.log.1 past 1 MiB. Elsewhere it runs in a process
group of its own.
Known limit
The proxy that starts the bridge reaches systemd's user manager only
when its own environment holds XDG_RUNTIME_DIR. A proxy started by an
agent's service is expected to inherit it from that service, but this
hasn't been checked on a box yet. Without it, the bridge starts in a
process group of its own, inside the first agent's service again, and
restarting that agent stops it. systemctl --user status 'lnk-bridge-*' shows whether a bridge runs in its own unit.
The wire
What the proxies log, count and wait on.
wire.log and asks/<id>.json
~/.lnk/safe/sandboxes/wire.log (600) is lnk sandbox log show's: one JSON object
per proxied call. ~/.lnk/safe/sandboxes/asks/<id>.json (600) is a question a
proxy is waiting on (lnk sandbox question list).
~/.lnk/safe/sandboxes/traffic/<pid>.json (600)
lnk sandbox show: the bytes a running proxy has carried each way,
written every 5 seconds while it changes, with when its proxy started.
Read only by lnk sandbox show, whose --json other modules read.
When it goes
Its proxy removes it when its program ends, or lnk sandbox show
does once its proxy is gone.
~/.lnk/safe/sandboxes/stopped and paused/<sandbox>
While stopped exists, every proxy refuses every call. While
paused/<sandbox> (600) exists, that sandbox's proxy refuses every
call.
Tools
The tools that run outside, and the hubs of those shared.
~/.lnk/safe/sandboxes/tools/<name>.json (600)
A tool that runs outside (lnk sandbox tool add): its command, or
mcp-remote and its URL, and its environment, headers included.
<runtime>/lnk/sandbox/tools/<key>.sock (600), .lock, .log
A shared tool's hub (--shared): its socket while it runs, its lock,
and its log.
<key>
It names the tool by its name and as it's defined, signed with tools/.key (600), a
secret made once on this machine, so the name gives away none of the
tool's tokens. It alone names the socket, without the tool's name, as
macOS keeps a socket's path to 104 bytes and its runtime folder takes
about 60.
~/.lnk/safe/sandboxes/settings.toml
The sandbox module's settings, over Link's. A proxy, the sandbox's
bridge and a shared tool's hub read it from the folder they're handed,
never through the HOME they run with, which for an agent is its
harness's. A file that can't be read is said, and Link's are used.
ask_wait
How long a question waits for your answer: "120s", at most "24h";
silence is no. An agent's sandbox waits as its spec's [connections] ask_wait says instead.
tool_starts and tool_sessions
tool_starts is the tool servers the sandbox's bridge starts at once
(2), and tool_sessions the tool sessions one sandbox keeps (8).
tool_idle and shared_idle
tool_idle is how long a tool's session stays, its server with it,
with no call ("5m"), and shared_idle how long a shared tool's server
stays up with no session open ("10m").
On Linux
What a sandbox keeps of this machine and of its runs, on Linux alone.
~/.lnk/safe/sandboxes/placeholders.json (600)
The empty placeholders made where a project's dot file isn't, while sandboxes run, the dot files to sweep in Link's data folders when a run ends, and which runs hold each; removed with the last.
~/.lnk/safe/sandboxes/bwrap-version (600)
What a sandbox's start found of this machine, so the next doesn't ask
again: whether its bubblewrap can refuse user namespaces inside, and
the checks that passed (bubblewrap makes a sandbox here, and wrap's
requirements hold). lnk sandbox check --ready removes it and checks afresh.
When it's asked again
It holds for this boot, kernel and user, the kernel's user namespace
settings, and these copies of bubblewrap and lnk-sandbox: any of
those changed, or a file that isn't a plain one only you may write, and
they're asked again.
~/.lnk/safe/sandboxes/specs.toml (600)
The sandbox specs run here, each by its path and a hash of what it opens (spec).
Command Arguments
The command metadata names the trailing argument list commands for
sandbox run and sandbox learn. It is separate from --commands.allow,
which selects programs the sandbox may run. Arguments still follow --.
Serialized run and learn inputs use commands as their field name.
Internal Environment Inputs
These inputs belong to process startup and isolated tests. A program inside a sandbox cannot use them to enlarge the policy that confines it.
LNK_SANDBOX_LEARN_FD
The first sandboxed program receives the descriptor used to record started programs and removes the variable. A program that sets it inside the sandbox can record its own descendants only, rather than observe unrelated execution.
LNK_TEST_ON_CLOUD
A value of 1 makes the proxy apply cloud-machine LAN restrictions for tests.
It cannot make a cloud machine count as a non-cloud machine, so it cannot
relax those restrictions.