Create lightweight sandboxes for Linux with host isolation, rootfs images, and networking.

• Sandbox Isolation - Networking, file-system, processes, and user isolation from the host using Linux namespaces.
• Filesystem Images - Uses an Overlay FS to mount a custom root file-system from a user image. Also supports minimal tmpfs dedicated to bind-mounting.
• Networking - Provides full network isolation by default. bridge and host modes available.
• Bind-mounts - Selective read-only/read-write bind-mounting of host directories into the sandbox.
• Security Features - Seccomp filtering for syscall restrictions and Linux capability management support.
• Resource Limits - Enforce CPU and Memory constraints using CGroups.

Microbox is a sandbox runtime that creates ephemeral and isolated execution environments on Linux by combining specific kernel features such as namespaces, cgroups, seccomp, and capabilities. It provides lightweight sandboxes to run container-like applications securely.

Namespacing in microbox provide process, network, filesystem, IPC, and user isolation, while cgroups provide resource limitation management, and can run with different filesystem modes, from completely isolated overlay root filesystems, to controlled access to host directories.

Microbox is built out of an educational purpose to understand how secure non VM based sandboxes can be on Linux. Its philosophy is to provide maximum isolation by default, unlike other container runtimes such as runc, or Podman which enforce a good balance between security and usability of applications.

You can run a simple rootfs image in an isolated sandbox in a couple minutes. First, follow the instructions in the Creating a Root Filesystem section to create a Ubuntu rootfs image on your host.

Feel free to adapt the architecture and packages as needed in your image as needed.

Download the latest release from the Releases page.

Run microbox to create an isolated sandbox using the rootfs image you just created. This will run an isolated sandbox with no network access, using the new rootfs image.

./microbox --fs <rootfs> -- /bin/bash -c "echo Hello Sandbox!"

The sandbox exposes a file-system that is ephemeral, isolated from the host—unless otherwise specified—and mounted in memory. As such, changes caused by applications within the sandbox's rootfs don't reflect on the host filesystem.

Below is a comparison table of the supported file-system options.

Using a custom rootfs image provides a complete environment with binaries and libraries in the sandbox. You can create your own rootfs image using the instructions in the Creating a Root Filesystem section.

microbox --fs ./ubuntu-24.04 -- /bin/ls

The default storage size is set to 512MB in the sandbox. Using the --storage option, you can control the size of the writable layer.

microbox --storage 2GB -- /bin/ls

This is the default, but you can make it explicit by specifying --fs tmpfs. In this mode, the sandbox exposes an empty rootfs with only devfs and procfs mounted.

In this example, we bind-mount /bin and lib from the host to provide a minimal environment.

microbox \
  --mount-ro /bin:/bin \
  --mount-ro /lib:/lib \
  -- /bin/ls

You can bind mount host directories into the sandbox using the --mount-ro and --mount-rw options.

Note that writes made by the sandbox to writable bind mounts will affect the host filesystem.

./microbox \
  --mount-ro /etc:/etc \
  --mount-rw /tmp:/tmp \
  -- /bin/bash

The default network mode is none, which means no network access. You can change this behavior using the --net option.

No networking in sandboxes is the default, you can make it explicit by specifying --net none.

$ microbox --fs <rootfs> -- /bin/curl google.com
curl: (6) Could not resolve host: google.com

In bridge mode, the sandbox gets its own network interface and IP address. It uses veth pairs and NAT to provide network access between the host and the sandbox.

$ microbox --fs <rootfs> --net bridge \
-- curl https://api.ipify.org/
1.2.3.4

Host networking does not provide any network isolation with the host. The sandbox shares the host network interface and network stack.

$ microbox --fs <rootfs> --net host \
-- /bin/curl https://api.ipify.org/
1.2.3.4

You can limit the number of CPU cores available to the sandbox using the --cpus option.

./microbox --cpus 1 -- /bin/bash

You can limit the amount of memory available to the sandbox using the --memory option.

