Configuration

Yokai stores durable state in ~/.config/yokai/config.json, or under $XDG_CONFIG_HOME/yokai/config.json when XDG_CONFIG_HOME is set. Writes are atomic and the file is created with private permissions.

Current schema

{
  "version": 1,
  "hf_token": "hf_...",
  "daemon": {
    "listen": "127.0.0.1:7473",
    "metrics_poll_interval_s": 2,
    "reconnect_interval_s": 30
  },
  "devices": [
    {
      "id": "gpu-box-01",
      "label": "GPU box 01",
      "host": "100.64.0.2",
      "ssh_user": "ubuntu",
      "ssh_key": "~/.ssh/id_ed25519",
      "ssh_port": 22,
      "connection_type": "tailscale",
      "agent_port": 7474,
      "agent_token": "<generated-token>",
      "monitoring_installed": true,
      "gpu_type": "nvidia",
      "tags": ["rtx-4090"]
    }
  ],
  "services": [
    {
      "id": "vllm-llama31",
      "device_id": "gpu-box-01",
      "type": "vllm",
      "image": "vllm/vllm-openai:latest",
      "model": "meta-llama/Llama-3.1-8B-Instruct",
      "port": 8000,
      "gpu_ids": "all",
      "extra_args": "--max-model-len 8192",
      "plugins": [],
      "runtime": {
        "ipc_mode": "host",
        "shm_size": "16g",
        "ulimits": { "memlock": "-1" }
      }
    }
  ],
  "preferences": {
    "theme": "tokyonight",
    "default_vllm_image": "vllm/vllm-openai:latest",
    "default_llama_image": "ghcr.io/ggml-org/llama.cpp:server-cuda",
    "default_comfyui_image": "spencerbull/yokai-comfyui:latest"
  }
}

Precedence and environment

Variable	Effect
XDG_CONFIG_HOME	Changes the base configuration directory
HF_TOKEN	Preferred Hugging Face token source
HUGGING_FACE_HUB_TOKEN	Secondary Hugging Face token source
YOKAI_DAEMON_URL	Points the TUI at a specific daemon URL
YOKAI_PLUGIN_DIR	Overrides the model-plugin asset directory

An environment-provided Hugging Face token takes precedence over hf_token in the file.

CLI editing

Use the CLI for safe inspection and common changes:

yokai config path
yokai config show
yokai config set daemon.listen 127.0.0.1:7473
yokai config set daemon.metrics_poll_interval_s 3
yokai config set preferences.theme dark

config show redacts agent and Hugging Face tokens. Restart or reload the daemon after a manual edit:

curl -X POST http://127.0.0.1:7473/reload

Other local state

• ~/.config/yokai/history.json stores recent deploy images and models.
• ~/.config/yokai/daemon.log records background daemon output.
• integration writers create a .yokai.bak file before changing a supported tool configuration.

Treat config.json and its backups as secrets because device bearer tokens may be present.