Skip to content

Getting Started

Michael Riddle edited this page Aug 26, 2026 · 3 revisions

Getting Started

Prerequisites

  • .NET 10 SDK — KHost runs from source; the SDK builds it on first run.
  • Node.js 18+ and npm — the build stages vendor scripts from node_modules.
  • FFmpeg on PATH — the host transcodes each song to HLS for the screens. A custom install can be pointed to via the FFmpegPath setting or the FFMPEG_PATH environment variable.

Contributor tooling is listed in Development.

Run from source

# 1. Clone
git clone https://github.com/riddlemd/KHost.git
cd KHost

# 2. Restore .NET dependencies
dotnet restore KHost.slnx

# 3. Install the UI's npm packages
cd src/KHost.UserInterface && npm install && cd ../..

# 4. Run
dotnet run --project src/KHost.UserInterface

The host opens in its own window and listens on http://localhost:5251. Screens are launched from the Screens dialog in the toolbar — the host injects its own address into each screen it starts.

A build that fails on npm run copy:vendors means node_modules is missing: run npm install inside src/KHost.UserInterface/ and retry.

First run

A setup wizard at /setup walks through four steps: choosing whether the console requires sign-in, creating an admin user (skipped when sign-in is off), configuring the first venue, and importing an initial media library. With sign-in required, the console then asks for the admin credentials — see Users and Permissions.

Runtime files on disk

Location Contents
./cache/*.json Queue and venue state (the queue survives restarts), the last signed-in username, and the settings overlay written by App Settings.
./cache/khost.db SQLite song library, created on first run.
./logs/*.log Daily-rolling logs; entries older than 7 days are pruned at startup.
./plugins/<id>/ Installed plugins, one folder each. See Plugins.
./plugins-staging/ Plugin payloads waiting to be applied on the next start, and pending removals. A sibling of plugins/, never a child.

Paths are relative to the host binary (src/KHost.UserInterface/bin/Debug/net10.0/ when run from source). Deleting bin/ deletes the library, users, queue, and installed plugins.

Clone this wiki locally