Skip to main content

​
Basic Usage

The basic syntax for running sandboxec is: 
sandboxec [OPTIONS] [COMMAND [ARG...]]
The -- separator is optional but recommended when passing arguments to the wrapped command to avoid ambiguity with sandboxec’s own flags.

​
Command Structure

sandboxec wraps your target command and applies sandbox restrictions before execution:
  1. Parse CLI flags and configuration
  2. Load and merge configuration from files (if any)
  3. Apply Landlock restrictions based on rules
  4. Execute the target command with restrictions inherited by all child processes
  5. Return the exit code of the wrapped command
sandboxec --fs rx:/usr /usr/bin/echo hello

​
Passing Arguments

There are two ways to pass arguments to your wrapped command:

​
Without -- separator

sandboxec --fs rx:/usr /usr/bin/echo hello world
All arguments after the command path are passed to the wrapped command. 
sandboxec --fs rx:/usr -- /usr/bin/echo hello world
The -- explicitly marks the end of sandboxec options. Everything after -- is treated as the command and its arguments.
Use -- when your wrapped command accepts flags that might conflict with sandboxec’s flags, or when passing complex arguments.

​
Command-Line Flags

​
Core Options

​
-c, --config
string
Path to YAML configuration file. Can be a local path or HTTP(S) URL.
sandboxec --config ./sandboxec.yaml -- /bin/echo ok
sandboxec --config https://example.com/config.yaml -- /bin/echo ok
​
-C, --named-config
string
Named config profile from the sandboxec/profiles repository.
sandboxec --named-config agents/claude -- claude --dangerously-skip-permissions
​
-f, --fs
RIGHTS:PATH
Add filesystem rule. Can be specified multiple times. See Filesystem Rules for details.
sandboxec --fs rx:/usr --fs rw:/tmp -- your-command
​
-n, --net
RIGHTS:PORT
Add network rule. Can be specified multiple times. See Network Rules for details.
sandboxec --fs rx:/usr --net c:443 -- /usr/bin/curl https://example.com

​
Advanced Options

​
--abi
int
default:"0"
Force a specific Landlock ABI version (1-6). 0 means use the highest available version.
sandboxec --abi 4 --fs rx:/usr --net c:443 -- your-command
​
--best-effort
boolean
default:"false"
Continue even if the kernel lacks support for some features. Degrades gracefully instead of failing.
sandboxec --best-effort --net c:443 --fs rx:/usr -- your-command
​
--ignore-if-missing
boolean
default:"false"
Do not fail if a filesystem rule path does not exist.
sandboxec --ignore-if-missing --fs rx:/opt/tool -- your-command
​
--restrict-scoped
boolean
default:"false"
Enable scoped IPC restrictions. Requires Landlock ABI v6+.
sandboxec --restrict-scoped --fs rx:/usr -- your-command
​
--unsafe-host-runtime
boolean
default:"false"
Automatically add read_exec rights for host runtime paths and their shared library dependencies.
This weakens least-privilege guarantees and can significantly increase startup latency for short-lived commands.
sandboxec --unsafe-host-runtime --fs rw:$PWD -- your-build-command
​
-m, --mode
string
default:"run"
Execution mode: run or mcp.
  • run: Execute a single command (default)
  • mcp: Start as an MCP server
sandboxec --mode mcp --fs rx:/usr --fs rw:/tmp --net c:443
In mcp mode, no command arguments are accepted. The MCP server provides an exec tool for running commands.

​
Utility Flags

​
-V, --version
boolean
Show version information and exit.
sandboxec --version
​
-h, --help
boolean
Show help message and exit.
sandboxec --help

​
Exit Codes

sandboxec returns different exit codes based on execution results:
​
0
success
The wrapped command succeeded (exited with code 0).
​
N
forward
The wrapped command exited with code N. sandboxec forwards the exit code.
​
1
error
sandboxec itself failed (parsing error, configuration error, Landlock failure, missing command, etc.).

​
Examples

sandboxec --fs rx:/usr -- /usr/bin/id

​
MCP Mode

When running in MCP mode, sandboxec provides a Model Context Protocol server with an exec tool: 
sandboxec --mode mcp --fs rx:/usr --fs rw:/tmp --net c:443
The MCP server provides:
​
exec
tool
Execute a command and return stdout, stderr, and exit_code.Input parameters:
  • command (required): The command to execute
  • args (optional): Array of arguments
The command runs with the same sandbox policy specified via CLI flags or configuration.
See Examples for MCP client configuration.

Build docs developers (and LLMs) love

Get started for freeTalk to us