All invocation forms, flags, and exit codes — one page.
All Sandy flags must come before -x. Everything after -x <exe> is forwarded to the child as-is.
# Run from a TOML file sandy.exe -c <config.toml> [-l <log>] [-L] [-q] -x <exe> [args...] # Run from an inline TOML string sandy.exe -s "<toml>" [-l <log>] [-L] [-q] -x <exe> [args...] # Run from a saved profile sandy.exe -p <profile> [-l <log>] [-q] -x <exe> [args...]
-c, -s, and -p cannot be combined. If more than one is present, Sandy exits with code 128.
workdir is either set explicitly in config as an absolute directory path or inherited from Sandy's own current working directory. The target executable path does not change the default working directory.
Short and long forms are synonymous.
| Flag | Description |
|---|---|
| Config input | |
-c <path>, --config | Path to TOML config file |
-s <toml>, --string | Inline TOML config string — alternative to -c |
-p <name>, --profile | Run with a persistent saved profile — mutually exclusive with -c / -s |
| Execution | |
-x <path>, --exec | Executable to run sandboxed — consumes all remaining arguments and forwards them to the child |
| Logging & output | |
-l <path>, --log | Session log — captures operational events, config, and exit code |
-L, --log-stamp | Prepend YYYYMMDD_HHMMSS_uid_ to log filenames to prevent collisions on repeated runs |
-q, --quiet | Suppress the config banner printed to stderr on launch |
| Profiles | |
--create-profile <name> | Create a persistent sandbox profile — saves SID, ACLs, and config derived from -c |
--delete-profile <name> | Delete a saved profile and revoke its persistent ACLs |
--profile-info <name> | Print profile details: type, SID, config, and grants |
| Inspection & tooling | |
--dry-run, --check | Validate config and show planned ACL changes — no system modifications made |
--print-config | Print resolved config to stdout with all defaults filled in — requires -c or -s |
--print-container-toml | Print the default AppContainer TOML template to stdout |
--print-restricted-toml | Print the default Restricted Token TOML template to stdout |
--status [--json] | Show instances, retry containers, cleanup tasks, saved profiles, and summary counts — optionally as JSON |
--cleanup | Restore stale state left by a crashed run — removes orphaned ACLs, loopback exemptions, scheduled tasks, and transient AppContainer profiles |
--explain <code> | Decode a numeric exit code — distinguishes Sandy codes (125–131), NTSTATUS, and Win32 error codes |
| Info | |
-v, --version | Print version and exit |
-h, --help | Print full help text with config reference |
Sandy follows the POSIX high-code convention used by bash, env, timeout, and git bisect. Child exit codes 0–124 pass through unchanged with zero ambiguity.
| Code | Origin | Meaning |
|---|---|---|
| 0 | Child / Sandy | Success — child exited cleanly, or info command succeeded |
| 1–124 | Child | Child's own exit code, passed through unchanged |
| 125 | Sandy | Internal / general error |
| 126 | Sandy | Cannot execute — CreateProcess failed (permission denied, bad format) |
| 127 | Sandy | Command not found — executable does not exist on disk |
| 128 | Sandy | Configuration error — invalid TOML, wrong-mode key, config file not found |
| 129 | Sandy | Sandbox setup failed — token / SID creation, ACL grants, or stdin setup |
| 130 | Sandy | Timeout — child killed by Sandy's watchdog |
| 131 | Sandy | Child crashed — NTSTATUS crash code detected (e.g. 0xC0000005 access violation) |
In scripts, check exit code >= 125 to detect Sandy-level failures. Codes 130 and 131 mean the child ran but terminated abnormally — use sandy.exe --explain <code> to decode any code, including raw NTSTATUS and Win32 error values.