Quick Start

This path uses the OpenTUI and a Best-Known Config (BKC). It is the fastest way to move from a new install to a running inference endpoint.

1. Launch Yokai

yokai

On launch, Yokai creates ~/.config/yokai/config.json when needed, checks the daemon at 127.0.0.1:7473, starts it if it is not healthy, and opens the compiled terminal interface.

The four primary routes are:

Route	Purpose
Dashboard	Fleet health, services, details, actions, and logs
Devices	Device inventory, SSH/Tailscale import, tests, and upgrades
Deploy	Workload, device, model, BKC, memory estimate, and review
Settings	Theme, Hugging Face, defaults, integrations, and endpoints

2. Add a device

Open Devices with 2, press A, and choose a source:

• SSH config imports aliases and connection details from ~/.ssh/config;
• Tailscale lists peers from tailscale status --json and highlights tag:ai-gpu;
• Manual accepts a host, port, user, and key directly.

Yokai tests the connection, performs preflight checks, copies the agent, installs its systemd service, and offers to provision monitoring.

For a dedicated compute server, follow Tailscale GPU Nodes to define and apply tag:ai-gpu. The tag adds Yokai’s AI GPU badge but does not grant network or SSH access.

3. Add a Hugging Face token when needed

Open Settings with 4, then press H. A token is required for gated repositories and may be provided either through Settings or through HF_TOKEN / HUGGING_FACE_HUB_TOKEN.

4. Deploy a model

Open Deploy with 3:

1. choose vllm, llamacpp, or comfyui;
2. select the target device;
3. search Hugging Face or enter a model ID;
4. press B on the config step to apply a matching BKC;
5. optionally press M to run the vLLM memory estimator;
6. review the image, ports, GPUs, flags, and runtime settings;
7. deploy.

The daemon sends the normalized deployment to the remote agent, which pulls the image and creates the Docker container.

5. Verify the service

Return to Dashboard with 1. Select the service with J / K, then press Enter to open its inspector. From the detail view you can test, restart, stop, remove, or open logs.

For vLLM and llama.cpp services, the dashboard and Settings page expose the local tunneled OpenAI-compatible endpoint.

6. Connect a coding tool

Open Settings, toggle one or more integrations, then press C. Yokai makes a backup before editing an existing tool configuration.

Scriptable equivalent

The non-TUI CLI emits JSON:

yokai devices add --host gpu-box-01 --ssh-user ubuntu --ssh-key ~/.ssh/id_ed25519
yokai devices bootstrap gpu-box-01
yokai services deploy --device gpu-box-01 --type vllm \
  --model meta-llama/Llama-3.1-8B-Instruct
yokai status

See CLI Commands for every flag.