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

Array of base template paths. Relative paths are resolved against the directory of current template. Every base must resolve to a file inside the configuration directory.

Bases are merged in the listed order: a later base overrides an earlier one, and the template itself overrides all of its bases.

bwrap

Path to the bwrap executable. Default: /usr/bin/bwrap.

bootstrap

Boolean. Default: false.

When enabled, sand:

  • binds common system paths in read-only mode
  • mounts a tmpfs on /tmp, and provides /dev and /proc;
  • sets default PATH, PS1, and XDG_RUNTIME_DIR;
  • forwards USER, HOME, LOGNAME, DISPLAY, WAYLAND_DISPLAY, XDG_SESSION_TYPE, XDG_CURRENT_DESKTOP, UID, TERM, HOSTNAME, LANGUAGE, LANG, LC_TYPE, TZ, COLORTERM and LS_COLORS environment variables from the host.

Values from the [env] section are applied after bootstrap and override it.

chdir

Directory inside the sandbox in which the command starts.

executable

Default command to run inside the sandbox, sand invocation doesn't specify one. It is passed as arguments to the entrypoint, if one is set. See COMMANDS.

entrypoint

Command wrapper to run inside the sandbox. When set, either executable or command from sand invocation are passed to it as its last arguments.

network

Boolean, default false. When false, the sandbox has its own network namespace. When true, the host network namespace is shared.

userns

Boolean, default false. When set to true, creating user namespaces inside the sandbox will be allowed.

nocwd

Array of host paths. sand will prevent starting of sandbox when current directory equal to, or a parent of, any of these paths. See sand(1), SECURITY section.

Environment variables passed to the sandbox. Sand passes no environment variables except these and the ones set by bootstrap.

NAME = "value"

Sets the variable to the expanded value.

NAME = true

Forwards the variable from the host environment, if it is set.

NAME = false

Removes the variable, for example one set by bootstrap.

bind

Array of bind mounts. See BIND MOUNTS.

dirs

Array of directories created inside the sandbox.

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

Commands that run on the host, outside the sandbox, before and after the sandbox. Commands are searched in $PATH. Relative paths are resolved against the directory of template which defined the hooks. See sand(1), HOOKS section.

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:

"LOCAL_SOURCE[:SANDBOX_DESTINATION][:OPTION]"

{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

Read-only bind mount (default)

rw

Writable bind mount.

tmp

Empty tmpfs mounted on SANDBOX_DESTINATION. In case of tmp bind-mounts, LOCAL_SOURCE is not used (specifying it is an error).

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:

bind = ["~", "~/.ssh:tmp"]

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