CLI Reference
Every subcommand and flag of the sandlock binary. Flags are grouped by the policy area they affect, which is the same grouping the TOML profile schema and the SDKs use.
Subcommands
| Command | Purpose |
|---|---|
sandlock run | Run a command in a sandbox |
sandlock check | Report the host kernel's Landlock support |
sandlock ps | List running sandboxes with uptime and command |
sandlock inspect <name> | Print a running sandbox's effective policy as JSON, or TOML with --toml |
sandlock kill <name> | Kill a running sandbox by name |
sandlock profile | list, show <name>, or delete <name> |
sandlock learn | Observe a workload and emit a profile of what it used |
sandlock run
Synopsis
sandlock run [flags] -- <cmd> [args...]Everything after -- is the command. When a profile supplies [program].exec, the command may be omitted; a trailing command overrides the profile's.
Filesystem
| Flag | Description |
|---|---|
-r, --fs-read <PATH> | Grant read access. Recursive, repeatable. |
-w, --fs-write <PATH> | Grant read and write access. Recursive, repeatable. |
--fs-deny <PATH> | Deny a path even where a broader rule allows it. |
--chroot <PATH> | chroot into this directory before applying the rest of the confinement. |
--fs-mount <VIRTUAL:HOST[:ro]> | Map a host path inside the chroot. Append :ro for read-only; :rw is the default. |
--image <IMAGE> | Use a local Docker image as the chroot rootfs. The image must already exist locally; sandlock never pulls from a registry. |
--workdir <PATH> | COW root directory. Controls which tree COW tracks; does not set the child's working directory. |
--cwd <PATH> | Child working directory. |
--fs-storage <PATH> | Where the COW upper layer and deltas live. |
--on-exit <ACTION> | COW branch action on normal exit: commit (default), abort, keep. |
--on-error <ACTION> | COW branch action on error: abort (default), commit, keep. |
--dry-run | Run the command, report the filesystem changes it would make, then discard them. |
Network
| Flag | Description |
|---|---|
--net-allow <SPEC> | Outbound allowlist rule. Repeatable. Mutually exclusive with --net-deny. |
--net-deny <SPEC> | Outbound denylist rule; targets must be literal IPs or CIDRs. Repeatable. |
--net-allow-bind <PORTS> | TCP ports the sandbox may bind. Comma-separated ports or lo-hi ranges; * allows any. |
--net-deny-bind <PORTS> | TCP ports the sandbox may not bind. Mutually exclusive with --net-allow-bind. |
--port-remap | Give the sandbox its own virtual TCP port space. |
The rule grammar, protocol gating, and DNS behaviour are covered in the network model.
HTTP and credentials
| Flag | Description |
|---|---|
--http-allow <RULE> | Allow rule, "METHOD host/path". Repeatable. |
--http-deny <RULE> | Deny rule, checked before allow rules. Repeatable. |
--http-port <PORT> | TCP port to intercept. Defaults to 80; 443 is added when a CA is configured. |
--http-ca <PATH> | PEM CA certificate for HTTPS interception. |
--http-key <PATH> | PEM CA private key. Required with --http-ca. |
--http-inject-ca <PATH> | Splice the active CA's public cert into this trust bundle at open time. Without --http-ca, generates an ephemeral CA. Repeatable. |
--http-ca-out <PATH> | Write the active CA's public certificate here. Never the private key. |
--credential <NAME=SOURCE> | Load a secret into the supervisor. Source is env:VAR, file:PATH, or fd:N. |
--http-auth <RULE> | Attach a loaded credential: "METHOD HOST/PATH AUTHSPEC NAME [replace|add-only]". |
See HTTP ACL and credential injection for the rule syntax and the auth specs.
Resource limits
Covered in depth on Resource Limits.
| Flag | Description |
|---|---|
-m, --max-memory <SIZE> | Memory limit, for example 512M or 1G. |
-P, --max-processes <N> | Maximum concurrent processes. Defaults to 64. Threads do not count. |
--max-open-files <N> | Maximum open descriptors, enforced with RLIMIT_NOFILE. |
-c, --cpu <PERCENT> | CPU throttle as a percentage of one core, 1 to 100. |
--max-disk <SIZE> | COW storage quota. Exceeding it returns ENOSPC. |
--cpu-cores <N,N,...> | Pin the sandbox to these cores with sched_setaffinity. |
--num-cpus <N> | Visible CPU count in /proc/cpuinfo, renumbered from 0. |
--gpu <all|N,N,...> | GPUs the sandbox may open. A hard Landlock boundary, not an environment hint. |
-t, --timeout <SECS> | Kill the sandbox after this many seconds. |
Process and environment
| Flag | Description |
|---|---|
--env <KEY=VALUE> | Set or override an environment variable. Applied after --clean-env. Repeatable. |
--clean-env | Start from a minimal environment (PATH, HOME, USER, TERM, LANG) rather than inheriting. |
--user <UID:GID> | Map the child to this uid and gid inside a user namespace. Both or neither. |
--name <NAME> | Sandbox name and virtual hostname. Auto-generated when omitted. |
-i, --interactive | Inherit the terminal instead of capturing stdout and stderr. |
-e, --exec-shell <CMD> | Run a command string through a shell. |
--no-coredump | prctl(PR_SET_DUMPABLE, 0). Also restricts other processes' access to /proc/<pid>. Breaks gdb, strace, and perf. |
--no-huge-pages | Disable transparent huge pages for the child. |
--status-fd <FD> | Report sandbox status on this descriptor. |
Syscalls and protections
| Flag | Description |
|---|---|
--extra-deny-syscall <NAME|GROUP> | Block additional syscalls or groups on top of the default blocklist. |
--extra-allow-syscall <GROUP> | Re-allow a named group such as sysv_ipc. Individual syscall names are rejected. |
--no-supervisor | Landlock plus a deny-only seccomp filter, with no supervisor process. Required when nesting. |
--allow-degraded <PROTECTION> | Enforce a protection where the kernel supports it, skip it where it does not. Repeatable. |
--disable <PROTECTION> | Never enforce a protection. Repeatable. |
Protection names are fs-refer, fs-truncate, net-tcp, fs-ioctl-dev, signal-scope, and abstract-unix-socket-scope. --disable fs-refer is rejected: the kernel denies REFER by default when the rule is unhandled, so disabling it would only tighten the sandbox and the flag would be misleading.
Determinism
Covered in depth on Determinism.
| Flag | Description |
|---|---|
--random-seed <N> | Seed deterministic getrandom(). Identical seeds produce identical byte streams. |
--time-start <TIME> | Frozen start time as a Unix timestamp or an RFC 3339 string. Time then advances at real speed. |
--deterministic-dirs | Sort readdir() entries lexicographically. |
--no-randomize-memory | Disable ASLR via personality(ADDR_NO_RANDOMIZE). |
Profiles
| Flag | Description |
|---|---|
-p, --profile <NAME> | Load a profile from ~/.config/sandlock/profiles/. |
--profile-file <PATH> | Load a profile from an arbitrary path. Conflicts with -p. |
Examples
Common invocations
# Basic confinement
$ sandlock run -r /usr -r /lib -w /tmp -- ls /tmp
# Interactive shell
$ sandlock run -i -r /usr -r /lib -r /lib64 -r /bin -r /etc -w /tmp -- /bin/sh
# Resource limits plus a timeout
$ sandlock run -m 512M -P 20 -t 30 -- ./compute.sh
# GPU: only the chosen device nodes are openable
$ sandlock run --gpu 0 \
-r /usr -r /lib -r /lib64 -r /etc -r /sys -r /proc -w /proc/self/task \
-- python3 train.py
# Clean environment with one variable set
$ sandlock run --clean-env --env CC=gcc -r /usr -r /lib -w /tmp -- make
# Chroot with a per-sandbox mount, no root and no bind mount
$ sandlock run --chroot ./rootfs --fs-mount /work:/tmp/sandbox/work -- /bin/sh
# A local Docker image as the rootfs
$ sandlock run --image python:3.12-slim -- python3 -c 'print(1)'
# Nested: confine sandlock's own supervisor
$ sandlock run --no-supervisor \
-r /proc -r /usr -r /lib -r /lib64 -r /bin -r /etc -w /tmp -- \
sandlock run -r /usr -w /tmp -- untrusted-commandManaging running sandboxes
ps, inspect, kill
$ sandlock ps
NAME PID UPTIME CMD
api.local 12345 5m python3 server.py
web.local 12346 3m python3 server.py
$ sandlock inspect api.local --toml | head -10
[config]
http_inject_ca = []
[determinism]
...
$ sandlock kill web.local
Killed sandbox 'web.local' (PID 12346)Sandboxes appear here only when their control socket is enabled, which is the default. A sandbox built with the control socket disabled creates no runtime directory, pid file, or socket, and is invisible to both commands.
sandlock check
Reports the running kernel's Landlock ABI and each protection's availability. Run it on a new host before deploying, since Sandlock's strict default refuses to start when a protection it expects is missing.
Check the host
$ sandlock checksandlock learn
Runs a workload under observation and emits a TOML profile of the paths, connections, and resource peaks it actually used. Covered in full on Profiles and learn.
Generate a profile from a real run
$ sandlock learn --collapse -o profile.toml -- python3 build.py
$ sandlock run -p profile.toml -- python3 build.py