Localynk — Secure Local Network← Back to website

BuildFix9 documentation

Localynk Headless on Proxmox.

A practical deployment and recovery guide for Debian 13 LXC, persistent storage, Web Admin, pairing, backups, upgrades and the problems you are most likely to encounter.

01 · Architecture

Recommended Proxmox layout

Run Localynk Headless in an unprivileged Debian 13 LXC. Keep the application and database on the container root disk, and bind-mount large file storage from the Proxmox host into /srv/localynk-storage.

ResourceNormal LAN useHeavier concurrent transfers
CPU1 core2 cores
RAM1 GB2 GB
Swap512 MB1 GB
Root disk8–16 GB16 GB+
Networkvmbr0 + DHCP/static LAN IPSame
Headless is Qt-free. You do not need PySide6 or a desktop environment inside the LXC.

02 · Create the LXC

Start with Debian 13.

  1. Download a Debian 13 standard CT template in Proxmox.
  2. Create an unprivileged container.
  3. Use bridge vmbr0.
  4. Assign DHCP or a reserved/static address.
  5. Start the CT and open its console.
apt update && apt upgrade -y apt install -y unzip curl ca-certificates ip addr ping -c 3 1.1.1.1

If IP works but package downloads fail, check DNS with getent hosts deb.debian.org and confirm the CT has a valid nameserver.

03 · Install

Use the Proxmox installer.

Extract the BuildFix9 source package inside the LXC, then run the dedicated installer:

cd /root/Localynk-Desktop-Client-Server-Headless-RC14-BuildFix9-ProductionAudited chmod +x proxmox/*.sh ./proxmox/INSTALL-PROXMOX.sh

The production deployment path installs pinned dependencies, performs dependency integrity checks, installs localynk.service, enables scheduled database backups and performs a health verification. BuildFix9 also attempts application rollback if activation fails health verification.

Verify immediately

localynk-ctl status localynk-ctl health localynk-ctl ip journalctl -u localynk -n 100 --no-pager

04 · First run

Protect Web Admin first.

From another machine on the same LAN, open http://SERVER-IP:8742/admin. Create the administrator password, sign in, enroll TOTP 2FA, verify a six-digit code and save the recovery codes outside the Localynk server.

Do not expose port 8742 directly to the public Internet. Use a trusted LAN, Tailscale or another private VPN.

05 · Storage

Bind-mount large storage cleanly.

On the Proxmox host, mount the physical disk first. Then use the included helper so the LXC receives it at /srv/localynk-storage.

# On the Proxmox HOST lsblk -f mkdir -p /mnt/localynk-storage mount /dev/sdX1 /mnt/localynk-storage # Then from the BuildFix9 proxmox folder ./HOST-MOUNT-HDD.sh 120 /mnt/localynk-storage pct exec 120 -- ls -lah /srv/localynk-storage

Replace CT ID 120 and the disk path with your real values.

Backup warning: a Proxmox bind mount is separate storage. Do not assume the contents are protected by the container’s normal root-disk backup. Back up the shared HDD separately.

If the folder is visible but not writable

# Inside LXC id localynk ls -ld /srv/localynk-storage sudo -u localynk touch /srv/localynk-storage/.localynk-write-test

If the touch fails, fix host-side ownership/mapping or rerun the supplied HDD helper instead of making the folder world-writable.

06 · Firewall

Allow what Localynk actually uses.

PortProtocolPurpose
8742TCPAPI, Web Admin, Web Client, file transfer
8743UDPLocalynk LAN discovery
5353UDPmDNS / Zeroconf

BuildFix9 includes proxmox/FIREWALL-UFW.sh. If you use SSH, allow SSH before enabling UFW.

apt install -y ufw ufw allow OpenSSH ./proxmox/FIREWALL-UFW.sh ufw status verbose

07 · Pair devices

Approve first, grant second.

  1. Open the Android or Desktop client.
  2. Discover Localynk automatically, or manually enter the server IP and port 8742.
  3. Submit the pairing request.
  4. Open Web Admin → Devices and approve it.
  5. Grant Browse / Download / Upload / Delete only where needed.

If the phone connects but a shared folder is missing, open the device’s share permissions and confirm Browse is enabled for that share. BuildFix9 retains the late-created-share permission tooling introduced earlier in RC14.

08 · Backups

Back up metadata and files separately.

localynk-ctl backup systemctl status localynk-backup.timer systemctl list-timers | grep localynk ls -lah /var/lib/localynk/backup-snapshots/

The Localynk backup protects the SQLite database and server state. Your actual files in /srv/localynk-storage need their own backup plan (another disk, NAS, rsync, ZFS snapshot strategy, etc.).

09 · Upgrade

Upgrade without deleting state.

Back up first, extract the new release into a new source directory, then run its proxmox/INSTALL-PROXMOX.sh. Keep /var/lib/localynk and /srv/localynk-storage intact. BuildFix9’s deployment logic keeps a previous application tree for rollback when a new activation fails health verification.

localynk-ctl backup # extract the new release, then: ./proxmox/INSTALL-PROXMOX.sh localynk-ctl health

10 · Troubleshooting

Fast problem map

Service will not start

Run systemctl status localynk and journalctl -u localynk -n 150 --no-pager. Check port conflicts with ss -ltnp | grep :8742.

Web Admin will not open

Confirm localynk-ctl health, then test curl http://127.0.0.1:8742/api/v2/health inside the CT. If local works, inspect firewall/routing.

Discovery fails

Manual IP + port 8742 should still work. Check UDP 8743/5353 and whether the client is on the same broadcast domain.

Share missing on phone

Check Web Admin → Devices → permissions and ensure Browse is granted for that share.

Upload returns 413

The configured maximum upload size was exceeded. Change the server limit intentionally; do not disable the protection blindly.

Upload returns 507

Free disk reserve or share quota is insufficient. Check df -h and the configured share quota.

HDD read-only

Check unprivileged UID/GID mapping and host mount state. Do not solve it with chmod -R 777.

Lost 2FA

Use a recovery code or run localynk-ctl reset-2fa from the server console.

Collect the first diagnostics

localynk-ctl status localynk-ctl health localynk-ctl ip systemctl status localynk --no-pager journalctl -u localynk -n 150 --no-pager ss -ltnup | grep -E '8742|8743|5353' df -h free -h

11 · Emergency commands

Commands worth remembering.

localynk-ctl status localynk-ctl health localynk-ctl logs 100 localynk-ctl follow localynk-ctl restart localynk-ctl backup localynk-ctl reset-2fa localynk-ctl ip
Still stuck? Save the command output above before changing anything. The logs usually identify whether the failure is service startup, permissions, storage, networking or configuration.