Barrier KVM

--- name: software-barrier description: Expert guidance for managing Barrier KVM across the fleet to share a single keyboard and mouse between Spark (server) and client machines (Bots, Jarvis, Vault, Dev1). metadata: author: skynet version: 1.0.0 --- # Software Barrier Skill Barrier is an open-source software KVM that allows the sharing of a single mouse and keyboard between multiple computers. This skill provides the configuration, service management, and troubleshooting patterns specific to James's (skynet) fleet. ## Fleet Topology & Connectivity The fleet operates in a star topology with **Spark** as the central server. | Machine | Role | IP Address | OS | Service Manager | |---------|------|------------|----|-----------------| | **Spark** | Server | 192.168.86.48 | Linux | systemd (user) | | **Bots** | Client | 192.168.86.50 | macOS | launchd | | **Jarvis** | Client | 192.168.86.51 | macOS | launchd | | **Vault** | Client | 192.168.86.27 | macOS | launchd | | **Dev1** | Client | 192.168.86.22 | Linux | systemd (user) | - **Default Port:** 24800 - **Server Endpoint:** `192.168.86.48:24800` ## Configuration Locations ### Server (Spark) The server configuration defines the screen layout and hotkeys. - **Config Path:** `~/.config/barrier/barrier.conf` - **Key Sections:** - `screens`: List of all machine hostnames. - `links`: Directions (left, right, up, down) between screens. - `options`: Keyboard mapping, screen corners, and dead zones. ### Clients (macOS/Linux) Clients usually point directly to the server IP via command line arguments in the service definition. - **Linux (Dev1):** Service file at `~/.config/systemd/user/barrierc.service` - **macOS (Bots/Jarvis/Vault):** Launch Agent at `~/Library/LaunchAgents/com.github.debauchee.barrier.plist` ## Service Management ### Managing the Server (Spark) Use these commands when SSH'd into Spark: ```bash # Check status systemctl --user status barriers # Restart after config change systemctl --user restart barriers # View logs journalctl --user -u barriers -f ``` ### Managing Clients (Linux/Dev1) ```bash # Restart client systemctl --user restart barrierc # Check logs journalctl --user -u barrierc -f ``` ### Managing Clients (macOS) ```bash # Restart Barrier client launchctl bootout gui/$(id -u)/com.github.debauchee.barrier launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.github.debauchee.barrier.plist # Check logs (if redirected to file) tail -f ~/Library/Logs/barrier.log ``` ## Common Workflows ### Adding a New Machine to the Fleet 1. **Server Side:** Edit `~/.config/barrier/barrier.conf` on Spark. - Add the new hostname to the `screens` section. - Add the relationship (e.g., `new-machine is left of spark`) to the `links` section. - Restart the server: `systemctl --user restart barriers`. 2. **Client Side:** - Install Barrier: `sudo apt install barrier` (Linux) or `brew install --cask barrier` (macOS). - Create the service file/plist pointing to `192.168.86.48`. - Start the service and verify connectivity in the server logs. ### Updating Screen Layout If machines are physically moved, update the `links` section in `barrier.conf`: ```conf section: links spark: left = bots right = dev1 bots: right = spark dev1: left = spark end ``` ## Troubleshooting ### Connectivity Issues - **Check Port 24800:** Run `nc -zv 192.168.86.48 24800` from the client. - **SSL/TLS Errors:** If encryption is enabled, ensure the fingerprints match. If "failed to verify" appears, you may need to manually trust the certificate: - Linux: `~/.local/share/barrier/SSL/Fingerprints/` - macOS: `~/Library/Application Support/barrier/SSL/Fingerprints/` ### Mouse Stuck on One Screen - **Symptom:** Mouse won't transition between edges. - **Fix:** 1. Check if "Scroll Lock" is on (some configs use this to lock the cursor). 2. Verify the hostname on the client matches the hostname in the `screens` section on the server. Run `hostname` on the client to confirm. 3. Restart the server service on Spark. ### Keyboard Mapping Issues - **Symptom:** Alt/Cmd/Super keys are swapped. - **Fix:** Adjust the `screens` entry in `barrier.conf`: ```conf section: screens bots: alt = meta meta = alt end ``` ## Fleet-Specific Patterns - **Headless Operation:** All clients are configured to run as background services. Do not expect or rely on the Barrier GUI. - **SSH Fallback:** If Barrier fails, always use SSH (`ssh spark`, `ssh vault`, etc.) to debug and restart the services. - **Consistency:** Ensure `barrier.conf` is checked into the `~/infra/` directory for version control and backup. ## Installation Status Reference - **Spark (Server):** Installed via `apt`. Runs `barriers` (server binary). - **Dev1 (Client):** Installed via `apt`. Runs `barrierc` (client binary). - **Mac Minis (Clients):** Installed via `brew`. Runs `barrierc` via LaunchAgents. For deeper technical details, refer to the [Official Barrier Documentation](https://github.com/debauchee/barrier).