Sandbox Guide
Run any program so it changes only the folders you give it, reaches only what you allow, and never reads Link's settings. Link agents use it by default, and you can use it for your own commands.
lnk sandbox check --ready
lnk sandbox run --commands.toolchains shell --files.write . -- bash
lnk sandbox run --commands.toolchains shell --internet.hosts '*' -- curl -sI https://example.com
lnk sandbox run --spec app.toml -- node app.jslnk sandbox check --files.write .lnk sandbox log showWhat it needs
You need a Mac, whose Seatbelt is built in, or Linux with bubblewrap. The
sandbox module comes with every harness, and lnk module add sandbox
installs it alone. It's free and needs no account.
Run a program
How to run a program in the sandbox, with only the folders you give it, or with all of it written down in a file.
Run a program in the sandbox
The program reads the system's programs and libraries, and nothing else
unless you open it. It has no network. Its environment is cleared, so no
tokens or SSH_AUTH_SOCK from your shell reach it. run exits with the
command's status.
lnk sandbox run --commands.toolchains node --files.write ~/Projects/site -- npm run buildlnk sandbox run --commands.toolchains python --files.read ~/Documents/reports --files.write . -- python3 summarize.pylnk sandbox run --commands.allow ./tool --files.read '~' --localhost.ports 5432 -- ./toolIts arguments
Arguments after -- reach the program unchanged, including option names
also used by the sandbox's internal launchers.
--files.write and --files.read
--files.write <dir> is a folder it may read and write, and --files.read <dir>
one it may only read. Both repeat, and --files.read '~' reads your whole
home folder except Link's settings. --localhost.ports <port> lets it connect to a
port on this machine's loopback.
lnk sandbox run makes a folder it writes that isn't there yet, as it
starts, so a first step that fills ~/app keeps what it writes. A grant
can't reach a folder that isn't there.
--files.hide
--files.hide <dir> closes a folder to it even then, except for the --files.write
and --files.read folders inside it. Agents' folders in ~/Link/Agents, and
what agents that left kept in ~/Link/Archive, are always hidden this
way.
Behind a proxy that re-signs TLS
A company's network often re-signs every TLS connection with its own
certificate authority, which programs trust through SSL_CERT_FILE.
The sandbox keeps that variable and lets the program read the one file
it names, wherever it is, read only. It never opens the file's folder
or SSL_CERT_DIR's, which may hold more than certificates
(Security).
Every flag is a key
Every permission flag is a key of a spec, the file the next section writes. lnk sandbox permission list lists each section and its flags (Sandbox
Permissions), and lnk sandbox run --help
describes them.
Describe a sandbox in a file
A spec is a TOML file whose sections are the sandbox's only grants:
[files], [internet], [lan], [localhost], [tools], [browser]
and [commands]. A section left out stays closed, so a spec with no
sections reads none of your files, reaches no network and runs no
program. The spec
lists every key and what it takes.
lnk sandbox spec show --files.write ~/code/app --internet.hosts '*' --commands.allow node > app.toml
lnk sandbox run --spec app.toml -- node app.js
lnk sandbox run --spec app.toml --yes -- node app.jslnk sandbox check --spec app.tomllnk sandbox spec show --spec app.tomlschema = 1
name = "app"
version = 1
[files]
write = ["~/code/app"]
[internet]
hosts = ["registry.npmjs.org", "api.openai.com"]
[commands]
allow = ["sh", "node", "npm"]Asked first
A spec can come from anyone, so one you haven't run here, or one that
opens something different now, shows what it opens and asks first.
--yes answers for you. A flag beside --spec replaces that key of the
file's, except --files.hide, which adds to it.
What it can't open
A spec can't open Link's settings, agents' folders, or anything that would let a program reach outside the sandbox (each).
Let it commit
At the top of each folder it writes, a project's dot files that run
outside the sandbox, such as .git, .envrc, .vscode and .idea,
are read only (the full list).
So git status, diff and log work, and a commit, git config or a
new hook needs --files.write_dot_files to name the folder, or [files] write_dot_files in a spec.
lnk sandbox run --commands.toolchains git --files.write . -- git status
lnk sandbox run --commands.toolchains git --files.write . --files.write_dot_files . -- git commit -qam fixWhy they're read only
What's written there would run as you, outside the sandbox, the next
time you run git, cd into the folder or open it in your editor.
Only the top
Only the top of each folder is kept read only, so a repository the program clones or makes in a folder inside is its own to write. Give it the project's folder, not the one holding all your projects.
Choose what it can reach
The programs it 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: Choose What the Sandbox Can Reach.
Answer what a sandbox asks
A call that asks you first, such as a tool's or a page to open, waits
for a yes or no: lnk sandbox question list shows what waits and lnk sandbox answer answers it (Sandbox Questions).
Check it, and watch it
Try the sandbox from inside, see every call on its wire, and what each sandbox sent.
Check the sandbox
check plants bait, such as secrets in your home folder, in Link's
settings and in each --files.hide folder, and a server on another port. It
tries to reach each from inside, then removes it, and reports each try.
Like every sandbox, it first makes the Link folder and the folders every
sandbox hides there, where they aren't yet
(Hidden folders made first); those stay.
lnk sandbox checklnk sandbox check --files.write . --internet.hosts '*'lnk sandbox check --spec app.tomllnk agent harness check --harness linkWhat it reports
blocked when the sandbox stopped it, allowed when a folder or
permission you gave lets it through, failed when it was allowed but
didn't work here, missed when it should have been allowed and wasn't,
and open for a known gap.
leaked
Something nothing allows got through. It exits 1, and please report it (Security).
See every call on the wire
lnk sandbox log show lists each call on a sandbox's proxy, allowed or
refused, without its path, headers or body (Sandbox Log).
See what each sandbox sent
This is what each running sandbox's proxy has carried since it started,
up from the sandbox and down to it. lnk measure reads it as an agent's
network; a hosted model's tokens are counted by its route, read from the
usage each answer gives as it passes, and lnk measure reads them as
the agent's.
lnk sandbox showlnk sandbox show --jsonStop a sandbox
Closing a wire refuses every new call and ends open ones within a
second. lnk sandbox stop closes every wire and stops the programs
sandboxed here, however an agent behaves, and the log stays. lnk sandbox start opens the wires again.
lnk sandbox stoplnk sandbox startGiven a sandbox's name, both act on that sandbox alone: stop closes
its wire and leaves its program running, and start opens it again.
lnk sandbox list names every sandbox that runs or has run here, and
--paused keeps those whose wire is closed, with why.
lnk sandbox listlnk sandbox stop main-linklnk sandbox list --pausedlnk sandbox start main-linkWithout a wire
A sandbox without a wire, such as an agent with --network.mode host,
stops only when its program does. An agent with no sandbox keeps its
wire, but it closes only the calls the agent sends its proxy, which no
wall keeps it to.
A wire that pauses itself
A proxy also pauses its own wire when its calls look like no normal work, and notifies you. That means 30 calls refused within a minute, 20 different targets refused within 10 minutes, or any call to a cloud's metadata service.
Seeing it
lnk sandbox list --paused and lnk sandbox log show show which wires are paused
and why. lnk agent show shows its own, for a box where no
notification shows.
Let someone SSH into a sandbox
Box Users
gives each person a Linux login and sandbox on a box. Shells, remote commands,
and file transfers use that sandbox, whose command policy must allow
/bin/bash. Sandboxed SSH Sessions documents the forced
command interface used by a box controller.
Make the sandbox work on this machine
On Ubuntu 23.10 and newer, lnk sandbox check --ready also offers to add
an AppArmor profile with sudo, or prints the two commands. lnk agent start,
run and check make sure of this first, once a boot on Linux, and on
a Mac there's nothing to do.
sudo apt install bubblewraplnk sandbox check --readyWhere things live
Link keeps the sandbox's files in your settings folder, where no
sandbox reaches them: ~/.lnk/safe/sandboxes/ holds your tools, the wire's log
and waiting questions, and ~/.lnk/safe/sandboxes/specs.toml lists the specs
run here, so a new one asks first
(how).
More about it
What the sandbox guarantees, and its known gaps, are in Security. Why it works this way is in Decisions. How a module uses it is in Module Contracts. What to do when it fails is on Troubleshooting.