Skip to main content

Architecture: Daemon → Headless → PTY

PTY-for-AI is built on three layers. Each layer does one thing and is independently replaceable.

The Three Layers

Layer 1: PTY Daemon

The foundation. A persistent process that spawns and manages PTY sessions. Responsibility: Create terminal sessions, resize, close, list. Nothing more. Protocol (JSON over Unix socket):
Response:
Key properties:
  • Runs as OS service (launchd on macOS, systemd on Linux)
  • Survives terminal closures, reboots, SSH disconnects
  • Each session has its own Unix socket for I/O
  • Supports cwd and shell per session — this is how plugins work
  • Binary is never modified. All extension happens externally.

Layer 2: Headless Server

Bridges PTY sessions to the network without a GUI window. Responsibility: Connect to gateway, relay terminal I/O, manage grid state. What it does:
  • Creates a PTY session via daemon (Layer 1)
  • Renders terminal grid (VTE parsing)
  • Connects to gateway via WebSocket
  • Relays input/output between gateway and PTY
  • Accepts --default-cwd and --default-shell from plugins
What it doesn’t do:
  • No window. No UI. No display.
  • Does not modify terminal content.
  • Does not interpret commands.

Layer 3: Gateway / P2P

Remote access to headless sessions across machines and networks. Two paths:
Gateway for reliability. P2P for when gateway is unreachable. Both encrypted end-to-end.

How Sessions Are Controlled

These commands work identically for local and remote sessions:

Persistence Model

The daemon is an OS service. It starts on boot and restarts on crash. Sessions persist across:
  • Terminal window closures
  • SSH disconnects
  • Network interruptions
  • Application restarts
Only explicit session close or machine shutdown ends a session.

Plugin Injection Points

Plugins transform session parameters before they reach the daemon. The daemon never knows plugins exist.
This separation means:
  • Daemon binary never changes (stable, signed, tested)
  • New plugins are added to the CLI layer only
  • Plugin development doesn’t require daemon access
  • Third-party plugins are possible (same interface)

What Each Layer Knows

No layer knows which AI is running inside the PTY. This is by design. LLM-agnostic at every level.