跪拜 Guibai
← All articles
AI Programming · OpenAI · AIGC

Tether: A Locally-First AI Agent Desktop Workstation Built on Pi

By 因吹斯汀 ·
Read original on juejin.cn ↗ Google Translate ↗ Alt translation

Most AI coding tools are cloud services that own your session data and offer limited control over agent behavior. Tether demonstrates that an open-source ecosystem like Pi can be wrapped into a local-first desktop tool where the security boundary is enforced by the type system, the agent process is crash-isolated, and every file mutation is checkpointed for reliable undo — a combination that cloud-hosted alternatives rarely deliver.

Summary

Tether bundles model invocation, terminal commands, diff review, and session history into a single Electron desktop application where all data stays on disk and model requests go directly to the configured provider. The architecture isolates the renderer process from Node.js entirely through a typed IPC contract, while the agent runs in an independent child process so a crash never takes down the UI or silently replays unfinished commands. File changes are tracked as patches with checkpoints, making a single `/undo` command sufficient to roll back an entire turn of modifications. Four permission modes — plan, ask, auto, and full — let developers dial in how much autonomy the agent gets, backed by macOS Seatbelt sandboxing. Skills, MCP, and hooks are inherited from the Pi runtime rather than reimplemented, and team conventions can be codified as skill files instead of living in chat logs.

Takeaways
— All renderer-to-main communication goes through a typed `DesktopApi` interface; the preload script is a mechanical translation layer with no logic, and the compiler rejects any attempt to access unlisted capabilities.
— Agent processes run in independent child processes over JSON-RPC on stdio; a crash leaves the session file on disk for manual recovery but never silently replays unfinished commands.
— RPC requests use a timeout whitelist: standard calls get 45 seconds, while long-running operations like `prompt` and `compact` get 30 minutes to prevent a single hung request from freezing the UI.
— File changes are applied as patches with per-turn checkpoints; the `/undo` command restores the previous turn's file state by writing the checkpointed versions back to disk.
— Four permission modes control agent autonomy: `plan` (read-only with sandboxed diagnostics), `ask` (prompts before writes or network access), `auto` (auto-executes routine ops, prompts on escalation), and `full` (disables the workspace sandbox for trusted projects).
— Skills are loaded at runtime from `SKILL.md` files with frontmatter; team conventions like UI patterns or long-task workflows become version-controlled skill files rather than tribal knowledge.
— Session data lives under `~/.tether` with no telemetry or relay; model requests connect directly to the user's configured provider.
Conclusions

Typed IPC contracts turn Electron's notorious security surface into a compile-time enforcement problem — if a capability isn't in the interface, the renderer literally cannot request it, which is stronger than any runtime permission check.

Running the agent in a child process rather than the main process is the architectural decision that makes crash recovery possible; a single misbehaving model invocation can't take down the entire application.

The patch-and-checkpoint approach to file mutations is what makes undo feasible in an agent context. Whole-file rewrites would make rollback prohibitively expensive and imprecise.

Codifying team conventions as skill files rather than relying on chat history or documentation is an underappreciated pattern — it makes agent behavior reproducible and version-controllable across a team.

Concepts & terms
contextBridge / contextIsolation
Electron security mechanisms that create a strict boundary between the renderer process (which loads web content) and the main process (which has full Node.js access). contextBridge exposes only explicitly listed APIs, and contextIsolation prevents the renderer from accessing Node.js or Electron internals directly.
JSON-RPC over stdio
A communication pattern where a parent process spawns a child process and exchanges JSON-RPC messages over standard input/output streams. Each message is a newline-delimited JSON object representing a request or response, keeping the protocol simple and debuggable.
macOS Seatbelt (sandbox)
Apple's mandatory access control framework that restricts what system resources a process can access — files, network, processes, and syscalls. Tether uses it as a defense-in-depth layer to contain agent operations even before permission prompts are evaluated.
MCP (Model Context Protocol)
An open protocol that standardizes how AI models connect to external tools and data sources. In Tether, MCP support is inherited from the Pi agent-core runtime, allowing the agent to interact with MCP-compatible servers for extended capabilities.
Source: juejin.cn ↗ Google Translate ↗ Backup ↗