Documentation Edit this page

AI CLI Supervisor

Remote supervision of AI CLI tools (Claude Code, OpenAI Codex, …) via programmatic PTY sessions. A supervisor daemon runs on a host, manages multiple concurrent AiCliPty sessions by session id (create, list, control, shut down, health/status), and exposes them over the url:// protocol; a browser-based WUI drives those sessions with a live terminal view. It is the hosted face of the AiCli project, and the runner that the agent workstreams (AiCliHostSupervisor, MyLittleAgi) build on.

Current status (2026-07-09): aiclisupervisor.wasmserver.com serves the AiCli Supervisor Fleet console (AiCliSupervisorManagerWui, superseding the single-supervisor DaemonWui) over the durable manager at url://aiclisupervisormanager/. Real supervisors run the AiCliHostSupervisorLauncher fat jar (real CodexPty/ClaudePty sessions, self-announcing with --register-with); the CN-hosted service-server-launcher.jar route remains a FakeCodexPty demo instance. The stack reports usage/quota at all four AiCli scopes (supervisor / model / agent / conversation — each quota a max quantity + current quantity, e.g. the Codex 5-hour and weekly limits parsed live from /status): the daemon serves getUsage, the manager caches fleet-wide usage, and the console renders it on /usage plus per-conversation and per-supervisor panels.

Routes

The supervisor url:// route is per host: each supervised host gets its own vpn.<host-id>.aiclisupervisor instance (the vpn.* naming convention) — real hosts run the launcher fat jar directly (standalone P2P mode) rather than under ContainerNursery. The console is a stateless HTTPS frontend over the durable manager; live PTY traffic flows straight to the owning supervisor.

Architecture

          +---------------------------+
          |      Browser / Admin      |
          +---------------------------+
                      |
                HTTPS | (TLS terminated by ContainerNursery)
                      v
          +-------------------------------+
          | aicli-hostsupervisor-wui.jar  |   stateless WUI (Jetty)
          | aiclisupervisor.wasmserver.com|   remembers supervisors in
          | (ContainerNursery)            |   browser localStorage only
          +-------------------------------+
                      |
            url:// via UrlResolver (P2P / libp2p)
                      v
   +------------------------------------------------+
   |  url://vpn.<host-id>.aiclisupervisor/          |
   |  service-server-launcher.jar                   |   sends SJVM client
   |  (ContainerNursery, lazy-start)                |   bytecode to callers
   +------------------------------------------------+
                      |
                      v
          +---------------------------+
          | AiCliHostSupervisorDaemon |   multi-session PTY manager
          |  Embedded (the daemon)    |   (one per host)
          +---------------------------+
                      |
          +-----------+-----------+
          v           v           v
      AiCliPty    AiCliPty    AiCliPty       each session = an AI CLI under a
      session 1   session 2   session N      pseudo-terminal (real ptyFactory),
                                             optionally inside a Docker container
                                             with AiCliDockerGuestDaemon

The deployed daemon currently substitutes a FakeCodexPty for the real per-session PTY (see status note above).

Repositories

Part of the broader AiCli family, which also includes aiCliPtyApi / AiCliPtyEmbedded (PTY emulation), AiCliDockerGuestDaemonEmbedded (in-container PTY proxy), and AiCliGui (desktop frontend).

Dependents

• The user-facing agent products (MyLittleAgi, SpawningPool) are where end users reach their agents — they connect an AiCliHostSupervisorDaemon like this one behind the scenes as the agent runner (engine design: AiCliHostSupervisor). Aspirational, not yet wired to this deployment.

Deployment

Both JARs run on ContainerNursery via the danger_jarfile provider with keepWarmSeconds: 300.

• WUI — aicli-hostsupervisor-wui.jar serves the HTTPS facade aiclisupervisor.wasmserver.com. Built with aicli.hostsupervisor.wui.buildFatJar. It is stateless (the list of known supervisors lives in browser localStorage) and bounds its dashboard render so it never blocks past ContainerNursery's ~30 s HTTPS read timeout (serves an auto-refreshing "Connecting" page while a cold daemon lazy-starts).
• ServiceServer launcher — service-server-launcher.jar binds url://vpn.<host-id>.aiclisupervisor/ and currently runs with FakeCodexPty. Because a danger_jarfile url:// route cannot pass CLI args or env vars, fake mode is forced via a dedicated entrypoint built with aicli.hostsupervisor.serviceserver.buildFakePtyFatJar. The ServiceServer is dual-mode: ContainerNursery lazy-start (URL_BIND_DOMAIN) — as deployed here — or standalone P2P. A production launcher supplying a real ptyFactory (CodexPty/ClaudePty, via the Embedded module) would replace it to drive real AI CLIs.

Health Checks

• WUI: https://aiclisupervisor.wasmserver.com/ — should return HTTP 200.
• Production Health: see productionhealth.wasmserver.com.
• ContainerNursery: monitored via standard ContainerNursery health checks.

Notes

• The deployed instance is a fake-model demo, not a real AI CLI host (see the status note). Creating a session through the WUI yields the [fake-model] echo daemon, which is intentional — it lets the end-to-end WUI → url:// → daemon path be exercised without any Codex/Claude install.
• The WUI itself holds no server-side session state; supervisor history is per-browser (localStorage).
• The vpn.<host-id> route convention scopes a supervisor instance to a single host, so multiple hosts can each expose their own aiclisupervisor endpoint under the same pattern.