Sandbox Spec Guide
How Link reads a sandbox spec: what each section opens and refuses, how one OS's table and field flags change it, and what a file may never grant. Each field is in the Sandbox Spec reference.
schema = 1
name = "app"
version = 1
[files]
write = ["~/code/app"]
read = ["~/Documents/reports"]
[internet]
hosts = ["api.openai.com", "github.com"]
tcp = ["github.com:22"]
[commands]
allow = ["sh", "node", "git", "/usr/lib/git-core/"]
[commands.macos]
allow = ["sh", "node", "git", "/Library/Developer/CommandLineTools/usr/libexec/git-core/"]
developer_tools = trueSections
A section is a grant, and one left out stays closed: a spec with no
sections reads none of your files, reaches no network and runs no
program. A section needs its main key: [files] needs write or
read, [internet], [lan] and [browser] need hosts,
[localhost] ports or models, [tools] names and [commands]
allow. An empty section, an unknown key and "*" beside other
entries are refused, naming the line, and a spec file is at most 64
KiB. lnk sandbox permission list lists each section with its field flags.
Each Section's Rules
What each section refuses, and how it reaches what it names.
[files] hide
The folders of write and read inside a hidden folder stay open.
hide adds up across the default table, an OS's table and the flags,
where every other key replaces the one before it.
[internet] tcp
Each endpoint names its port; *.abc.mongodb.net holds the names under
it, not abc.mongodb.net, and hosts must allow each. A *.
endpoint's port can't be a [localhost] port or 40781. On Linux, a spec
with endpoints gets DNS from its proxy
(how).
[lan] hosts
Which addresses each reaches, and what is refused whatever is listed:
Security.
On a cloud's machine, "*" and a range holding a whole private block
are refused too, since the network there is the cloud's.
[localhost]
A port is 1 to 65535, and 40781, the port of Link's proxy, is refused in
ports and in models. A model's port is reached through the proxy,
for inference only, never as a raw port, and models alone needs no
ports; with ports left out, only the models are reached.
[network] mode
"proxy", the default, has the program reach the network only through
Link's filtering proxy, as the other sections say. "host" gives it
this machine's network as it is, with no proxy and nothing filtered or
logged. A spec with it is shown as reaching the network unfiltered
before it runs.
Beside "host"
[internet] hosts can then only be ["*"], and [lan], [tools],
[browser], tcp, per_minute and models are refused, having
nothing to filter them. On macOS, [localhost] ports still names the
ports it reaches; on Linux it shares this machine's loopback whole.
[tools] names and developer_tools
[tools] names are letters, digits, - and _. [commands] developer_tools, true, reads Xcode's and the Command Line Tools'
programs, so git and compilers run; it means nothing but on macOS.
[commands] allow
A name is found on PATH when the run starts. A path is from the spec's
folder, and one ending in / allows every program in that folder.
lnk-sandbox and, on Linux, the program loader are always allowed. lnk sandbox learn lists the entries a command needs. An empty allow, or a
section missing allow, is invalid.
Installed program links
A name found on PATH grants the executable's real path, following
installed links such as Homebrew's python3. Link keeps that path for
the launch, so changing the link after discovery cannot redirect the
grant. Explicit paths still refuse links a non-root user owns.
What it refuses
An entry in a folder it may write, or in /tmp, is refused, and so is a
folder holding one of those ("/", or ~/tools/ beside write = ["~/tools/out"]).
Landlock
On Linux a finite effective list, after OS overrides, needs Landlock. A
spec without [commands] grants no programs and also needs Landlock.
When the required capability is unavailable, the launch is refused with
the observed reason. Every grant names its programs, so every sandbox
on Linux needs Landlock. A command line without a spec keeps its own
defaults.
Memory files
With an executable allowlist, Linux seals memory files non-executable
when its kernel and listener support that. Otherwise it refuses
memfd_create, so applications using it need a fallback.
Values
What a path, "*" and a host mean in every section.
Paths
~/ is your home folder; anything else relative is from the spec's own
folder. .. is refused.
"*"
In [internet] hosts, any public host; in [lan] hosts, the private
ranges; in [browser] hosts, any host; in [commands] allow, any
program; in [localhost] ports, every port, only with [network] mode = "host". It's refused in [files] and [tools].
Hosts
A name with a dot (api.openai.com), *.github.com for the names under
a name but not the name itself, or an IP address.
Dot files that run outside
At the top of each folder in write, a project's dot files that run
outside the sandbox are read only (each, and how).
write_dot_files lists the folders of write where they're written
too, for a sandbox that commits (Let it commit).
A folder in it that isn't in write is refused. Left out, none is.
One OS's Table
[<section>.macos] and [<section>.linux] hold the section's keys for
one OS. Each key given replaces the section's there, but hide, which
adds up. A section with only another OS's table is closed here. Its
field flags are its key paths, such as --files.macos.write.
lnk sandbox spec show prints the spec on this OS, and names the
file's tables for the other, which it leaves out.
Field Flags and a File
lnk sandbox run, check, learn and spec show take the file as
--spec FILE and each key as a field flag, its key path:
--files.write, --internet.hosts, --commands.allow. A flag giving a
key replaces the file's key, but --files.hide, which adds to it.
Without --spec, the flags are the whole spec. Omitted grants stay
closed in both inputs, and a grant always names its programs or toolchains. lnk agent permission add and deny
take the same flags, and Link shows each grant in them.
lnk sandbox run --commands.toolchains shell --files.write . --internet.hosts '*' -- bashlnk sandbox spec show --files.write ~/code/app --commands.allow node > app.tomlTeams
[teams.<team>] names the folders of a team's shared folder an agent
writes and only reads, each a folder's name in it or . for all of it.
Only an agent's harness knows where a team's shared folder is, so this
table is an agent's grant, in its sandbox file: lnk sandbox run
refuses a spec holding it, and an agent's lnk agent permission add --teams.research.write drafts grants one folder as any other grant.
Refused in a file
A spec from a file may be anyone's, so these are refused in it, with the flags given beside it:
- A folder in Link's settings or agents' folders, or a write of one holding them.
- A write of your home folder itself, a dot folder in it (
~/.ssh,~/.config),~/bin,~/Library, a folder on yourPATHor one holding it, or in the system's folders (The system's folders). - A write of the folder holding the spec, which would let the program change its next run.
- A write in a project's
.git,.envrc,.vscodeor.idea: write the project's folder, and name it inwrite_dot_files. - A read or write in, or holding, a folder where programs keep their
sockets:
/tmp,/run,/var/run,/var/folders,$XDG_RUNTIME_DIRand the temp folder, so/too. What answers on a socket there, a session's bus or Docker's, runs what it's asked outside the sandbox, and on Linux a socket connects read only. ..in a path.
The system's folders
/bin, /sbin, /usr, /etc, /lib, /lib32, /lib64, /boot,
/dev, /proc, /sys, /opt, /nix, /snap, /var,
/home/linuxbrew, and macOS's /System, /Library, /Applications,
/private/etc and /private/var. Homebrew's, /opt/homebrew and
/usr/local, are among them.
Flags, and a run's own folders
Flags alone are yours, or Link's own, and aren't checked this way.
The folders a run is given to write beside its spec's (lnk sandbox run --with-fd's write) are: each must be a folder there, named in
full with no . or .., and is refused as a write in a file is. A
program [commands] lists in a given folder is refused too.