Security Model
Yokai is designed for a trusted operator machine managing trusted GPU devices over SSH. It is not a multi-tenant authorization system.
Trust boundaries
Section titled “Trust boundaries”Operator machine
Section titled “Operator machine”The local daemon is the authority for fleet configuration, device tokens, endpoint discovery, and tool configuration. It listens on loopback by default. Anyone who can read the operator’s Yokai config can recover agent tokens.
SSH connection
Section titled “SSH connection”SSH authenticates the operator to the device and carries the agent tunnel. Yokai uses configured keys, the SSH agent, and supported credential fallbacks; it does not replace SSH host policy.
Device agent
Section titled “Device agent”Every agent endpoint requires a random bearer token generated during bootstrap. The token is stored on both sides of the connection. Keep port 7474 private even though authentication is enabled.
Workload containers
Section titled “Workload containers”Containers run with the GPU, mounts, environment, IPC, shared memory, ulimits, and ports declared by the deployment. A BKC is reviewed source code, but operators should still inspect a recipe and image before running it on sensitive hardware.
Sensitive files
Section titled “Sensitive files”| Location | Sensitive content |
|---|---|
~/.config/yokai/config.json | Hugging Face token, agent tokens, SSH paths, fleet inventory |
/etc/yokai/agent.json on a device | Agent bearer token |
~/.config/yokai/daemon.log | Hosts, operational errors, and service context |
*.yokai.bak beside tool configs | Previous client configuration and possible credentials |
Yokai writes its configuration directory and file with private permissions. Preserve them when copying or backing up state.
Secrets in deployments
Section titled “Secrets in deployments”Environment variables in a service spec may reach Docker inspect output and container logs. Prefer runtime-specific secret mechanisms for high-value credentials. A Hugging Face token is necessary for gated models but should not be committed to a repository.
Network recommendations
Section titled “Network recommendations”- Keep the daemon on
127.0.0.1unless you add external authentication and transport security. - Permit SSH only from trusted identities and networks.
- Use Tailscale ACLs or equivalent private-network policy for remote devices.
- Do not expose the agent directly to the public internet.
- Limit Grafana and model endpoint exposure independently from the agent.
- Rotate an agent token after suspected config disclosure by re-bootstraping the device.
Integration backups
Section titled “Integration backups”Yokai creates .yokai.bak before changing a supported client configuration. Those backups inherit the sensitivity of the original file and should not be uploaded or committed.
Reporting a vulnerability
Section titled “Reporting a vulnerability”Avoid opening a public issue with credentials or exploit details. Contact the repository owner through an appropriate private GitHub channel and include the affected version, impact, and a minimal reproduction.