> ## Documentation Index > Fetch the complete documentation index at: https://docs.monolex.ai/llms.txt > Use this file to discover all available pages before exploring further. # Monolex PTY Daemon > Own terminal child processes, VTE state, scrollback, resizing, and socket transport for Monolex clients. `monolex-pty-daemon` is the native PTY and terminal-emulation service beneath the Monolex desktop app, headless server, Maxmux, MonoTerm, and Monopty. It owns child processes and Alacritty-based VTE state so clients can reconnect without becoming the terminal process owner. *Published contract: `monolex-pty-daemon 0.2.8`, OpenCLIs build `2026-07-18-155744`. The executing binary, registry, and public CDN metadata agree on this release.* ## Quick Start ```bash theme={null} openclis install monolex-pty-daemon monolex-pty-daemon --version monolex-pty-daemon # start the daemon in the foreground ``` Most users should let Monolex or the headless service manage the daemon rather than launching an extra owner manually. ## Complete Command Reference | Invocation | What it does | Effect | | ------------------------------------ | ----------------------------------------------- | -------------------------------------------------------------------- | | `monolex-pty-daemon` | Starts the daemon and binds its control socket. | Long-running process; owns PTY children and terminal state. | | `monolex-pty-daemon -h`, `--help` | Prints the public CLI contract. | Read-only. | | `monolex-pty-daemon -V`, `--version` | Prints the payload version. | Read-only; use this to verify the installed executable, not the CDN. | There are intentionally no public create/write/resize subcommands. Those operations travel over the versioned daemon protocol through Monolex clients; exposing a second ad-hoc CLI parser would split ownership of ordering and state. Only the four flag forms above are parser exits. Bare `help`, bare `version`, an unknown option, or any other first argument falls through to daemon startup. Do not probe this binary with guessed subcommands. ## Internal Control Protocol The daemon control socket currently uses protocol version 1 and accepts seven newline-delimited JSON request types. These are a client-library contract, not shell subcommands: | Request type | Responsibility | Important fields or boundary | | ---------------- | ---------------------------------------------------- | ------------------------------------------------------------------- | | `create-session` | Spawn a PTY and return its session id/socket. | Optional `sessionId`, `projectHash`, cells, pixels, shell, and cwd. | | `remove-session` | Close and remove a named session. | Requires `sessionId`. | | `list-sessions` | List daemon-owned sessions. | Read-only control query. | | `resize-session` | Resize cells and optional pixel dimensions. | Updates the PTY/window size for one `sessionId`. | | `status` | Report daemon state and protocol version. | Clients use this to detect wire skew. | | `subscribe` | Preserve the legacy notification registration shape. | Compatibility lane; current estate clients do not use it. | | `shutdown` | Request daemon shutdown. | Process mutation reserved for owning clients/service flows. | The control response has one stable shape with `success`, optional `sessionId`, `socketPath`, `error`, `message`, and `protocolVersion` fields. Session input/output then travels over the returned per-session socket; users should go through Headless, Monopty, Maxmux, MonoTerm, or `lib-pty-client` instead of writing raw protocol messages. ### Session retirement is process-tree ownership In 0.2.8, `remove-session` moves the session out of the shared map, releases the global lock, then terminates and reaps the owned process tree before it acknowledges success. A stubborn child therefore cannot freeze unrelated health, list, or create requests. If cleanup fails, the session is put back and the caller receives an error instead of a successful row-only deletion. On Unix, the daemon validates the session leader and foreground process group, sends a graceful hangup, waits, then uses a bounded kill escalation. On Windows, every ConPTY session is assigned to a Job Object configured with `KILL_ON_JOB_CLOSE`, so descendants are contained with the shell. Whole-daemon shutdown drains all sessions and applies the same cleanup contract. A lifecycle test should prove that both the shell PID and a foreground descendant PID are gone after close; an empty session list alone is insufficient evidence. ## What the Daemon Owns | Layer | Responsibility | | ---------- | ------------------------------------------------------------------------------------------------- | | Process | Spawn the configured shell or AI CLI, forward input, resize, signal, and reap the child. | | Terminal | Parse escape sequences, maintain the grid and scrollback, and preserve wide-cell/attribute state. | | Transport | Bind an app-scoped local control socket and serialize ordered session operations. | | Continuity | Keep the PTY alive while a compatible client detaches and reconnects. | The daemon does **not** own desktop tabs, gateway authentication, remote estate presence, terminal UI key bindings, or AI answer extraction. Those remain in their respective client and orchestration layers. ## Deployment and Signing On macOS, a copied or rebuilt sidecar must be code-signed before a hardened Monolex app can launch it. A successful build alone is not deployment proof. For a packaged app, verify all of these independently: ```bash theme={null} monolex-pty-daemon --version codesign --verify --strict /path/to/monolex-pty-daemon monopty health monopty test ``` On Linux and Windows, verify the installed architecture-specific payload and a real PTY lifecycle. Socket or named-pipe reachability does not by itself prove that the child terminal is rendering correctly. ## Published Platforms Version 0.2.8 ships five standalone archives from clean source commit `98c4bcada9e8d248ec48678e191f8d47daefd436`: `darwin-aarch64`, `linux-x86_64`, `linux-aarch64`, `windows-x86_64`, and `windows-aarch64`. | Platform | Archive SHA-256 | Extracted payload SHA-256 | | ----------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------ | | `darwin-aarch64` | `2ea8c698d042fa8a4387a30a936cf6d6112c2ccc7c25ffaa998f509cfc97ab3c` | `bb0f1bd9a220d0e2f0a6ca5e355d0118868dcec6e0f50035efe56a176b9b943e` | | `linux-x86_64` | `3e9fa68ddb9ccb47a4caa115dfbb4d6e97349fc7c82ed0dfeddb83d2bbd52d7a` | `f660c45bbf6370e14d936f8902dc0c91ab0a0252f1249f261d17c1f8c6050084` | | `linux-aarch64` | `9d79f3fd6e4136fe431e6c8f8ec69d91ce253dabca94168f92c06436bc7bb9ce` | `9eaf8d4bca7141b700c103392fd343d63358266f8d68d07a28070264aeaa7508` | | `windows-x86_64` | `b265fc2824205182126c9aeec02502aa318fb94c9eaf8c16624451edc08ee4d2` | `76d2d4e8c3715293689618a34a01dedfe0767c6eb2f3b3ba44868e798d1db157` | | `windows-aarch64` | `19c288e74bb2f537a4c801ee0d79d8e741ed2c3968f47141cf2c3d11c6e3e2ad` | `cbef4da29e5bfd833ea94b6d002713b3b32ba0ae751786e9524fd92ebc626397` | All five archives and extracted binaries were directly hash-verified. The macOS payload executed as 0.2.8 and passed strict Developer ID verification. Headless 0.1.45 also bundles PTY Daemon 0.2.8 in each of its four platform archives. A standalone daemon version check and a Headless-bundled sidecar check are different release proofs; verify the executable that the active service actually launches. ## Relationships | Tool | Ownership | | --------------------------------------------- | -------------------------------------------------------------------------- | | [Monolex Headless](/ai-clis/monolex-headless) | Creates server-side sessions and exposes higher-level local/remote control | | [Monopty](/ai-clis/monopty) | Verifies rendered PTY behavior through the headless control surface | | [Maxmux](/ai-clis/maxmux) | Adds a full-screen crossterm UI and user key bindings | | [MonoTerm](/ai-clis/monoterm) | Adds a separate terminal client over the shared PTY foundation |