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:
10.100.0.0/24), authenticating with the server’s host
key (declared as sshHost.pubkey in
values/network-details.nix, present in every host’s
authorized_keys). The key never leaves the server; systemd
hands it to the bot via LoadCredential.Everything in this section is done once per guild/server and is recorded here so it can be replayed from scratch.
In the developer portal:
Install Link to
None.Public Bot.GUILDS intent.Reset Token, copy it — it goes into the
yobidashi/env sops secret (below).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.
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).
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) |
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.
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).
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.
| 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.
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.
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>.