System Overview

Yokai is a three-tier control system: an OpenTUI client, a local daemon, and one authenticated agent per managed GPU device.

Operator machine                              GPU device

┌────────────────────────┐                    ┌────────────────────────┐
│ yokai-tui              │  REST + SSE       │ yokai agent :7474      │
│ Dashboard / Devices /  │◄──────┐            │ system + GPU metrics   │
│ Deploy / Settings      │       │            │ Docker lifecycle       │
└───────────┬────────────┘       │            │ service probes + logs  │
            │                    │            └────────────┬───────────┘
            │ localhost :7473    │ SSH tunnel              │
┌───────────▼────────────┐       │            ┌────────────▼───────────┐
│ yokai daemon           ├───────┘            │ Workload containers    │
│ config + history       │                    │ vLLM / llama.cpp /     │
│ tunnels + aggregation  │                    │ ComfyUI                 │
│ BKC / HF / integrations│                    └────────────────────────┘
└────────────────────────┘

OpenTUI

yokai-tui is a compiled Bun/OpenTUI React client. It contains four routes—Dashboard, Devices, Deploy, and Settings—and talks only to the daemon over REST and Server-Sent Events.

The frontend does not read SSH config, invoke Tailscale, edit tool configurations, bootstrap devices, or write Yokai state directly. Those behaviors stay behind the daemon API.

Local daemon

yokai daemon is the operator-side control plane. It:

• owns config.json and deploy history;
• resolves SSH and Tailscale discovery;
• opens and repairs device tunnels;
• polls and aggregates agent metrics;
• proxies service lifecycle actions and logs;
• exposes the BKC catalog and Hugging Face helpers;
• performs vLLM memory estimates;
• manages settings and coding-tool integrations;
• coordinates device bootstrap, tests, and upgrades.

The default listen address is 127.0.0.1:7473.

Remote agent

yokai agent is installed as a systemd service on each managed device and listens on port 7474 by default. It is responsible for operations that must happen near Docker and the GPU:

• system, GPU, container, and LLM-service metrics;
• image-tag inspection and image pulls;
• container create, stop, restart, remove, test, and log streaming;
• static system and runtime information;
• Prometheus exposition.

Every agent route requires its generated bearer token.

Workloads

Workloads remain normal Docker containers. Yokai records enough state to reconnect and render them, but the agent also discovers managed containers from Docker labels and the yokai- naming convention.

Supported first-class workloads are vLLM, llama.cpp, and ComfyUI.

Monitoring stack

The optional per-device stack adds Prometheus, Grafana, node_exporter, and dcgm-exporter. The TUI does not depend on Grafana: its live view comes from agent JSON metrics cached by the daemon.

Launch sequence

1. yokai resolves the daemon address from config.
2. It checks GET /health with a short timeout.
3. If unhealthy, it starts yokai daemon in the background and waits up to five seconds.
4. It locates yokai-tui next to the controller binary and passes YOKAI_DAEMON_URL.
5. In a source checkout only, it can fall back to bun run src/index.tsx when the compiled sidecar is absent.

Data flow

1. The daemon opens an SSH tunnel to each agent.
2. It polls JSON metrics and keeps the latest fleet snapshot in memory.
3. The TUI fetches aggregate state and renders local history.
4. User actions travel TUI → daemon → agent → Docker.
5. Agent responses and SSE streams travel back through the same trust boundaries.

See Network Topology for ports and trust boundaries.