Skip to main content

Pikvm-studio Setup Detail

Documentation and system management guide for the dedicated studio KVM-over-IP appliance (pikvm-studio).

1. Video Architecture: 1080p @ 60.000 Hz Pass-Through

PiKVM V4 Plus features a built-in HDMI hardware pass-through port (OUT2) and a TC358743 HDMI-to-CSI capture bridge. By default, PiKVM V4 advertises a 1920x1200 EDID. When connected to a standard 1080p physical display, the image would be cropped from the bottom.

Applied Video Optimizations

  1. 1080p EDID Preset (No 1920x1200 Mode):
    • Imported and applied the v4plus.no-1920x1200 EDID preset to /etc/kvmd/tc358743-edid.hex via kvmd-edidconf.
    • Ensures the target host (bmo95) negotiates uncropped 1920x1080 @ 60.000 Hz for both remote web streaming and the physical monitor on OUT2.
  2. GPU Clock & H.264 60 FPS Boost:
    • Added gpu_freq=700 to /boot/config.txt to provide sufficient GPU clock headroom for full 60fps hardware H.264 encoding.
    • Configured KVMD streamer overrides in /etc/kvmd/override.yaml: 
      kvmd:
    streamer:
        h264_boost: true
        desired_fps:
            default: 60

Physical Wiring

  • HDMI Input (Rear Bottom Right): Connected to bmo95 AMD Radeon GPU HDMI output.
  • HDMI Output 2 (OUT2): Connected to the local physical studio monitor (pass-through).
  • USB-C OTG (Rear): Connected to bmo95 USB port for keyboard/mouse HID emulation and mass storage drive.
  • RJ45 Ethernet (Front): Connected to local studio LAN.

2. Configuration Management: Chezmoi

Configuration files across /etc (ext4) and /boot (FAT32) are tracked in Git using Chezmoi.

Why Chezmoi on PiKVM?

  1. FAT32 /boot Compatibility: The Raspberry Pi bootloader partition (/boot) uses a VFAT filesystem which does not support Linux symlinks. Chezmoi uses a Source $\rightarrow$ Target Copy Model, rendering physical files without symlink errors.
  2. Security & Ownership Compliance: Security-sensitive utilities (such as sudo and PAM) require configuration files to be owned by root:root with strict permissions (e.g. 0440). Chezmoi preserves exact permissions and system UIDs rather than pointing symlinks to user-owned directories.
  3. Drift Detection: chezmoi diff provides instant comparison between Git state and the live appliance filesystem.

Chezmoi Configuration

Located in /home/luke/.config/chezmoi/chezmoi.yaml:

destDir: "/"
sourceDir: "/home/luke/git/pikvm_studio"

Git History Structure

The repository at https://git.drheck.dev/luke/pikvm_studio maintains a 2-stage commit baseline:

  1. feat(pikvm): baseline vanilla system configuration — Stock OS overrides, default 1920x1200 EDID, and stock /boot/config.txt.
  2. feat(video): configure 1080p60 pass-through, H.264 boost, and GPU frequency — All active studio customizations.

Running git diff HEAD~1 clearly documents all modifications relative to factory OS defaults.

3. PiKVM Read-Only Lifecycle & Chezmoi Workflow

PiKVM OS operates with read-only root (/) and boot (/boot) partitions to protect flash storage from corruption. When managing configurations with Chezmoi, follow these standard workflows:

A. Checking for Configuration Drift

To compare the Git repository against the live system:

chezmoi diff

B. Editing and Applying Changes

To edit a tracked file and deploy it to the live system:

# 1. Remount filesystem as read-write
sudo rw

# 2. Edit the file in Chezmoi
chezmoi edit /etc/kvmd/override.yaml

# 3. Preview changes
chezmoi diff

# 4. Apply changes to disk
sudo chezmoi apply

# 5. Commit and push to GiteaForgejo
cd ~/git/pikvm_studio
git add .
git commit -S -m "feat: description of change"
gpush pikvm_studio

# 6. Return filesystem to read-only
sudo ro

C. Ingesting Modifications Made Directly on Disk

If a file was modified outside Chezmoi (e.g. via kvmd-override or kvmd-edidconf):

sudo rw
chezmoi re-add /etc/kvmd/override.yaml
chezmoi re-add /etc/kvmd/tc358743-edid.hex

cd ~/git/pikvm_studio
git add .
git commit -S -m "feat: update kvmd settings"
gpush pikvm_studio

sudo ro

4. SSH & GPG Key Management

  1. Terminal Pinentry: ~/.gnupg/gpg-agent.conf is configured with pinentry-program /usr/bin/pinentry-curses to ensure GPG password prompts display cleanly over headless SSH sessions.
  2. Password Store: GiteaForgejo API tokens (forgejo/token/*) are managed via pass and pushed using ~/bin/gpush pass.