As of November 2026: In CardinalHost (documented pre-launch on cardinalhost.org), the Mac — from desktops to a MacBook — serves two roles: native Swift/SwiftUI operator client (ServerMountApp) for remote Linux and macOS hosts, and assisted target governed by pubblico-macos.sh. Here we document both implemented macOS foundations, including the 3-state TCC machine, and our in-progress research on lossless tile compression (Tela and zstd), wireless packet pacing, and file transfer between Mac and servers.
Two Roles on the Mac: Operator Client and Assisted Target Machine
Across the Cardinal product family — alongside CardinalMail and CardinalOS — CardinalHost interfaces directly with each operating system’s native security and media frameworks instead of embedding a browser runtime. As outlined in our CardinalHost applied research overview, communicating with a Mac involves three complementary layers depending on whether the Mac initiates or receives a session:
- The Mac as operator client (
ServerMountApp): On a MacBook or desktop Mac, the native Swift/SwiftUI application manages remote hosts via SSH and SFTP, stores credentials in the macOS Keychain, uses Apple’sCryptoKit, and orchestrates port forwarding throughSSHTunnelManagerbacked by the pureSpecInoltromodel for local (-L), remote (-R), and dynamic SOCKS (-D) forwarding. - The Mac as assisted host (
pubblico-macos.sh): When a remote Mac shares its screen, audio, clipboard, or session files during support, a unified macOS support script governs session lifecycle. In the declarative capability matrix (capacita.json),macosexposes all 11 capabilities:terminale,file,file-sessione,stream,controllo,chat,stampa,appunti,registrazione,salute, andaudio(system audio gated on macOS 13 or newer viaScreenCaptureKit). - Agentless baseline health over SSH (
ParserSaluteMacOS): Even when no Cardinal agent is installed on a remote Mac, the client can inspect baseline machine health over standard SSH without fabricating misleading estimates.
This macOS layer complements the sibling articles in our engineering series: native Linux Wayland capture and video transport, the deterministic command gate and consent-gated BYOK AI diagnostics, and executable protocol contracts and encrypted synchronisation channels.
Session Boundaries, the TCC State Machine and Honest macOS Telemetry
In practice, remote support on macOS rarely fails at the raw TCP or SSH socket; it fails at two platform-specific boundaries: temporary credential lifecycle and Apple’s Transparency, Consent, and Control (TCC) permission model. Our codebase models both explicitly and deterministically.
Locked-by-Default Support Agent and Expiring Single Sessions
The pubblico-macos.sh script provisions macOS remote support so that access remains locked by default immediately after installation. Only when the person at the Mac explicitly opens a support window via --sessione does the agent generate a temporary session credential valid for 30 minutes by default (selectable via --durata as two hours or open until manually closed); a fixed-credential access mode requires an explicit switch via --permanente (while per-connection consent remains a separate setting), whereas --blocca immediately revokes any active or scheduled access.
Under the hood, the macOS agent uses Apple’s directory service utility dscl rather than Linux user tools, marks the dedicated service account hidden (IsHidden 1), and pipes credentials exclusively over standard input so secrets never appear in process argument lists (argv). For timed sessions, a periodic launchd timer checks every 5 seconds whether the configured session window has expired and locks access automatically when time runs out (whereas no expiry timer is armed when set to stay open until manually closed). For the local status interface, --json outputs a deterministic read-only snapshot without administrator privileges, while health files are written with mode 0600 and atomic rename. By design, we never publish exploitable cage parameters such as dedicated account names, tunnel port numbers, or internal configuration paths.
Why PermessiMacOS Models the macOS Black-Screen Trap as a 3-State Machine
Anyone onboarding screen sharing on a fresh Mac encounters a subtle macOS TCC trap: if the user grants Screen Recording (CGPreflightScreenCaptureAccess, paired with ScreenCaptureKit) in System Settings while the target process is already alive, the preflight API reports permission granted, yet the live process continues capturing black frames until the application restarts. By contrast, Accessibility permission (AXIsProcessTrusted for keyboard and pointer injection) takes effect immediately without restarting.
Rather than leaving the user staring at a silent black view, PermessiMacOS.swift encodes this platform rule as a pure, side-effect-free state machine (ProceduraPermessi). For each permission in PermessoMac, StatoPermesso distinguishes exactly 3 states: mancante (not yet granted), concessoInAttesaDiRiavvio (granted during the live session and awaiting restart because richiedeRiavvioDopoConcessione is true for Screen Recording), and pronto (active and ready). In the mancante state, the model deep-links to the corresponding System Settings pane (Privacy_ScreenCapture or Privacy_Accessibility), whereas concessoInAttesaDiRiavvio requests an app restart. Pure transitions are verified by unit tests, while the step-by-step permission window in the app is not built yet and live OS prompt behaviour awaits verification on physical Mac hardware.
ParserSaluteMacOS: Returning nil Instead of Invented Memory Percentages
When monitoring a Mac over plain SSH without an agent, ParserSaluteMacOS.swift evaluates the standard commands sw_vers, df -P /, sysctl -n kern.boottime, and uptime as a pure function parameterised by the current timestamp. When reading kern.boottime, the parser matches sec strictly as an isolated word so substrings such as usec or sector can never be misread as boot epoch seconds. Equally important, ramUsataPercento deliberately stays nil rather than 0 on macOS: because macOS does not expose a clean SSH equivalent to Linux’s MemAvailable and vm_stat mixes compressed and purgeable pages, fabricating a single RAM percentage would mislead operators.
In-Progress Research on Screen and Data Compression Between Mac and Server
Working from a MacBook with a high-density Retina display against a remote engineering workstation exposes a fundamental tension in conventional video streaming: hardware H.264 using 4:2:0 chroma subsampling handles motion efficiently, but visibly softens crisp terminal glyphs, IDE syntax colours, and fine UI lines. Our in-progress research across CardinalHost’s active development branches therefore investigates a hybrid layer named Tela — presented strictly as ongoing research and open engineering questions, never as a finished commercial claim.
Lossless 16×16 Tiles with a zstd Prefix Dictionary Instead of Noisy Video Residuals
Our first research question (2026-10-22-tela-esatta) on a hardware HEVC base asked whether sending a near-lossless residual (maximum error 1 against the decoded HEVC frame) beats direct lossless tile coding. Empirical analysis refuted residuals: lossy quantisation noise around glyph edges raises entropy and needed 3 to 8 times more bytes on text than direct lossless tiles.
Guided by that finding, Tela.swift in our macOS client development branch partitions the canvas into 16×16 pixel tiles (up to 8,192 pixels per side, window log 27), embeds a single-file zstd 1.5.7 decoder without assembly (-DZSTD_DISABLE_ASM) alongside zlib, and uses the client canvas as a prefix dictionary. For contiguous bands, it negotiates CRC-32-checked streaming FLUSSO records (type 4); if any checksum or decoder invariant fails, the client fails closed via tela reset.
Glyph-Dictionary Coding and Documented Negative Results in Ongoing Research
A second research track (razzo-149) explores an encrypted-at-rest glyph dictionary persisted across sessions (tela glifi 1, record type 5) that chooses online per record between glyph coding and zstd, verifies output via CRC-32, and encrypts the local cache using ChaCha20-Poly1305 with HKDF key derivation (wiping keys on host revocation). Two laboratory findings show why we report positive and negative measurements together:
- Small keystroke deltas without canvas prefix: Across 12 measured single-keystroke updates, encoding compact
XORdeltas without the 160-row canvas prefix shrank payloads to 43–53 bytes, compared with a 197-byte median when the prefix was included. - Open bottleneck on full-screen scene switches: In a Python/NumPy prototype, full-screen
1440pglyph decomposition on scene switches consumed 150–200 ms of CPU time versus 37 ms for plainzstdrefinement (whereas compiled Swift-Odecoding inside a virtual machine took 19.0 ms median). Consequently, full-screen video suppression on scene switches remains disabled by default pending a native encoder.
Pixel-Verified Historical Screen Mirror and Its Open Limits
When an engineer on a MacBook switches back and forth between open editor windows or documentation tabs, large screen regions reappear unchanged seconds or minutes later. Research branch razzo-150 investigates an ephemeral, RAM-only, session-encrypted tile mirror (zlib plus ChaCha20-Poly1305) driven by compact SALVA commands (22 bytes) and COPIA references over 64-bit tile hashes. To verify the integrity of the stored mirror slot, the receiver recomputes CRC-32 over the decrypted pixels of that slot: memory corruption, tampering, or a slot from a stale epoch discards the slot and triggers tela reset (whereas tile selection relies on the tile hashes themselves, so the slot checksum does not guard against a hash collision).
Across 20 interleaved ABBA runs at 1440p and 20 Mbit/s on the reference client (with low PSI CPU contention at most 3.49 %), steady-state rate dropped from 4.828 Mbit/s in the previous version to 0.902 Mbit/s, with a 31–32 ms median return time to seen screens and 0 corrupted tiles. The research log also documents three open limits: the production macOS client does not yet request this extension; on 4K scenes capped at 20 Mbit/s, motion p95 rose from 81 ms to 153–161 ms due to queueing behind large exact tile frames; and tail times widen under heavy multi-core contention.
In-Progress Research on Packet Pacing and File Transfer Between MacBook and Server
Alongside screen compression, we research how CardinalHost estimates wireless link capacity and transfers files reliably between Mac and remote servers.
Why Short Packet Pairs Mislead on Wi-Fi Links (SCM_TIMESTAMP_MONOTONIC)
A MacBook often communicates over Wi-Fi or scheduled access links where the radio scheduler aggregates frames and enforces airtime pauses. In a dedicated measurement study between a Linux server and a macOS client (2026-10-23-sonda-capacita-ciclo-accesso), 40 real UDP packet trains totalling 540 of 540 received datagrams of 1,202 bytes each were timestamped in the kernel using SCM_TIMESTAMP_MONOTONIC. Every single one of the 40 trains exhibited medium-access grant pauses: while intra-burst spacing was 5.5 µs median, scheduler pauses between bursts reached 2.38 ms median.
This result directly shapes our transport research: short probes of 6 or 16 packets measure either radio grant pauses or instantaneous burst dispersion rather than sustainable bottleneck capacity (54.2 Mbit/s on the tested path). Our pacing design therefore enforces a conservative rule: never report or unlock a send rate above what a full long access unit has actually delivered end to end.
Multi-Path File Transfer: Session Files, Resumable rsync and SFTPService over ControlMaster
For moving files between Mac and server, CardinalHost pairs established transfer primitives with in-progress research on low-overhead remote file operations:
- Integrity-checked in-session support transfer (
file-sessione): Inpubblico-macos.sh,file-riceviaccepts an incoming file only when its byte length and 64-character hexadecimalSHA-256digest (normalised internally to lowercase) match, placing it in Downloads; in reverse,file-sceglisends solely the single file chosen by the assisted user. - Resumable
rsyncqueue (TransferManager.swift): For larger files and trees, the macOS client runsrsyncover SSH with resumption via a separate partial directory (--partial-dir, leaving the destination untouched until final replacement), isolated temporary SSH configs (modes0700and0600), and the two-leg staging bufferServerMountApp-xfer-<UUID>for server-to-server copies. - Mountless
SFTPServicefile layer (SSH commands andcatoverControlMaster) onmainandpa-sftpresearch (SFTPService.swift): Onmain,SFTPService.swift(named historically, without the SFTP subsystem) runs quoted SSH commands andcatstreams over persistentControlMastersockets without FUSE, guards arguments with--, and enforces root protection (percorsoCanonico,protectedPaths). Branchpa-sftpstudies streamingSHA-256digests in 256 KiB buffers: a single 8 MiB file remained slower thanscp, whereas batches of 128 files of 16 KiB beatscp -r; parallel pipelining, direct server-to-server transfer, and adaptive compression remain open research questions. - Local sync indices and snapshot status (
IndiceSyncLocale,SyncCartelleManager,StatoSyncStore): Hashes files in 64 KiB streaming chunks (O_NOFOLLOW,O_NONBLOCK), appliesfnmatchrules, filters 36-character UUID staging suffixes, and saves JSON atomically.SyncCartelleManagerreads node state fromStatoSyncStore(or pause), returning.offlineonly without a snapshot or on error: auto-refresh requires a persistent file grant without fallback; manual refresh may fall back toindiceRemotoViaElenco(file-elenca) under consent; agent hash-index rollout and continuous sync are in progress.
| Area | Foundation Implemented in Code | In-Progress Research & Open Limits |
|---|---|---|
| macOS Agent & Permissions | pubblico-macos.sh (11 capabilities, locked by default, 30-minute default session, configurable via --durata, 5 s expiry check); 3-state TCC machine in PermessiMacOS; ParserSaluteMacOS |
Step-by-step UI window in the app, plus physical Mac hardware verification of live system prompts and app restart (not yet performed) |
Lossless Tela Compression |
16×16 tiles up to 8,192 pixels, zstd 1.5.7 with canvas prefix, and CRC-32-checked FLUSSO records (type 4) in the client development branch |
Native glyph encoder for 1440p scene switches (currently 150–200 ms in Python vs. 37 ms zstd); production client integration of SALVA/COPIA mirror and 4K send-queue pacing |
| Mac↔Server Network Pacing | 40 measured UDP trains (540 datagrams of 1,202 bytes) with SCM_TIMESTAMP_MONOTONIC demonstrating 2.38 ms radio pauses vs. 5.5 µs intra-burst |
Adaptive rate unlocking over long access units under fluctuating Wi-Fi contention in the production transport path |
| File Transfer & Folder Sync | file-ricevi (64-character SHA-256 check); rsync with --partial-dir; mountless SFTPService (SSH/cat over ControlMaster); 64 KiB IndiceSyncLocale (36-character UUID filter); StatoSyncStore node status (.offline if missing/failed; manual indiceRemotoViaElenco fallback) |
256 KiB streaming SHA-256 in pa-sftp (single 8 MiB files vs. 128 × 16 KiB batches), parallel pipelining, adaptive compression, agent hash-index rollout, continuous sync |
Frequently Asked Questions (FAQ)
The pubblico-macos.sh support script leaves remote access locked after installation: single-session credentials created via --sessione last 30 minutes by default (also selectable via --durata as two hours or until manually closed) and, when timed, are checked every 5 seconds by a launchd job, while --blocca revokes access immediately (covering 11 declared capabilities in capacita.json, with system audio on macOS 13+). Alongside it, PermessiMacOS models TCC permissions in 3 explicit states so the state logic distinguishes the required app restart after granting Screen Recording from a missing permission (the dedicated step-by-step UI window in the app is still unbuilt).
In our in-progress research (2026-10-22-tela-esatta), even a near-lossless pixel residual (maximum error 1) between the source screen and the decoded HEVC base around sharp text edges required 3 to 8 times more bytes than direct lossless 16×16 tiles because quantisation noise raises entropy. The research branch therefore pairs zstd 1.5.7 with the client canvas as a prefix dictionary and CRC-32 checks, while full-screen 1440p glyph decomposition (150–200 ms CPU in Python versus 37 ms for zstd) stays disabled by default pending a native encoder.
Across 40 real UDP packet trains comprising 540 received datagrams of 1,202 bytes each, all 40 runs exhibited access-link scheduler pauses: intra-burst packet spacing was 5.5 µs median, separated by 2.38 ms median pauses. Short probes of 6 or 16 packets therefore measure radio grant pauses rather than the 54.2 Mbit/s bottleneck rate, so our in-progress research caps announced send rates to demonstrated long access-unit delivery.
Operational on main are file-ricevi (64-character SHA-256 check), the resumable rsync queue (--partial-dir), the mountless SFTPService file layer (SSH/cat over ControlMaster with path guards), 64 KiB IndiceSyncLocale, and StatoSyncStore node status in SyncCartelleManager (.offline only without a snapshot or on error; auto-refresh requires a persistent file grant without fallback; manual refresh may fall back to indiceRemotoViaElenco under consent). Research in pa-sftp and companion tracks covers 256 KiB streaming SHA-256 (128 files of 16 KiB beat scp -r; single 8 MiB files trailed scp), parallel pipelining, adaptive compression, agent hash-index rollout, and continuous sync.