Sandbox Spec

Every option

Every key, as a file holds it. lnk sandbox spec --keys prints them as a table, and lnk sandbox spec --schema the spec's JSON Schema, for an editor to check a spec with: both are made from the one type Link reads a spec into.

# Yours: a name to tell specs apart, and a number to bump when you change one.
name = "app"
version = 1

# Your folders. A section needs write or read.
[files]
write = ["~/code/app"]              # read and written; relative paths are from this file's folder
read = ["~/Documents/reports"]      # read only; "~" alone reads your whole home
# Of write, the folders whose .git, .envrc, .vscode and .idea it writes too, for a sandbox that commits.
write_dot_files = ["~/code/app"]
hide = ["~/code/app/secrets"]       # closed whatever else is open

# How it reaches the network: through Link's proxy, as the sections below say, the default.
# [network]
# mode = "host"                     # instead: this machine's network as it is, no proxy, nothing filtered

# Public hosts, through Link's proxy. A section needs hosts.
[internet]
hosts = ["api.openai.com", "github.com", "*.githubusercontent.com"]
# hosts = ["*"]                     # instead: any public host
tcp = ["github.com:22"]             # raw host:port beyond HTTPS and HTTP; hosts must allow each
per_minute = 600                    # the most calls a minute, at least 1

# Other machines of your network, through Link's proxy. A section needs hosts.
[lan]
hosts = ["nas.local", "192.168.1.0/24"]   # names, addresses and ranges; "*" is the private ranges

# Servers on this machine. A section needs ports or models.
[localhost]
ports = [8080]                      # ports it may call
models = [11434]                    # a model runtime's port, for inference only

# Your tools from `lnk sandbox tool add`, which run outside with your logins. A section needs names.
[tools]
names = ["gh"]

# Pages it may ask you to open in your browser, each time. A section needs hosts.
[browser]
hosts = ["github.com"]              # or ["*"] for any host

# The programs it may run. A section needs allow; one left out runs nothing.
[commands]
allow = ["sh", "node", "git", "/usr/lib/git-core/"]   # names, paths, folders ending in /, or ["*"]

# On macOS, these keys replace the section's. Every section has these tables, for macos and linux.
[commands.macos]
allow = ["sh", "node", "git", "/Library/Developer/CommandLineTools/usr/libexec/git-core/"]
developer_tools = true              # Xcode's and the Command Line Tools' programs, read only

# [files.linux]
# hide = ["~/.local/share/keyrings"]   # hide adds to the section's instead of replacing it

# [localhost.macos]
# ports = [5432]                       # only on macOS, these ports and no others

Sections

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.

Each section's rules

What each section refuses, and how it reaches what it names.

Values

What a path, "*" and a host mean in every section.

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.

Flags and a file

A flag giving a key replaces the file's key, but --hide, which adds to it. Without --spec, the flags are the whole spec, and any program runs unless --command names them.

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 your PATH or 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, .vscode or .idea: write the project's folder, and name it in write_dot_files.
• A read or write in, or holding, a folder where programs keep their sockets: /tmp, /run, /var/run, /var/folders, $XDG_RUNTIME_DIR and 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.

More about it

How to use a spec: Describe a sandbox in a file. Why it is what it is: Decisions. Every spec Link reads, side by side: Specs.

Checked reference

The field names below come from link_sandbox_client::Spec. Optional values remain unset until the feature resolves its environment or inherited settings.

root: browser, commands, files, internet, lan, localhost, name, network, tools, version
browser: hosts, linux, macos
browser.linux: hosts, linux, macos
browser.macos: hosts, linux, macos
commands: allow, developer_tools, linux, macos
commands.linux: allow, developer_tools, linux, macos
commands.macos: allow, developer_tools, linux, macos
files: hide, linux, macos, read, write, write_dot_files
files.linux: hide, linux, macos, read, write, write_dot_files
files.macos: hide, linux, macos, read, write, write_dot_files
internet: hosts, linux, macos, per_minute, tcp
internet.linux: hosts, linux, macos, per_minute, tcp
internet.macos: hosts, linux, macos, per_minute, tcp
lan: hosts, linux, macos
lan.linux: hosts, linux, macos
lan.macos: hosts, linux, macos
localhost: linux, macos, models, ports
localhost.linux: linux, macos, models, ports
localhost.macos: linux, macos, models, ports
network: linux, macos, mode
network.linux: linux, macos, mode
network.macos: linux, macos, mode
tools: linux, macos, names
tools.linux: linux, macos, names
tools.macos: linux, macos, names

network.mode = "proxy"