Windows sandbox

Since v0.7.4, Zagens applies OS-level process isolation for exec_shell on Windows (restricted token + ACL + WFP firewall) instead of running commands with your full user privileges.

Policy vs enforcement: Execution policy sandbox_mode states what the agent intends (e.g. workspace-only writes). The Windows sandbox decides whether the OS actually enforces it. Use both together.

Where to configure

Surface	What
Sidebar Sandbox	First-run wizard, Windows mode, private desktop, configured vs effective status
Settings → System → Security	Global `sandbox_mode`, shell toggle, approval policy
`~/.zagens/config.toml`	`[windows] sandbox`, `sandbox_initialized`, …

First launch (Agent mode): until initialized, the Sandbox panel shows only the wizard — pick Elevated sandbox (recommended) or Unelevated sandbox, then the full panel unlocks.

Two Windows modes

Mode	Best for	Summary
Elevated (recommended)	Daily dev, profile read isolation	No writes outside workspace; blocks reads of `.ssh` and similar; default WFP blocks outbound (loopback allowed); background shell + ConPTY interactive terminal; first provisioning needs UAC / admin
Unelevated	Quick try, no admin rights	Workspace write isolation + best-effort network limits; no profile read isolation (documented honestly)

When [windows] sandbox is unset: after setup → default elevated; before setup → unelevated with warning.

Relation to `sandbox_mode`

`sandbox_mode`	File intent	Windows elevated adds
`workspace-write` (default)	R/W inside workspace	No writes outside workspace
`read-only`	No file writes	Same + policy-level read-only
`danger-full-access`	Broader writes (sparingly)	Still bounded by OS sandbox (not fully unrestricted)

When a tool requests network (network_access: true), the elevated path uses an online sandbox user with unrestricted outbound — see Network policy.

First-run wizard

Open Sandbox in the sidebar.
Initialize default sandbox (recommended) — elevated provisioning (offline/online sandbox users, WFP rules, …); triggers UAC.
Or Use unelevated sandbox — no admin; see table above.
After init: Auto / Elevated / Unelevated, private desktop (sandbox_private_desktop).

The panel shows configured vs effective backend. Elevated without completed setup prompts you to run zagens sandbox setup.

CLI (advanced)

Where the zagens CLI is installed (shared runtime with desktop):

zagens sandbox setup      # one-time elevated provisioning (admin)
zagens sandbox teardown   # remove sandbox artifacts
zagens sandbox add-read-dir <path>   # session-scoped read grant (elevated)

Other platforms

Platform	Status
macOS	Seatbelt (`sandbox-exec`) process isolation
Linux	Policy declared; OS enforcement degraded (env marker + log warning)
OpenSandbox	Optional external container backend — see Execution policy

Troubleshooting

Symptom	Action
Panel says setup required	Run `zagens sandbox setup` or redo the wizard
Configured Elevated, effective Unelevated	Setup incomplete or UAC denied; check status badge
Shell result `sandbox_enforced: false`	Read stderr warning; expected on degraded Linux
Worried about full-machine access	Use elevated + `workspace-write` + Tool approval

Honest limits

Unelevated does not isolate profile reads (e.g. .ssh).
Elevated offline network block may still leak DNS resolution side channels.
Online user with network has no host allowlist on outbound (separate from file sandbox).