Network Topology

Yokai keeps operator control traffic local and reaches device agents through SSH tunnels.

Default ports

Port	Service	Expected exposure
7473	Local Yokai daemon	Loopback on the operator machine
7474	Remote Yokai agent	Device-local; normally reached through SSH
22	SSH	Reachable from the operator machine
8000	Common vLLM service port	Device-local or tunneled, depending on deployment
8080	Common llama.cpp port	Device-local or tunneled
8188	Common ComfyUI port	Device-local or tunneled
3000	Common Grafana port	Device-local, LAN, or Tailscale according to policy

Ports are defaults, not requirements. Service ports are part of each deployment spec.

Control path

yokai-tui
    │ HTTP/SSE on 127.0.0.1:7473
    ▼
yokai daemon
    │ SSH connection and local forwarding
    ▼
yokai agent on device:7474
    │ Docker API / local service HTTP
    ▼
workload containers

The TUI never connects directly to a remote agent. The daemon owns tunnel lifecycle and gives each device an operator-local route.

Tailscale

Tailscale is a discovery and reachability option, not a separate Yokai protocol. The daemon reads local Tailscale state and can use a peer’s Tailscale IP or DNS name as the SSH host. Existing ACL policy still governs access.

Recommended practice:

• tag GPU peers with tag:ai-gpu for easy identification;
• allow SSH only from the operator identity or device;
• avoid exposing agent port 7474 to an entire tailnet when the SSH tunnel is sufficient.

The tag is an identity and discovery signal, not an access grant. See Tailscale GPU Nodes for tag ownership, least-privilege grants, optional Tailscale SSH policy, and verification in Yokai.

Agent authentication

Bootstrap generates a random 64-character hex token. The daemon stores it in the local device record and the agent reads the corresponding remote configuration. Requests without Authorization: Bearer <token> receive 401.

Workload endpoints

Yokai records each workload port and can expose a stable operator-local endpoint through its device connection. Tool integrations use the normalized local URL returned by the daemon rather than asking clients to manage SSH directly.

Firewall guidance

On each GPU device:

• allow SSH from the operator machine or trusted network;
• keep the agent bound to the intended interface and protected by its token;
• expose Grafana or model ports only to the audience that needs them;
• prefer Tailscale or another private network over public ingress;
• do not publish Prometheus credentials or Yokai config files.

Reconnection

The daemon retries disconnected devices according to reconnect_interval_s (30 seconds by default). Metrics polling uses metrics_poll_interval_s (2 seconds by default). A temporarily unreachable device remains in config and appears offline until the tunnel and agent recover.