vbox

English · 한국어 · 日本語 · 简体中文 · Español

A self-contained protocol + Wayland nested compositor for running Linux guest GUI apps as rootless multi-window on a macOS host. The goal is full keyboard input support for any language, without any XPRA dependency.

Why vbox?

• XPRA's macOS client never forwards host IME composition to the guest, so non-Latin keyboard input (Korean/Japanese/Chinese, etc.) is broken.
• The XPRA macOS cask is deprecated — it fails Gatekeeper and will not survive future macOS releases.
• Owning both the wire format and the client is the only way to keep long-term maintenance in our hands.
• Targeting Wayland as the canonical backend avoids the X11 capture/ injection special-cases from day one.

How vbox compares

Aspect	vbox	XPRA	VNC	ssh -X	Waypipe
Display unit	rootless windows	rootless windows	whole desktop	single window	rootless windows
Guest display	Wayland	X11 first	X11 / Wayland (whole)	X11	Wayland
macOS client	native (winit)	cask deprecated	external (RealVNC, etc.)	XQuartz	none
Asian IME (KR/JA/ZH)	yes (text-input-v3)	no (host IME not forwarded)	no	no	yes (Wayland passthrough)
Transport	QUIC + TCP / ssh -L fallback	TCP / SSH	RFB over TCP	SSH X11	SSH or Unix socket
Main use case	macOS ↔ Linux	any ↔ any	any ↔ any	any ↔ any	Linux ↔ Linux

Architecture

 macOS host Linux guest
┌──────────────┐ ┌──────────────────────────────┐
│ │ │ ┌────────────────────────┐ │
│ │ data plane │ │ vbox-server │ │
│ │ ◀─QUIC(UDP)──▶ │ │ (data plane) │ │
│ │ default │ │ Wayland compositor │ │
│ │ TCP+ssh -L │ │ + frame stream │ │
│ vbox-client │ fallback │ │ (QUIC + TCP listen) │ │
│ (viewer) │ │ └───────────▲────────────┘ │
│ │ │ │ spawns │
│ │ ctl : 5711 │ ┌───────────┴────────────┐ │
│ │ ◀─token/mTLS─▶ │ │ vbox-controld │ │
│ │ (bootstrap) │ │ (control plane) │ │
│ │ │ │ instance / app RPC │ │
└──────────────┘ │ └────────────────────────┘ │
└──────────────────────────────┘

• vbox-server (guest) — streams the screen, receives the input. Runs as a Wayland compositor on the Linux guest. Streams each app window's pixels to the host and injects the host's mouse / keys / IME back into the app. Transport: QUIC (UDP) preferred, TCP / ssh -L as fallback.
• vbox-controld (guest) — the manager. Spawns vbox-server, launches / stops apps, and hands the viewer the connection info (address, token, QUIC cert hash). Token or mTLS auth.
• vbox-client (macOS) — the viewer. Opens one native macOS window per guest app window and keeps mouse / scroll / keys / IME / resize / close in sync with it. Bootstraps via controld first, then talks to vbox-server directly.

Crate layout

crates/
├── proto/ # wire format, handshake, RPC types (no I/O)
├── server/ # guest data plane: vbox-server
├── controld/ # guest control plane: vbox-controld
├── client/ # macOS client: vbox-client (ping/view/ctl)
└── vbox-cli/ # user-facing clap CLI: vbox

Install on macOS (Homebrew)

brew tap openVbox/vbox https://github.com/openVbox/vbox.git
brew install --cask vbox

Upgrade or remove later:

brew upgrade --cask vbox
brew uninstall --cask vbox --zap # also clears ~/Applications/vbox + ~/.vbox

Install on the Linux guest

curl -fsSL https://raw.githubusercontent.com/openVbox/vbox/main/scripts/install-linux.sh | sh

From source (older glibc, other arches, or development)

# on the guest — git + cargo + build deps
sudo apt install -y git cargo build-essential pkg-config libxkbcommon-dev # or dnf equivalent
git clone https://github.com/openVbox/vbox.git ~/vbox &&cd~/vbox
./install.sh # cargo build → systemd user unit → linger (plain-token only)

Run

Launch vbox.app from Launchpad and pick from the GUI, or invoke the CLI directly:

# guest sync + server + ssh tunnel + viewer + app launch in one shot
vbox run gnome-calculator
# step-by-step
vbox view # server + tunnel + viewer only
vbox app gnome-calculator # spawn an app into the open viewer# tear down
vbox stop

Specify guest/port:

vbox --guest USER@HOST --guest-dir /path/to/vbox --port 5710 run gnome-calculator

Changelog

See CHANGELOG.md.