./microbox --memory 256M -- /bin/bash

You can chain environment variables in the sandbox using the --env option.

./microbox --env MY_VAR=hello -- /bin/bash -c 'echo $MY_VAR'

You can restrict the syscalls available to the sandbox using the --allow-syscall and --deny-syscall options.

See the Default Seccomp Profile section for more details on syscalls denied by default.

./microbox \
  --fs ./rootfs \
  --allow-syscall unshare \
  --allow-syscall setns \
  -- /bin/bash

You can add or drop Linux capabilities in the sandbox using the --cap-add and --cap-drop options.

./microbox \
  --fs ./rootfs \
  --cap-drop CAP_SETPCAP \
  -- /bin/bash

You can set custom DNS servers for the sandbox using the --dns option.

By default, microbox uses Google DNS Servers for the sandbox.

./microbox \
  --fs ./rootfs \
  --dns 1.1.1.1 \
  --dns 8.8.8.8 \
  -- /bin/bash

You can set a custom hostname for the sandbox using the --hostname option.

$ ./microbox \
  --fs ./rootfs \
  --hostname my-sandbox \
  -- /bin/bash -c 'hostname'
my-sandbox

You can mount the root filesystem as read-only using the --readonly option to disable any writes to the rootfs.

./microbox \
  --fs <rootfs> \
  --readonly \
  -- /bin/bash

By default, the sandbox runs in a new user namespace, mapping the root user in the sandbox to a user on the host. This can break the normal operations of some applications. You can disable this behavior using the --userns host option.

This is recommended for working with applications such as apt which attempt to change the effective user ID at runtime.

./microbox \
  --fs <rootfs> \
  --userns host \
  -- /bin/bash

You can control the log level and format using the --log-level and --log-format options.

./microbox \
  --fs ./rootfs \
  --log-level info \
  --log-format json \
  -- /bin/bash

Below is a description of the isolation features provided by microbox by default.

• --fs MODE|DIR - Filesystem mode: host (uses host filesystem), tmpfs (temporary filesystem), or a path to use a directory as the rootfs
• --net MODE - Network mode: none (no network), host (use host network), bridge (bridged network with NAT)
• --mount-ro HOST:DEST - Create read-only bind mount from host path to sandbox destination
• --mount-rw HOST:DEST - Create read-write bind mount from host path to sandbox destination
• --readonly - Mount the root filesystem as read-only
• --env KEY=VALUE - Set environment variable in the sandbox
• --allow-syscall SYSCALL - Allow specific system calls in the sandbox using seccomp
• --deny-syscall SYSCALL - Deny specific system calls in the sandbox using seccomp
• --dns SERVER - Set custom DNS server for the sandbox
• --hostname NAME - Set custom hostname for the sandbox
• --cpus N - Set CPU limit (e.g., 0.5 for half a core, 2 for two cores)
• --memory SIZE - Set memory limit (e.g., 10MB, 2GB)
• --storage SIZE - Set storage limit for the sandbox filesystem (e.g., 1GB, 10GB)
• --log-level LEVEL - Set log level between info, warn, error (default: error)
• --log-format FORMAT - Set log format: text or json (default: json)
• --cap-add CAPABILITY - Add a Linux capability to the sandbox (e.g., CAP_NET_ADMIN)
• --cap-drop CAPABILITY - Drop a specific Linux capability from the sandbox (e.g., CAP_SYS_TIME)
• --help - Display help message

• Rootless Unsupported - Sandbox creation currently requires root privileges to create namespaces, cgroups and a network bridge.
• OCI Support - Not a full container runtime replacement, no OCI image support, focused on process isolation.
• No AppArmor/SELinux - Does not currently support AppArmor or SELinux profiles for additional security layers.

• Linux Namespaces - Kernel documentation on namespaces
• Seccomp - System call filtering
• Cgroups - Resource control groups
• OverlayFS - Union filesystem for layering filesystems
• runc - Container runtime