Headless server

Run Kyaraben on a headless Linux server as a central sync hub. The server stores your collection and syncs with devices that run emulators locally.

Use cases:

• Home server as the primary storage for ROMs and saves
• NAS device syncing to multiple gaming machines
• Cloud VPS as a backup destination

Requirements

• x86_64 Linux (no GUI needed)
• systemd user services support
• Sync ports accessible (see Syncthing’s firewall documentation)

Port numbers

Kyaraben uses different ports than default Syncthing:

• TCP 22100 (sync traffic, default is 22000)
• UDP 21127 (local discovery, default is 21027)

If you have existing Syncthing firewall rules, update them accordingly.

Installation

Download the CLI binary from GitHub releases:

curl -fsSL https://github.com/fnune/kyaraben/releases/latest/download/kyaraben-cli-linux-amd64 -o kyaraben
chmod +x kyaraben
sudo mv kyaraben /usr/local/bin/

Setup

Initialize a headless configuration:

kyaraben init --headless --collection /path/to/emulation

This creates ~/.config/kyaraben/config.toml with:

[global]
collection = "/path/to/emulation"
headless = true

[sync]
enabled = true

Apply the configuration:

kyaraben apply

This creates the full directory structure for all systems and installs Syncthing, but does not install any emulators.

Persistence

Enable user services to run without an active login session:

loginctl enable-linger $USER

This allows Syncthing to keep running after you disconnect from SSH.

Pairing devices

Generate a pairing code on the server:

kyaraben sync pair

On your desktop or Steam Deck, enable synchronization and enter the code.

If the pairing code doesn’t work (requires Syncthing relay access), use the device ID directly:

kyaraben sync pair --device-id
# Copy the full ID and enter it on the other device

Managing files

Place ROMs directly in the collection:

cp game.chd /path/to/emulation/roms/psx/

The directory structure follows Kyaraben’s collection layout. Files sync automatically to paired devices.

Monitoring

Check sync status:

kyaraben sync status

This shows whether sync is running, connection status, paired devices, synced folders, and any connectivity warnings.

If sync shows “not running”, check the Syncthing service:

systemctl --user status kyaraben-syncthing

Access the Syncthing web UI at http://server-ip:8484 for detailed monitoring.

Updating

Keep the CLI up to date:

kyaraben update

Remote syncing

By default, Kyaraben syncs devices on the same local network. For syncing across different networks (e.g., a cloud VPS or a home server accessed remotely), you need to enable global discovery.

Global discovery announces your device to Syncthing’s discovery servers, allowing devices to find each other’s IP addresses across the internet. Without it, devices can only locate each other on the same LAN.

Add to your config:

[sync.syncthing]
global_discovery_enabled = true
relay_enabled = true

With both settings enabled:

• Global discovery lets devices find each other
• Relays transfer data when direct connections aren’t possible

Untested

Remote syncing with global discovery should work but hasn’t been tested end-to-end. If you encounter issues, please report them.

Troubleshooting

Service not starting after reboot

Verify linger is enabled:

loginctl show-user $USER | grep Linger

Check service status:

systemctl --user status kyaraben-syncthing