sand(1) General Commands Manual sand(1)

sand - run commands in a bwrap-based sandbox, configured with extensible TOML rules.

sand [-f] [-t template] [command [arguments]]

sand runs a command inside a sandbox created by bwrap(1). The sandbox is described by TOML template read from $XDG_CONFIG_HOME/sand, documented in sand(5).

-t template, --template=template

Name of the template, without the .toml suffix. Templates are only read from the configuration directory: $XDG_CONFIG_HOME/sand or ~/.config/sand if $XDG_CONFIG_HOME is missing.

-f, --force

Start the sandbox even if a security checks fail. See SECURITY.

-h, --help

Print usage and exit.

--version

Print the version and exit.

Hooks are commands that run on the host, outside of the sandbox. The following hooks are supported:

sand exports the following environment variables and, unless said otherwise, exposes them to the hooks and template expansions. They are not passed automatically to the sandbox, unless sand.bootstrap is set to true (see sand(5) [sand] section).

UID, GID

user id and group id of running user

HOSTNAME

hostname of the current system

SAND_PID

id of the main sand process

SAND_TEMPLATE_DIR

sand's configuration directory, from which templates are read

SAND_SANDBOX_RC

exit status of the sandbox, passed only to post hook

Templates, configuration directory and hooks are trusted and protected. Anyone who can write to the configuration directory can run arbitrary commands with the privileges of the user.

Before starting the sandbox, sand will perform the following checks and will refuse to start if any of them fails:

  • sand's configuration directory
  • sand's installation directory (including Python interpreter and its prefix,
defaulting to /usr/local)
  • bwrap executable
  • directories listed in PATH

This is discouraged, but security checks can be disabled with -f switch.

If the sandbox runs, sand exits with the status of the sandboxed command.

If the pre hook fails, sand exits with the status of the hook and the sandbox is not started. If the post hook fails while the sandboxed command succeeded, sand exits with the status of the post hook.

Other errors, like invalid command line usage, invalid templates, missing commands or failed security checks result with non-zero error status.

Run Bash inside the sandbox defined by the dev template:

sand -t dev bash

Run the default executable of the dev template:

sand -t dev

sand(5), bwrap(1)

Michal Goral <dev@goral.net.pl>

2026-11-17 sand