yobidashi

Overview

Discord control plane for the companion stack (Open-LLM-VTuber). A Rust bot (codeberg.org/yuuhikaze/yobidashi) runs on the server and drives the desktop over SSH, so companion-role members can start and stop the companion from Discord — with admin approval, a pinned live dashboard, and the startup console streamed into the channel.

flowchart LR
    subgraph DC [Discord cloud]
        CH["control channel\npinned dashboard + notices"]
    end
    subgraph SRV ["server (10.100.0.1)"]
        Y[yobidashi bot]
    end
    subgraph DSK ["desktop (10.100.0.2)"]
        C[companion command]
        U["systemd user units\ncompanion-letta, companion-tts, companion-olvt"]
    end
    Y -->|"gateway + REST\noutbound WSS/HTTPS"| CH
    Y -->|"ICMP ping, SSH\ninside WireGuard mesh"| C
    C --> U

Every connection is outbound from the machine that initiates it — nothing listens for Discord:

One-Time Setup

Everything in this section is done once per guild/server and is recorded here so it can be replayed from scratch.

Discord application

In the developer portal:

  1. Create the application.
  2. Make it private, in this order:
    1. Installation tab → set Install Link to None.
    2. Bot tab → disable Public Bot.
    Only the application owner can invite the bot from now on.
  3. Leave all privileged gateway intents off — the bot only needs the baseline GUILDS intent.
  4. Bot tab → Reset Token, copy it — it goes into the yobidashi/env sops secret (below).

Invite

Invite the bot with:

https://discord.com/oauth2/authorize?client_id=<APP_ID>&scope=bot+applications.commands&permissions=2251799813778432

The permissions integer encodes: View Channel, Send Messages, Manage Messages, Pin Messages, Embed Links, Read Message History.

Guild wiring

  1. Create the companion role. On the role’s Display tab enable Allow anyone to @mention this role (the bot mentions it in dismissal notices). Assign it to whoever may operate the companion — granting access later is a role assignment, never a config change.
  2. Restrict the control channel to that role (private channel).
  3. Add the bot itself to the channel’s permission overrides and grant it the same six permissions as the invite. A private channel’s implicit deny is not pierced by guild-level grants, so without its own override the bot cannot even see the channel. Do not give the bot the companion role or any moderation role — least privilege.

Collecting IDs

Enable Developer Mode (User Settings → Advanced → Developer Mode), then right-click and Copy ID on each of:

ID Where to right-click Goes to
Guild server name in the sidebar guildId
Channel the control channel channelId
Admin user the admin’s profile adminId
Role Server Settings → Roles → the companion role roleId

Paste them into modules/features/yobidashi.nix (settings reference under Bot Service).

Secrets

Two sops secrets, one per host:

Secret Host Contents
yobidashi/env server DISCORD_TOKEN=… (from the Bot tab)
companion/env desktop EXA_API_KEY=…, OPENROUTER_API_KEY=… (read by the companion script)

Deploy

Rebuild the desktop (installs companion, mounts companion/env, enables linger) and the server (starts yobidashi.service). On first start the bot registers /dashboard, posts the dashboard, and pins it. Verify with journalctl -u yobidashi on the server — a startup failure (bad IDs, missing channel access, invalid token) logs which step failed and exits, and systemd retries every 10 s.

Dashboard

One pinned message in the control channel is the bot’s entire persistence: on startup it adopts its own pinned dashboard or creates one, so restarts and redeploys lose nothing. The admin-only /dashboard command force-recreates it (delete the orphaned old message by hand afterwards).

States

A poller refreshes the dashboard every 30 s; operations refresh it immediately.

stateDiagram-v2
    PCSleeping: 💤 PC sleeping (gray)
    Unreachable: unreachable (red)
    state Powered {
        Asleep: 🌑 asleep (gray)
        HalfAwake: half-awake (yellow)
        Awake: 🏮 awake (green)
        Summoning: 🥁 summoning…
        Dismissing: 🍂 dismissing…
        [*] --> Asleep
        Asleep --> Summoning: summon approved
        Summoning --> Awake: READY
        Summoning --> HalfAwake: some components failed
        HalfAwake --> Summoning: summon approved
        HalfAwake --> Awake: 🔔 revive succeeds
        Awake --> HalfAwake: component dies 🌩️
        Awake --> Dismissing: dismiss approved
        HalfAwake --> Dismissing: dismiss approved
        Dismissing --> Asleep: units stopped
    }
    [*] --> PCSleeping: desktop off
    PCSleeping --> Powered: ping answers
    Powered --> PCSleeping: ping lost
    Powered --> Unreachable: ping ok, SSH fails
    Unreachable --> Powered: status call succeeds

The embed body shows one line per component — 🏮 up, 🌑 down — plus a relative “Updated” timestamp. In the PC-sleeping state the body instead says to ask the admin to wake the machine. A component dying mid-session (green → yellow on a poller tick) additionally posts a death notice in the channel.

Buttons

State 🥁 Summon 🍂 Dismiss 🔔 Revive
PC sleeping – – –
asleep ✔ – –
half-awake ✔ ✔ only dead components
awake – ✔ –
operation in flight – – –

The matrix is the security model: revive skips approval but is only ever enabled in the half-awake state, so it can resuscitate a crashed component (e.g. TTS after a GPU OOM) yet never cold-start the companion.

Flows

Companion Command

scripts/companion.sh, installed on the desktop as companion by modules/features/open-llm-vtuber.nix. Each component runs as a transient systemd user unit, so interactive and remote starts share one lifecycle — a bot-issued stop also stops a GUI-started session.

Unit Runs
companion-letta Letta memory server (podman)
companion-tts Qwen3-TTS via vllm-omni (podman, GPU)
companion-olvt Open-LLM-VTuber backend (uv, GPU ASR)
Subcommand Behavior
(none) / gui Start + kitty tabs tailing each unit’s journal
start Idempotent headless start; streams journals, exits 0 on READY
stop Stop all units (--rm cleans the containers)
status One parseable line: letta=up tts=down olvt=up
start-component <letta\|tts\|olvt> Start one unit and wait for its readiness

Readiness is measured at the HTTP endpoints (:8283, :8091/v1/models, :12393), not systemctl is-active — a unit is active long before its model finishes loading. After the TTS endpoint answers, the script fires a warmup synthesis so the first real sentence is not slow.

The script itself lives in the world-readable nix store, so its secrets come from the companion/env sops secret, mounted at /run/secrets/companion/env; COMPANION_ENV_FILE overrides the path for ad-hoc runs.

Linger is enabled for the user on the desktop so the user manager (and therefore systemd-run --user over SSH) works right after boot, before any graphical login.

Bot Service

The yobidashi flake exports nixosModules.default; modules/features/yobidashi.nix on the server is thin configuration:

Setting Meaning
guildId / channelId Discord server and control channel
adminId User whose approval gates summon/dismiss
roleId Role whose members may operate the dashboard
adminName Display name used in messages
sshTarget [email protected]

The Discord token is wired in as an EnvironmentFile from yobidashi/env; the SSH identity is the server host key via LoadCredential (reference Overview). The service runs as its own yobidashi user with Restart=always, and a failed startup exits the process rather than lingering half-connected, so systemd keeps retrying. Logs: journalctl -u yobidashi on the server; per-component logs on the desktop: journalctl --user -u companion-<letta|tts|olvt>.