---
name: "Barrier KVM"
description: "Fleet skill: Barrier KVM — software inventory and operations reference"
version: "1.0.0"
author: "skynet"
category: "fleet"
agents: ["claude-code", "codex", "gemini", "kimi"]
tags: ["software-barrier", "fleet", "fleet", "software"]
---

# 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).