lfsv

CLI tool to connect directly to any LoverCraft game server via tmux — no need to look up which machine it's on.

lfsv megasurvival/zone1   # SSH to the right machine and attach to the tmux session
lfsv --list               # list all servers from velocity.toml
lfsv --machine prison     # just show which machine hosts a server

Tab completion is included for zsh.

---

How it works

lfsv reads the [servers] block from Velocity's velocity.toml, maps each server name to its host machine using the last octet of the IP address (10.0.0.N → lfN), SSHs to that machine, and runs tmux attach-session.

---

Requirements

• zsh (for tab completion)
• tmux on the game servers
• SSH access to the lf* hosts
• Velocity proxy with a velocity.toml

---

Install

git clone https://github.com/lovercraftllc/lfsv.git
cd lfsv
./install.sh

The installer places:

• lfsv → ~/.local/bin/lfsv
• completions/_lfsv → ~/.zfunc/_lfsv

Custom paths:

BIN_DIR=/usr/local/bin COMP_DIR=/usr/share/zsh/site-functions ./install.sh

---

Configuration

1. Set LF_VELOCITY_TOML

Add to your ~/.zshrc (or ~/.bashrc):

export LF_VELOCITY_TOML=/path/to/velocity/main/velocity.toml

2. Configure SSH hosts

Add your game server hosts to ~/.ssh/config. The host name must follow the lfN pattern, where N matches the last octet of the server's IP in velocity.toml.

# Default user for all lf* hosts
Host lf*
  User debian
  IdentityFile ~/.ssh/id_ed25519

# lf1
Host lf1
  HostName <public-ip>

# lf2
Host lf2
  HostName <public-ip>

# lf3 — uses a different login user
Host lf3
  HostName <public-ip>
  User source

# ... repeat for lf4–lf14

Note: lf3 uses a special login flow: it connects as the source user, then runs sudo su debian before attaching to tmux. This is handled automatically by lfsv.

3. SSH key passphrase

The recommended approach on macOS is to store the passphrase in the keychain once:

ssh-add --apple-use-keychain ~/.ssh/id_ed25519

Alternatively, set LF_SSH_PASS in your environment and lfsv will unlock the key automatically on first use:

export LF_SSH_PASS=your-passphrase

---

Environment variables

Variable	Required	Default	Description
LF_VELOCITY_TOML	yes	—	Path to velocity.toml
LF_SSH_KEY	no	~/.ssh/id_ed25519	Path to SSH private key
LF_SSH_PASS	no	—	Key passphrase (prefer ssh-agent)
LF_LF3_USER	no	source	SSH user for lf3

---

Tab completion (zsh)

The installer patches your .zshrc automatically. If you installed manually, add:

fpath=(~/.zfunc $fpath)
autoload -Uz compinit && compinit

Then reload your shell:

source ~/.zshrc

---

velocity.toml format

lfsv expects the standard Velocity [servers] block:

[servers]
"megasurvival/zone1" = "10.0.0.12:21101"
"skyblock/spawn1"    = "10.0.0.5:22001"
prison               = "10.0.0.4:26001"

The IP's last octet determines the machine: 10.0.0.12 → lf12.