Edit AI CLI Supervisor — Service Atlas

Editing the page as plain markdown. The rich editor loads with the page; if it has not appeared, this field still saves normally.

# 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](https://github.com/CodexCoder21Organization/DocumentationRepository/blob/main/projects/AiCli.md) project, and the runner that the agent workstreams ([AiCliHostSupervisor](https://github.com/CodexCoder21Organization/PlanRepository/blob/main/workstreams/AiCliHostSupervisor.md), [MyLittleAgi](https://github.com/CodexCoder21Organization/PlanRepository/blob/main/workstreams/MyLittleAgi.md)) build on.

> **Current status (2026-07-09):** `aiclisupervisor.wasmserver.com` serves the **AiCli Supervisor Fleet console** ([AiCliSupervisorManagerWui](https://github.com/CodexCoder21Organization/AiCliSupervisorManagerWui), superseding the single-supervisor DaemonWui) over the durable manager at `url://aiclisupervisormanager/`. Real supervisors run the [AiCliHostSupervisorLauncher](https://github.com/CodexCoder21Organization/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](https://github.com/CodexCoder21Organization/DocumentationRepository/blob/main/projects/AiCli.md#terminology)** (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`](https://aiclisupervisor.wasmserver.com/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](https://github.com/CodexCoder21Organization/DocumentationRepository/blob/main/projects/AiCli.md) family, which also includes [aiCliPtyApi](https://github.com/CodexCoder21Organization/aiCliPtyApi) / [AiCliPtyEmbedded](https://github.com/CodexCoder21Organization/AiCliPtyEmbedded) (PTY emulation), [AiCliDockerGuestDaemonEmbedded](https://github.com/CodexCoder21Organization/AiCliDockerGuestDaemonEmbedded) (in-container PTY proxy), and [AiCliGui](https://github.com/CodexCoder21Organization/AiCliGui) (desktop frontend).

## Dependents

- The user-facing agent products ([MyLittleAgi](https://github.com/CodexCoder21Organization/PlanRepository/blob/main/workstreams/MyLittleAgi.md), [SpawningPool](https://github.com/CodexCoder21Organization/PlanRepository/blob/main/workstreams/SpawningPool.md)) are where **end users** reach their agents — they connect an `AiCliHostSupervisorDaemon` like this one behind the scenes as the agent runner (engine design: [AiCliHostSupervisor](https://github.com/CodexCoder21Organization/PlanRepository/blob/main/workstreams/AiCliHostSupervisor.md)). 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/](https://aiclisupervisor.wasmserver.com/) — should return HTTP 200.
- **Production Health**: see [productionhealth.wasmserver.com](https://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.

Commit message

Cancel

Editing against commit 9467c5cbaeba3f3aece7df029ab93d65e0bce544. A save is refused if the atlas has moved past it, so a slow edit cannot discard somebody else's commit.