Architecture
How ArcBox Desktop works under the hood.
Overview
ArcBox Desktop is a native macOS application that provides a GUI for the ArcBox runtime. It does not run containers itself — it communicates with the ArcBox daemon, which manages the actual workloads.
Components
Desktop App
A SwiftUI application using the @Observable pattern for state management. Communicates with the daemon over gRPC (via grpc-swift) and renders the UI. Has no privileged access — all privileged operations go through the helper.
Daemon
A Rust process (arcboxd) that manages the container runtime, virtual machines, networking, and filesystem. Exposes a gRPC API over a Unix socket. Creates and manages a lightweight Linux VM using Apple's Virtualization.framework.
Privileged Helper
A minimal daemon installed via SMAppService that handles three operations: Docker socket symlink, CLI installation, and DNS resolver configuration. See Helper.
Lightweight VM
A Linux VM running a custom-built kernel optimized for container workloads. Boots in milliseconds. VirtIO devices provide high-performance bridging for storage, networking, and IPC.
Communication
| Path | Protocol | Why |
|---|---|---|
| Desktop ↔ Daemon | gRPC over Unix socket | Type safety, streaming, code generation |
| Daemon ↔ VM | ttrpc over vsock | Minimal overhead, no TCP stack required |
Data Flow
All container data (images, volumes, logs) lives inside the VM's virtual disk. The daemon acts as a proxy, translating Docker API calls into operations inside the VM.
The Desktop app caches display state in memory but is not the source of truth. If the app restarts, it re-fetches everything from the daemon.