In this section
Design / platform boundary

macOS backend

Apple silicon can run the reduced macos-explicit backend from source. The daemonless fallback is now proxychains-style interposition plus child-only runtime adapters. The Network Extension prototype is deferred, and official macOS packages are not available.

One CLI, no always-on service

The heimdall CLI is the only process a user starts. The explicit backend owns one kernel-assigned loopback listener and one private JSONL run store, then closes both with the foreground command. It starts no daemon, helper, Web UI, app, or system extension and never changes system proxy settings. No persistent user-managed Heimdall daemon is installed or required.

Native explicit acceptance passed. On Apple silicon, just test-macos-native routes curl through the loopback SOCKS5 CONNECT frontend, the shared relay_transport, and a fixture upstream; it verifies hostname preservation, policy and flow evidence, listener cleanup, exit propagation, and pre-exec refusal. This is source-backend evidence, not official package or transparent acceptance.

Package mechanics passed; publication has not. The native gate now covers arm64 Mach-O hygiene, macOS 11 deployment, normalized archive metadata, SHA-256, install, simulated upgrade, rollback, and uninstall. Its test artifact is ad-hoc signed and cannot be published. The official builder separately requires Developer ID, Hardened Runtime, timestamp, warning-free notarization, and Gatekeeper assessment.

Interpose is research, not support. just test-macos-interpose-feasibility proves an ordinary dynamic fixture loads an injected library while Hardened Runtime and SIP-protected targets do not. No socket hook or selectable backend exists yet.

Network Extension is deferred. The fail-closed NETransparentProxyProvider app/system-extension skeleton and heimdall.macos.control/v1 remain in source, but package and release construction do not build or include them. heimdall agent reports status="deferred" and release_included=false.

Explicit quick start

heimdall agent --policy default

# Use actions.execute_prefix from that JSON. Its shape is:
heimdall --config /path/to/config.toml run \
  --backend macos-explicit --policy default -- \
  curl https://example.com

Readiness requires Apple silicon, system DNS, rejected UDP, capture off, decrypt off, and readable outbound credentials. The child receives only ALL_PROXY and all_proxy with a socks5h://127.0.0.1:<port> URL. A client can ignore those variables, so this mode is cooperative rather than transparent or fail closed.

Three paths with different claims

BackendStatusBoundary
macos-explicitAvailable from source on Apple silicon; first signed/notarized release asset pending.Cooperative TCP route/direct/reject and metadata only; no strict scope, UDP, fake DNS, capture, TLS inspection, QUIC, or fail-closed claim.
macos-interposeIn development and unselectable.Compatible dynamically linked socket/resolver calls only. SIP, Hardened Runtime, static code, alternate APIs, direct syscalls, and unproven descendants are outside the claim.
macos-transparentDeferred source research; excluded from releases.Optional entitled companion design. No installation, activation, routing, process-group, TCP/UDP, or attribution support.

Explicit policy and flow records use source={backend:"macos-explicit", scope:"cooperative_environment"}. That proves the client reached the listener, not operating-system process attribution. A normal run intentionally records incomplete descendant cleanup because the environment cannot prove the entire process tree used it.

What the research says

Heimdall never asks a user to disable SIP, weaken signing, install Proxyman, change the system proxy, or mutate the system keychain. Read the sourced fallback decision →

Planned interpose path

heimdall run --backend macos-interpose -- command
  → preflight target and policy
  → inject signed interposition library
  → constructor authenticates to foreground relay
  → connect / resolver calls use route, direct, or reject
  → JSONL and relay close with the foreground run

The first milestone is TCP plus libc resolver calls. The library rejects a hooked call when its relay is gone, and the CLI refuses known incompatible targets before exec. Because no operating-system boundary prevents every possible bypass, capability output will keep scope=interposed_dynamic_calls, strict_command_scope=false, and client_can_bypass=true unless native negative evidence proves a stronger bounded contract. UDP, QUIC, fake DNS, capture, and TLS remain unavailable.

Relay TLS may be explored later through optional, child-only trust adapters for individually tested runtimes. Interposition does not itself inspect TLS, and pinning or client-certificate mTLS remains unsupported.

Retained Network Extension source

just test-macos-companion-native remains an explicitly invoked source gate for the unsigned app/system-extension shape and Swift codec. It is not called by the release builder. The app never submits activation, no Network Extension configuration exists, provider startup fails, and unexpected flows are closed. Nothing is signed, installed, approved, activated, or routed.

If a future roadmap decision reactivates this path, sourceAppAuditToken remains optional and native evidence must distinguish attributed, unrelated, missing, and ambiguous flows. NEAppProxyProvider remains only a possible managed per-app option. Neither API is currently a process group support claim.

Native release gate

The explicit source and package-mechanics gates are complete. An official claim still requires a versioned Developer ID-signed/notarized asset and fresh-download signature, Gatekeeper, install, upgrade, rollback, uninstall, and explicit-run acceptance. Until then, published GitHub, npm, PyPI, and Cargo versions remain Linux-only even though the next Cargo source package is prepared to compile the reduced backend.

The package contains only the CLI. Interpose needs native TCP/DNS, loader, spawn/exec, bypass, relay-loss, cleanup, signing, and archive tests before it can join. The deferred companion needs a separate future roadmap decision plus the complete entitlement, approval, attribution, coexistence, transport, and cleanup matrix before any release work resumes.