| sand.template(5) | File Formats Manual | sand.template(5) |
sand - template format
A template is a TOML (Tom's Obvious Minimal Language) file which describes a how sand(1) creates a bwrap(1) sandbox. sand reads templates from $XDG_CONFIG_HOME/sand/ or ~/.config/sand.
Template might build upon other templates, specified in extends array. Each base template is read from left to right and extended the following way:
extends
Bases are merged in the listed order: a later base overrides an earlier one, and the template itself overrides all of its bases.
bwrap
bootstrap
When enabled, sand:
Values from the [env] section are applied after bootstrap and override it.
chdir
executable
entrypoint
network
userns
nocwd
Environment variables passed to the sandbox. Sand passes no environment variables except these and the ones set by bootstrap.
NAME = "value"
NAME = true
NAME = false
bind
dirs
Mapping of fake files and their contents created inside the sandbox. PATH is an absolute path inside the sandbox.
A fake path must not be the destination of a bind with a source on the host.
Fake paths are mounted read-only by default. To change it, specify different mode via filesystem.bind.
PATH = "contents"
pre, post
executable, entrypoint, pre and post accept either a string or an array of strings. Both forms behave the same and array form is recommended, because it it gives full control over arguments splitting. Shell quoting rules apply to the string form of commands.
A bind mount is given either as a string or as a mapping:
{src = "LOCAL_SOURCE", dst = "SANDBOX_DESTINATION", opt = "OPTION"}
Options:
SANDBOX_DESTINATION defaults to LOCAL_SOURCE (meaning that by default sand will bind-mount directories inside the sandbox under the same paths as they are on the host).
OPTIONS:
ro
rw
tmp
Bind mounts are applied in the order they appear: later ones mount over an earlier ones. To hide a subdirectory of a bind, list the parent bind first and the tmp bind after it:
A ro or rw bind whose source does not exist is skipped.
Relative sources are resolved against the directory in which sand is started.
Paths and commands support expansion of user home directory via ~/ and environment variables written as $var and ${var}. Only variables existing in the environment of main sand process are expanded. Missing variables are left unchanged.
base.toml:
[sand]
bootstrap = true
entrypoint = ["~/.local/bin/winch-adapter"]
chdir = "${PWD}"
nocwd = ["~", "/etc"]
[env]
HOME = true
DISPLAY = false
WAYLAND_DISPLAY = false
PATH = ${HOME}/.cargo/bin:${HOME}/.local/bin:/usr/bin:/bin
[filesystem]
bind = [
"${PWD}:rw",
"${HOME}/.cargo:rw",
"${HOME}/.cargo/bin:ro",
"~/.local",
"~/.rustup",
]
[filesystem.fakes]
"/etc/passwd" = "${USER}:x:${UID}:${GID}:User Name,,,:${HOME}:${SHELL}n"
bash.toml:
extends = ["base.toml"] [sand] executable = "bash" chdir = "/workspace" [filesystem] bind = ["/tmp/workspace:/workspace:rw"] [hooks] pre = ["mkdir", "-p", "/tmp/workspace"] post = ["rm", "-r", "-f", "/tmp/workspace"]
sand(1), bwrap(1), https://toml.io
Michal Goral <dev@goral.net.pl>
| 2026-11-17 | sand |