Skip to content
Ubiquitty

How it works

How Ubiquitty is put together Programs run in pseudo-terminals owned by ubiquitty-host. Inside the host, the Core parses their output into the screen, scrollback and layout of windows, tabs and panes, and checks every effect against the permission policy. The host sends each client a checkpoint of the screen, then updates and history, over the Sync protocol; clients send input, their size and focus back. The clients are the macOS app, the iPhone and iPad app, the web page, the Emacs and Neovim clients, and ubq for people and agents. They reach the host over the local socket, SSH, QUIC, a WebSocket bridge or the host's attach bridge. Each client keeps a replica of the screen and draws it with its own renderer. Programs your shell editors, builds, TUIs commands an agent runs for you one PTY per pane output input ubiquitty-host keeps sessions when no client is attached Core parser: every escape sequence screen, scrollback, images windows › tabs › panes permission checks, by who drove the bytes frames: only what changed history, by logical line tokens · consent · audit log the same Core also runs inside the macOS and Linux apps for a local window Sync checkpoint, updates, history input, size, focus local socket SSH · QUIC WebSocket attach bridge Clients: screens macOS app Metal, CoreText iPhone and iPad Metal, CoreText Web page Core in WebAssembly, WebGL2 Emacs, Neovim the protocol in Lisp and Lua ubq, for people and agents command line and MCP server each keeps a replica of the screen and draws it with its own renderer A session lives on the host. Closing a client detaches it; another client can attach to the same session.
View full-size diagram

One Core

Section titled “One Core”

The portable C++ Core parses terminal output, keeps the screen and scrollback, decodes images, decides which rows changed, and checks effects such as clipboard access against the permission policy. Native frontends and the host use that Core. The Emacs and Neovim clients read its replicated state without linking the C++ library.

The host keeps the session

Section titled “The host keeps the session”

ubiquitty-host is that Core running as a daemon. It owns a pseudo-terminal for every pane, the programs running in them, their screens and scrollback, and the layout: a workspace of windows, each with tabs, each with a tree of panes. Detach every client and the host keeps the shells running.

The macOS app carries the host inside it and starts it when a session needs to outlive a window. On another machine, the app installs the host over SSH the first time you connect.

Clients are screens

Section titled “Clients are screens”

A client keeps a replica of each pane’s screen and draws it with its own renderer: Metal and CoreText on the Mac, iPhone and iPad, WebGL2 in a browser, an Emacs or Neovim buffer, or plain text for ubq. It sends up what you type, its size and its focus. Two clients can show the same session at once, and an agent’s client is held until a person on that session agrees to let it in.

The macOS app and the Linux frontend can also run the Core in-process, for a window whose shell is local to the app. On macOS, sharing a local window hands its shell to the host without restarting it.

Sync between them

Section titled “Sync between them”

The Sync protocol carries the session between host and client, over any byte stream: the host’s local socket, SSH, QUIC after SSH has authenticated, a WebSocket bridge for the browser, or the host’s attach bridge for the editor clients.

  1. Attach. The client says hello with its size and the session it wants, by id or by name, and presents a token if it is an agent or a remote client.
  2. Checkpoint. The host sends the whole screen once.
  3. Updates. From then on it sends only the rows and state that changed since a frame the client acknowledged, paced to the link. The host batches changes around coherent frames, with a bounded wait for programs that keep drawing.
  4. History. Scrollback comes separately, newest lines first and older ones to the depth the client asks for, so a phone on a metered link does not download a day of build logs to show a prompt.
  5. Reconnect. A returning client presents its retained replica identity. The host sends changes from retained state when possible, or a checkpoint when a fresh base is required. The shell keeps running on the host.

Numbered input and receipts keep transport delivery distinct from application output. Screen, history and pane metadata travel independently. The Sync protocol page links the specification for client implementers.

Where to read more

Section titled “Where to read more”

Ubiquitty and this site are copyright © 2026 Stanislav Yaglo. Ubiquitty is licensed under the Apache License 2.0.

Apple, iPad, iPadOS, iPhone, Keychain, Mac, macOS, Metal, Swift and Xcode are trademarks of Apple Inc., registered in the U.S. and other countries and regions.