Appearance
xvm
Launch and inspect policy-managed Turbo sessions on macOS. xvm is the macOS launch helper used by Turbo Launcher; it is distinct from the Windows /xvm system image and the turbo vm command.
Usage
text
xvm [options] -- <executable> [args...]
xvm [options] --image <path>
xvm --daemon-health [--json] [--require-managed-networking-ready]
xvm --list-session-details [--json]
xvm containers [--json]
xvm stop <session-id>
xvm rm [--force] <session-id>Description
Turbo Launcher normally constructs the xvm invocation from the active policy and launch profile. Use the command directly for administration, validation, diagnostics, and controlled launch testing.
A direct launch connects to the Sandbox Service (the sandboxmanager daemon) only when you pass --sandbox. Network, clipboard, drag-drop, and instrumentation overrides require that managed connection; per-path isolation overrides also apply to a local launch. Policy-managed production launches should place stable filesystem and networking rules in policy; command-line overrides are best suited to diagnostics and explicit one-off tests.
Managed Boundary
Omitting --sandbox creates a local launch without the daemon-managed session boundary. Do not use that form when validating policy enforcement. Disabling Seatbelt confinement also weakens defense in depth and should be limited to documented compatibility testing.
Options
Policy, Images, and Launch
| Flag | Description | Notes |
|---|---|---|
--sandbox | Connect the launch to the Sandbox Service (the sandboxmanager daemon). | Required for a policy-managed session and the managed overrides described below. |
--profile <id> | Use a named launch profile from policy. | The profile must exist and authorize the executable. |
--session-id <id> | Adopt a live, pre-created managed session. | Requires --sandbox. |
--image <path> | Load a local Turbo .svm image layer. | Repeatable. |
--using <paths> | Add local .svm dependency layers. | Accepts comma- or semicolon-separated paths; image-name resolution is not currently available in xvm. |
--env <KEY=value> | Add or override an environment variable. | Repeatable. |
--mount <src>:<dst> | Expose a host path inside the session as read-write. | Also accepts [id:]<src>=<dst>. Prefer policy-defined mounts for stable deployments. |
--sandbox-root <path> | Override the sandbox root. | Intended for controlled testing. |
--cwd <path> | Set the launched process working directory. | --working-directory is an alias. Supports @SANDBOX_ROOT@ and @SANDBOX_HOME@. |
--transient | Use a session-local application profile. | The default profile persists per application. |
--dry-run | Print the resolved manifest without launching. | Useful for policy verification. |
Isolation and Data Motion
The clipboard, drag-drop, and --disable-seatbelt-confinement options require --sandbox. The per-path isolation options (--isolate, --isolation-default, --virtualize-preferences, --no-managed-keychain) and --container-color also apply to a local launch. Managed application-bundle launches isolate clipboard and drag-drop by default; the flags below override that posture for one launch.
| Flag | Description | Notes |
|---|---|---|
--isolate <path[=mode]> | Add a per-path isolation rule for the session home. | Modes: merge, writeCopy (default), or full; optional modifiers: +readOnly, +hidden, +noSync. Repeatable. |
--isolation-default <mode> | Set the isolation mode for paths not covered by a rule. | Use policy for stable application or agent-specific paths. |
--virtualize-preferences[=off] | Capture preference writes and isolate preference daemons. | Pass =off to force-disable the behavior for a compatibility test. |
--no-managed-keychain | Skip managed-keychain provisioning. | Intended for development or smoke tests that do not validate keychain isolation. |
--clipboard-direction <mode> | Set clipboard direction. | bidirectional, inbound-only, outbound-only, or isolated. |
--clipboard-mode <mode> | Set clipboard direction using PC-compatible values. | Bidirectional, InOnly, OutOnly, or Disabled. |
--clipboard-size <bytes> | Set the clipboard limit in both directions. | 0 is unlimited. Direction-specific flags override it. |
--clipboard-size-inbound <bytes> | Set the host-to-session clipboard limit. | 0 is unlimited. |
--clipboard-size-outbound <bytes> | Set the session-to-host clipboard limit. | 0 is unlimited. |
--clipboard-image-max-pixels <count> | Set the maximum clipboard image area. | 0 is unlimited. |
--isolate-drag-drop | Use a separate drag pasteboard realm. | --share-drag-drop applies the opposite override. |
--container-color <RRGGBB> | Draw a colored border around managed windows. | --skin-border-color is the PC-compatible alias and also accepts named colors. |
--disable-seatbelt-confinement | Skip the additional Turbo Seatbelt wrapper. | The daemon policy remains active; use only for a known compatibility requirement. |
Managed Networking
Managed-network overrides require --sandbox. Proxy launches fail closed: unmatched egress is denied, and a proxy failure does not fall back to a direct connection.
| Flag | Description | Notes |
|---|---|---|
--disable-network | Deny outbound network access for the launch. | |
--route-add <spec> | Add a direct route. | Supports protocol, host, CIDR, IP-range, and PC-compatible TCP/UDP forms. The TCP/UDP forms match protocol and port on macOS; they do not publish or remap host ports. |
--route-block <spec> | Add a deny route. | Repeatable. |
--proxy <url> | Proxy matching flows. | Schemes: http, https, socks5. |
--proxy-server <url[;url]> | PC-compatible proxy alias. | The first candidate is used. |
--proxy-targets <spec> | Select proxy destinations. | Semicolon-separated hosts, CIDRs, or IP ranges. |
--proxy-use-tls | Wrap a SOCKS5 proxy connection in TLS. | --proxy-tls is an alias. |
--proxy-tls-skip-verify | Disable proxy TLS certificate verification. | Use only on a trusted test network. |
Instrumentation and Diagnostics
| Flag | Description | Notes |
|---|---|---|
--instrument <list> | Enable instrumentation adapters. | Examples: node-electron, pty. Requires --sandbox. |
--interpose <list> | Enable concrete call interpositions. | Requires --sandbox. |
--interpose-rules <path> | Load compiled JSON interposition rules. | Requires --sandbox and --interpose. |
--diagnostic | Emit launch progress to stderr and set TURBO_DIAGNOSTIC=1. | --diag is an alias. |
--log-path <dir> | Write diagnostic output to xvm-<pid>.log. | The directory must already exist; exports TURBO_LOG_PATH. |
--help, -h | Show built-in command help. |
Daemon and Session Administration
These commands connect to sandboxmanager automatically and exit after returning the requested state or applying the operation.
| Command or Flag | Description | Notes |
|---|---|---|
--daemon-health, --status | Report daemon health. | Add --require-managed-networking-ready to exit nonzero unless managed networking is ready. |
--list-session-details | List active runtime session details. | Supports --json. |
containers, sessions | List durable managed sessions. | --containers and --sessions are aliases. Supports --json. |
stop <session-id> | Stop a durable session without deleting it. | |
rm [--force] <session-id> | Delete a durable session. | --force stops a running session first. |
--session-manifest <id> | Print a managed session manifest. | --manifest is an alias; supports --json. |
--purge-session <id> | Purge runtime state for a session. | |
--reset-session-storage <id> | Reset runtime and persistent session state. | --purge is a Windows-parity alias. |
--print-net-config | Print a managed-networking configuration template. | |
--validate-net-config <path> | Validate and normalize a managed-networking configuration file. | |
--json | Select machine-readable output. | Applies to standalone daemon commands. |
Examples
Verify Managed Runtime Readiness
bash
xvm --daemon-health --json --require-managed-networking-readyValidate a Policy-Managed Launch
bash
xvm --sandbox \
--profile <profile-id> \
--dry-run \
-- /usr/local/bin/example-agentThe named profile should own stable application-specific filesystem rules. For a one-off isolation test, use a generic path override rather than embedding a vendor path in a launcher script:
bash
xvm --sandbox \
--isolation-default writeCopy \
--isolate "Library/Application Support/ExampleAgent=full" \
-- /usr/local/bin/example-agentInspect and Stop Sessions
bash
xvm containers --json
xvm --session-manifest <session-id> --json
xvm stop <session-id>Output
Launches stream diagnostics to stderr only when --diagnostic is active. --dry-run prints the resolved session manifest. Standalone daemon commands emit human-readable text by default and machine-readable JSON when you pass --json.
Use process exit status as the readiness signal in automation. In particular, --daemon-health --require-managed-networking-ready exits nonzero when the daemon or required managed-networking components are not ready.
Related Commands
- Turbo Launcher on macOS — Deployment, activation, and readiness guidance.
- turbo vm — Inspect the Windows Turbo VM system image version.
- turbo vms — List Windows Turbo VM system image releases.
- turbo run — Launch Windows Turbo sessions from images.