We have prepared a few examples to demonstrate how to use sandbox2 depending on your situation and how to write policies.

You can find them in //sandboxed_api/sandbox2/examples, read on for detailed explanations.


The CRC4 example is an intentionally buggy calculation of a CRC4 checksum, it demonstrates how to sandbox another program and how to communicate with it.

  • crc4bin.cc: is the program we want to sandbox (the sandboxee)
  • crc4sandbox.cc: is the sandbox program that will run it (the executor).

How it works:

  1. The executor starts the sandboxee from its file path using ::sandbox2::GetDataDependencyFilePath().
  2. The executor sends input to the sandboxee over the communication channel Comms using SendBytes().
  3. The sandboxee calculates the CRC4 and sends its replies back to the executor over the communication channel Comms which receives it with RecvUint32().

If the program makes any other syscall other than communicating (read() and write()), it is killed for policy violation.


The static example demonstrates how to sandbox a statically linked binary, such as a third-party binary for which you do not have the source, so is not aware that it will be sandboxed.

  • static_bin.cc: the sandboxee is a static C binary that converts ASCII text from standard input to uppercase.
  • static_sandbox.cc: the executor with its policy, limits and using a file descriptor for sandboxee input.

How it works:

  1. The executor starts the sandboxee from its file path using GetDataDependencyFilepath, just like for CRC4.
  2. It sets up limits, opens a file descriptor on /proc/version and marks it to be mapped in the sandboxee with MapFd.
  3. The policy allows some syscalls (open) to return an error (ENOENT), rather than being killed for policy violation. This can be useful when sandboxing a third party program where we cannot modify which syscalls are made, but we can make them fail gracefully.


The tool example is both a tool to develop your own policies and experiment with sandbox2 APIs as well a demonstration of its features.

  • sandbox2tool.cc: the executor demonstrating
    • how to run another binary sandboxed,
    • how to set up filesystem checks, and
    • how the executor can run the sandboxee asynchronously to read its output progressively

Try it yourself:


bazel run //sandboxed_api/sandbox2/examples/tool:sandbox2tool -- \
    --sandbox2tool_resolve_and_add_libraries \
    --sandbox2tool_additional_bind_mounts /etc \
    /bin/cat /etc/hostname

CMake + Ninja

cd build-dir
ninja sandbox2_sandbox2tool && \
    ./sandbox2_sandbox2tool \
    --sandbox2tool_resolve_and_add_libraries \
    --sandbox2tool_additional_bind_mounts /etc \
    /bin/cat /etc/hostname


  • --sandbox2tool_resolve_and_add_libraries to resolve and mount the required libraries for the sandboxee
  • --sandbox2tool_additional_bind_mounts <PATHS> to make additional directories available to the sandboxee
  • --sandbox2tool_keep_env to keep current environment variables
  • --sandbox2tool_redirect_fd1 to receive the sandboxee STDOUT_FILENO (1) and output it locally
  • --sandbox2tool_cpu_timeout to set CPU timeout in seconds
  • --sandbox2tool_walltime_timeout to set wall-time timeout in seconds
  • --sandbox2tool_file_size_creation_limit to set the maximum size of created files
  • --sandbox2tool_cwd to set sandbox current working directory


The custom_fork example demonstrates how to create a sandbox, which will initialize the binary, and then wait for fork() requests coming from the parent executor.

This mode offers potentially increased performance with regard to other types of sandboxing, as here, creating new instances of sandboxees doesn't require executing new binaries, just fork()-ing the existing ones

  • custom_fork_bin.cc: is the custom fork-server, receiving requests to fork() (via Client::WaitAndFork) in order to spawn new sandboxees
  • custom_fork_sandbox.cc: is the executor, which starts a custom fork server. Then it sends requests to it (via new executors) to spawn (via fork()) new sandboxees.


Network namespace, which is enabled by default, prevents the sandboxed process from connecting to the outside world. This example demonstrates how to deal with this problem.

A connection is initialized inside the executor and resulting socket is passed via ::sandbox2::Comms::SendFD(). The sandboxee receives the socket by using ::sandbox2::Comms::RecvFD() and then it can use this socket to exchange the data as usual.


There is another way to deal with a network namespace. Internally it works exactly the same as in above example, but is exposed as a more convenient API.

The sandboxee can establish network connection in 2 different ways:

  • automatic - installing an automatic handler and then issuing regular connect calls.
  • manual - obtaining a NetworkProxyClient and directly using NetworkProxyClient::Connect.

This example shows both methods. Automatic mode is used when a flag connect_with_handler is set, manual is used otherwise.