Choose What the Sandbox Can Reach
The programs a sandboxed program runs, the hosts, machines and models it
reaches, the tools it calls and the pages it opens, each a flag of lnk sandbox run and a key of a spec (Sandbox).
Choose the programs it may run
Nothing runs that [commands] does not name, whether the grants come
from a file or field flags. The program given to run must be named,
or the run is refused before it starts. A grant always says what it lets
run, so no entry stands for every program: allow = ["*"] is refused.
lnk sandbox learn --spec app.toml -- npm testlnk sandbox run --files.write . --commands.allow sh --commands.allow git -- sh -c 'git status'
lnk sandbox run --spec app.toml -- npm testA program refused
A program started from inside that isn't listed gets "Permission denied", and the sandbox says which:
lnk sandbox: refused /usr/lib/git-core/git-remote-https: add it to [commands] allowToolchains
A toolchain names a language's or a task's programs in one word:
--commands.toolchains rust or toolchains = ["rust", "git"]. It
stands for its programs found on PATH (Cargo, rustc, and
rust-analyzer for Rust), and the folders where those keep the programs
they start themselves (rustup's toolchains, the compiler's own).
lnk sandbox permission list lists each toolchain with its programs, as
the sandbox declares them.
Build folders
A toolchain also runs what its builds make, in each folder the sandbox
writes that is a project of its kind. Rust's build scripts and tests run
from target/ beside Cargo.toml, a package's commands from
node_modules/ beside package.json, and a virtual environment's from
.venv/ beside pyproject.toml or requirements.txt. A folder of
another kind gets no build folder. A build folder is made as the sandbox
starts, since a folder that isn't there can't be granted, and never
through a link.
Installer build folders
A program wrapping a sandbox with lnk sandbox wrap may name one more
build folder: the folder an installer it runs installs into, which the
sandbox writes. An installer that unpacks a runtime there can then run
it (Security). A spec never names one.
lnk sandbox run --files.write . --commands.toolchains rust --commands.toolchains git -- cargo testlearn
learn runs the command once under the spec's other grants with every
program open, and prints the entries to add to [commands] allow. It
writes nothing. A helper a program starts only now and then is found
only if this run starts it.
An entry
An entry is a name found on PATH, a path, a folder ending in / for
every program in it. A script needs itself and what it
starts with, so #!/usr/bin/env node needs env and node. An entry
in a folder it may write, or in /tmp, is refused. A toolchain's build
folders are the one exception.
An interpreter
Listing an interpreter such as sh, node or python3 lets it run any
code it's given. The list limits which programs run, not what they do.
What it needs
On Linux this needs Landlock, which is in Linux 5.13 and newer. On
macOS, naming a refused program and learn need an admin user, because
they read what Seatbelt reports in the system log.
Give it the internet through Link's proxy
The program gets the internet without the rest of your network. Its
only way out is Link's filtering proxy, set as its HTTPS_PROXY, which
refuses this machine, your network and a cloud's metadata service. Every
agent with [internet] runs this way, unless it has [network] mode = "host".
lnk sandbox run --commands.toolchains python --internet.hosts '*' -- python3 fetch.pylnk sandbox run --commands.allow ./bot --internet.hosts api.anthropic.com --internet.hosts '*.telegram.org' -- ./botlnk sandbox run --commands.toolchains git --internet.hosts github.com --internet.tcp github.com:22 --files.write . -- git clone git@github.com:me/repo.git
lnk sandbox run --commands.toolchains node --internet.hosts '*.abc.mongodb.net' --internet.tcp '*.abc.mongodb.net:27017' -- node app.jslnk sandbox run --commands.toolchains shell --internet.hosts '*' --upstream socks5://127.0.0.1:1080 -- curl -sI https://example.com--internet.hosts and --internet.tcp
--internet.hosts names a host it may reach, or * for any, and
*.telegram.org covers the names under it but not telegram.org
itself. --internet.tcp <host:port> opens an endpoint beyond HTTPS on 443 and
HTTP on 80, such as github.com:22 for git over SSH, and its host must
be one it may reach.
--upstream and --internet.per_minute
They change where its traffic leaves from and how many calls it may
make. The upstream is direct, a SOCKS5 proxy
(socks5://127.0.0.1:<port>, or socks5://<a socket's absolute path>), or an HTTP proxy on this machine's loopback
(http://127.0.0.1:<port>).
An HTTP proxy upstream
It's for a machine whose traffic leaves only through a filtering proxy of its own network: that one is handed each host's name, which it resolves, so this machine looks up no name the sandbox asks for.
A program that ignores HTTPS_PROXY
It has no network. Python follows it, and Node gets
NODE_USE_ENV_PROXY=1. Git over SSH works once its endpoint is named
with --internet.tcp, using the sandbox's own key in its ~/.ssh.
Names on Linux
On Linux the sandbox also gets DNS from its proxy, so a --internet.tcp host
with a port from 1024 is reached by its name, and psql "host=db.example.com" and mongodb+srv:// work as they are (its
DNS).
Other endpoints, and a Mac
Other endpoints, and every one on a Mac, are reached only by a client
that takes a ProxyCommand, like ssh. On a Mac, psql and database
drivers can't reach a --internet.tcp endpoint.
Reach your network
--lan.hosts lets it reach machines of your network on any port, through
its proxy. It takes a name, an address, a range, or * for the private
ranges, and your network is reached from here whatever --upstream
says. Security says which
addresses a host reaches, and what it never reaches whatever is listed.
lnk sandbox run --commands.toolchains shell --lan.hosts nas.local -- curl http://nas.local:5000/lnk sandbox run --commands.allow ./sync --lan.hosts 192.168.1.0/24 --internet.hosts '*' -- ./syncLet it use a model
--localhost.models <port> makes a local model runtime such as Ollama, LM Studio
or llama.cpp reachable for inference only. That means chat, generation,
embeddings and the models' list, and pulling, creating or deleting a
model gets a 403. On Linux the program keeps the runtime's address. On
macOS it reaches the runtime at $LNK_LOCAL_MODEL_<port>, on its proxy.
lnk sandbox run --commands.toolchains python --localhost.models 11434 --files.write . -- python3 chat.pyA hosted model's key, or a secret
The proxy can also add a hosted model's key, or a service's secret such
as a Telegram bot's token, so the program never holds it: each is a
route of the proxy's, served outside the sandbox by the module it's for
(lnk-model, lnk-secret), as Security
explains.
For an agent
Agent startup configures this route automatically on Link Harness and on harnesses whose adapter accepts the proxy address. The route interface explains how that startup passes the permitted model credential use.
Calling it
The program calls http://127.0.0.1:<proxy port>/_link/model with a
placeholder key, and adds /v1 for OpenAI and OpenRouter. The proxy
port is 40781 on Linux. It works with Anthropic, OpenAI and
OpenRouter. A service's secret is reached the same way, as Security
explains.
Call a tool that runs outside
A tool is an MCP server that runs outside the sandbox, with your logins,
desktop and SSH agent, or a server at a URL reached from outside with
its headers, which no sandbox sees. Use one for what the sandbox keeps
out, such as gh or aws with your credentials. A sandbox reaches only
the tools it names, at $LNK_TOOL_<NAME>, so $LNK_TOOL_GH for gh.
lnk sandbox tool add gh --allow list_issues --allow get_issue -- github-mcp-server stdiolnk sandbox tool add docs --url https://example.com/mcp --header-file docs.headers
lnk sandbox tool add notes --shared -- notes-mcp servelnk sandbox tool-call list ghlnk sandbox tool listlnk sandbox run --commands.allow my-agent --tools.names gh -- my-agentlnk sandbox tool remove ghAsked first
Every call asks you first, except those you --allow by name, and
--ask none asks for none. Removing a tool ends its sessions.
Asked by an Argument
--ask-if <call>.<argument> makes a call ask by one of its boolean
arguments: it asks unless that argument is given false, even when
--allow names the call. A tool whose call takes a flag, such as a
schedule's recurring, asks for the one case and lets the other
through.
lnk sandbox tool add scheduler --allow schedule --ask-if schedule.recurring -- lnk-scheduler-tool serveThe argument is read from the call as the tool receives it, so a call
that leaves it out asks. Since --allow can't let such a call through, --ask-if-hint says what
can, in the words of whoever adds the tool, such as an owner's setting.
A call it asks by that's refused with no one to answer names the hint,
and without one names the argument to give false
(With No One to Ask).
lnk sandbox tool add scheduler --allow schedule --ask-if schedule.recurring --ask-if-hint "recurring = \"allow\" in its settings lets it through" -- lnk-scheduler-tool serve--shared
A tool with --shared runs one server for every session, where any
other starts one each, and stops once none has been open for the
sandbox's shared_idle: a team's memory is one.
--env
A tool's server runs with a few of your variables as they were when it
was added, and --env gives it one more: NAME=value, or NAME for
its value here at that moment. Only the server gets it. The sandbox
calling the tool never sees it, and lnk sandbox tool list never prints
it, so a token for the server belongs here.
lnk sandbox tool add aws --env AWS_PROFILE=work -- aws-mcp-serverA secret goes by its name alone. A command line can be read by other
users of this machine and stays in your shell's history, so --env
refuses NAME=value for a name that says it holds a secret (…_TOKEN,
…_KEY, …_SECRET, …_PASSWORD). Set it in your shell without echo,
then name it:
read -rs GITHUB_TOKEN && export GITHUB_TOKENlnk sandbox tool add github --env GITHUB_TOKEN -- github-mcp-server stdioOpen a page in your browser
With --browser.hosts, a program can open an https:// page in your
browser, such as a login, on the hosts given (* for any). Every page
asks you first and shows its whole URL, because it opens with your
cookies and logins. $BROWSER in the sandbox does it, so Python's
webbrowser, gh and xdg-open work as they are.
lnk sandbox run --commands.toolchains python --browser.hosts github.com -- python3 -m webbrowser https://github.com/loginA login's answer
A login that answers on localhost (its redirect_uri) gets that port
until the answer arrives, or for five minutes at most. With no desktop,
such as on a box, nothing opens, and the program's own fallback, a URL
to copy or a code to type, still works.