monolex-headless is the GUI-free Monolex terminal server. It supervises PTY
sessions through the PTY daemon, maintains rendered terminal state, exposes a
local control socket for Monopty, and—outside local-only
mode—opens an owned gateway session for remote access.
Published contract: monolex-headless 0.1.45, OpenCLIs build
2026-07-18-160008, source commit
0ccadab991a6ba90f6e4268e0d720ba229244662. The clean macOS archive has
SHA-256 a8f340613d4a99ea7de6b19e0c09ba97dc92286d8a202ea554b011965dfcbcba.
Quick Start
monopty health. For a persistent machine,
prefer the OS-service commands below over an unsupervised foreground process.
Complete Command Reference
Version 0.1.45 exposes one foreground invocation and six service operations. Clap also provides the generatedhelp command plus -h/--help and
-V/--version.
service-start refreshes the stable service wrapper to the currently installed
monolex-headless and sibling monolex-pty-daemon before asking the OS service
manager to start it. After an OpenCLIs update, use service-stop followed by
service-start so an older service-owned child does not survive the upgrade.
Runtime Options
--local-only and --proxy are mutually exclusive. A --session-id is also
rejected outside local-only mode: remote Headless opens a new session owned by
the authenticated vault device rather than attaching a viewer token as the
host. These validation failures occur before PTY runtime startup.
Remote authentication is owned by the shared OpenCLIs vault. Do not pass
gateway secrets through arbitrary argv or environment variables; authenticate
with the estate’s supported login surface and let the runtime read the vault.
Session Close and Reaping
Version 0.1.43 adds the local control-socket twin of the gatewaytab-close
operation. It is not a new Headless root CLI command: local automation calls
monopty close <SESSION>, while a remote viewer sends the corresponding tab
close event. Headless closes the PTY daemon session, removes it from the
Headless session map, and ends the matching heartbeat row so a dead shell does
not remain listed or reappear as a recoverable ghost. Closing an already-gone
session is idempotent. The operation retires one session; it does not stop the
Headless server or PTY daemon.
Version 0.1.45 keeps that Headless command/control surface and bundles PTY
Daemon 0.2.8. A close now succeeds only after the PTY owner terminates and
reaps the session shell plus its foreground descendants. On Unix the daemon
owns the session/foreground process groups and escalates from a graceful signal
to a bounded kill; on Windows it contains descendants in a Job Object with
kill-on-close. Cleanup failure remains an error rather than silently deleting
only the session row or socket, and daemon shutdown applies the same process-
tree contract to every live session.
Local and Remote Modes
~/ resolve there,
while outside absolute paths, parent traversal, and symlink escapes fail.
Dedicated DataChannel transfers use a 4 KiB header and a 64 MiB file limit;
local control-socket JSON transfer uses a 1 MiB decoded-file limit. Remote
WebSocket/WebRTC JSON FileGet and FilePut fail closed—use
monosystem remote cp for cross-machine copies.
Uploads stage beside the destination and replace it atomically only after the
declared byte count and PUT-END N agree. Downloads do not report success until
the receiver returns GET-ACK N. Zero-byte files are valid. These contracts
make the transfer surface bounded and acknowledged; they do not turn Headless
into an unrestricted filesystem API.
Service Semantics by Platform
Service pidfiles identify
headless=PID and pty=PID; status and cleanup reject
reused PIDs whose executable does not match the recorded role. The wrapper
retries a Headless process that dies within 15 seconds up to five times with a
two-second backoff. This is startup resilience, not proof of a stable PTY—run
the Monopty checks below after the service settles.
Published Platforms
The 0.1.45 train packages Headless together with PTY Daemon 0.2.8 (monolex-headless plus monolex-pty-daemon, with .exe names on Windows).
Every platform fragment must record source commit
0ccadab991a6ba90f6e4268e0d720ba229244662 and source_dirty: false.
The extracted macOS Headless executable has SHA-256
65fbb8a0369ae40fe948b80c53b830e6ff82f86a85c1f29d97d6cd0d20b821ef;
its bundled PTY Daemon has SHA-256
76d9ae5f5eaf1e85acc75a78d0d1cf2946ec89d814583dba9116437bd69ec7d3.
Both passed strict Developer ID signature verification and reported versions
0.1.45 and 0.2.8 respectively.
The extracted Linux x86_64 Headless executable has SHA-256
128134a7a90795917e56f1d2c3a48a643956c243fc82f58ad7b3a0def6c4282b;
the bundled PTY Daemon has SHA-256
6613984819fb154c641406228c5a5ce8d512f59b043b18ae2211c356fef56fb7.
The extracted Windows x86_64 Headless executable has SHA-256
42bd5f67485026b69bd46c369fae5ca16424e68a8d60aa5373f8040ced2c17be;
its bundled PTY Daemon has SHA-256
2191bec7087a74279e5eb55ecd3fd32adb8b4623ae1daccff4415b2c9aebb186.
The extracted Linux AArch64 Headless executable has SHA-256
e13527a9f4666d1d6f561afdabe19dcf2b7baa447b0936f7ff90943c76854b7b;
its bundled PTY Daemon has SHA-256
d96789d8bb49c5ffd16f9ee22dc25937a21161e13712fa51a1eac406d7a26743.
The current latest.json, every platform fragment, and merged metadata report
source_dirty: false. All four platform rows were directly downloaded and
hash-verified. Platform availability proves distribution only; it does not
prove service registration or a live PTY.
Verification
--local-only smoke proved the
new close path end to end: Headless owned a live daemon, Monopty created a
session, the shell exited, close removed the session from Headless, a repeated
close remained successful, and shutdown left no test daemon, socket, or process
behind. A complete deployment check proves each layer independently.