macOS sandboxing

The itch.io app uses macOS's built-in sandbox-exec facility to sandbox games. Each time a game launches, the app dynamically generates a sandbox policy written in Apple's Sandbox Profile Language (SBPL) and stores it at {install_folder}/.itch/isolate-app.sb.

The policy starts from a deny-all default and explicitly allows only the permissions a game needs to run.

Here's the policy template the itch app uses:

• https://github.com/itchio/smaug/blob/master/runner/policies/sandboxexec.go

How it works

When a game launches with the sandbox enabled:

1. The app generates an SBPL policy file tailored to the game's install location
2. The environment is filtered to an allowlist of safe variables (HOME, USER, PATH, locale settings, TMPDIR, and itch.io launch variables)
3. The game is launched through sandbox-exec -f {policy_file}

For app bundles (.app directories), the app creates a temporary shim bundle that wraps the original binary with a shell script invoking sandbox-exec. This allows app bundles to launch through the standard macOS app mechanism while still being sandboxed.

For standalone executables, sandbox-exec is invoked directly.

What the sandbox allows

Filesystem write access

• ~/Library subpaths: Application Support, Preferences, Logs, Caches, KeyBindings, Saved Application State, and RenPy
• The game's own install folder (full read-write)
• /var/folders and /private/var/folders (macOS temp storage)
• /dev/null, /dev/random, and /dev/urandom

Filesystem read access

• System libraries and binaries: /usr/local, /usr/share, /usr/lib, /usr/bin, /bin, /System/Library
• Rosetta 2 translation support: /usr/libexec/rosetta, /Library/Apple/usr/libexec/oah (for running x86_64 games on Apple Silicon)
• Java: /Library/Java/JavaVirtualMachines
• System preferences: /etc, /private/etc, /Library/Preferences
• Fonts and audio: /Library/Audio, /Library/Fonts, ~/Library/Fonts
• Input methods and keyboard layouts: ~/Library/Keyboard Layouts, ~/Library/Input Methods
• /Applications (read-only)

Explicitly denied

Even though ~/Library/Application Support is writable, the following subpaths are explicitly blocked to prevent credential theft:

• ~/Library/Application Support/itch and ~/Library/Application Support/kitch (itch.io app config)
• ~/Library/Application Support/Google (Chrome data)
• ~/Library/Application Support/Mozilla (Firefox data)

Network

Network access (network-bind and network-outbound) is allowed.

IPC and system access

The following are allowed for compatibility with game frameworks like SDL2 and Electron:

• Mach IPC (mach-lookup, mach-register)
• POSIX shared memory (ipc-posix*)
• System sockets (system-socket)
• IOKit device access (iokit-open)
• Process forking and execution (process-fork, process-exec)
• Hardware/OS limit probing (sysctl-read)

Settings

The sandbox can be configured from the itch.io app:

• Enable itch.io sandbox — Master toggle in the app's preferences
• Sandbox — Per-game override under Manage → Launch settings

Games can detect that they are running inside the sandbox by checking for the ITCHIO_SANDBOX=1 environment variable.

Troubleshooting

If a game is broken by the sandbox:

1. Check Console.app. Open the built-in Console.app and look for sandbox denial messages. Shutting down other applications can help reduce noise in the logs.

2. Inspect the policy. Open {install_folder}/.itch/isolate-app.sb to see the exact SBPL policy being applied to the game.

3. Try disabling the sandbox for that game. Open Manage → Launch settings and disable the sandbox to confirm whether it is causing the problem.

4. Report the issue. If you can't resolve the problem, open an issue on our issue tracker with the Console.app output and the contents of the .sb file.