LinkSy-mg/linksy-desktop技術ドキュメント

On the computer, one line finds your system and desktop, asks which app you want, and installs it with one password:

curl -fsSL https://linksy.diary.mg/install.sh | sh

Or by hand, from linksy-releases (linux-v… releases; its README has the commands for each distribution):

On the phone, install the latest .apk from linksy-releases, open Linksy on both, and pair: both screens show the same code.

• A page for each phone. Use As, Inbox, Gallery, Files, Transfers, History and Settings, in tabs, with how it's connected and its battery at the top.
• Messages. The phone's chats, texts and mail in one Inbox, made from its notifications: WhatsApp, Telegram, Signal, the SMS app, Gmail and others. Answer from the computer where the app allows it; codes that arrive are copied for you. Nothing is kept on disk.
• Photos and files. The phone's photos and videos by album, saved to Pictures in a click, and a file manager for the folder it shares: copy both ways, rename, delete.
• Deck. The phone as a deck of buttons for the computer: media, volume, microphone, sound output, lock, Do Not Disturb, Wi-Fi, Bluetooth, power modes, restart, and your own commands. Build it on the computer, on a phone drawn true to size, in five looks (the editor is in the GTK app for now).
• Share. Files and folders both ways, resumable and checked; the clipboard (text, images, small files), automatically where the desktop allows; notifications. "Send with Linksy" in Files, Dolphin and Thunar.
• Use the phone as a second display for the computer, a webcam ("Linksy Camera" in every app, with the phone's camera controls) or a microphone ("Linksy Microphone").
• Screens. Watch another device's screen and take control of it, each asked for separately. A phone on the USB cable can be controlled from the computer with no developer options.
• Terminal. The computer's shell on the phone, behind a code set on the computer, allowed per phone.
• Find your phone. Ring it, loud even on silent, or locate it on a map: asked once, never tracked.
• Away from home. Paired devices still reach each other over the internet for a week after they last met on the same network. Screens, files, camera and microphone stay local unless allowed per device.
• Every desktop. GNOME, KDE Plasma, Hyprland, Sway, niri, X11 desktops and more (docs/desktop-support.md), a tray icon, Update Now.

With no window open, Linksy is one small process (about 20 MB of memory, no CPU when idle).

• Identity. Each device makes a self-signed certificate on first run. Its SHA-256 fingerprint is the device id. There is no central authority.
• Presence. Devices advertise _linksy._udp.local. over mDNS and re-check every 45 s that the devices they see are still there. That's all that happens while idle.
• Connect on demand. Sending something dials the device at every address known for it (announced ones and the last one that worked) in parallel. A connection with nothing going on closes after a minute. "Stay connected" in Preferences keeps links open instead, for the lowest latency on mains power.
• Pairing. Both screens show a 6-digit code derived from the encrypted session, and both users confirm it. A device in the middle would see a different code.
• Transport. QUIC (TLS 1.3, mutual authentication). Each transfer or message gets its own stream on the connection, so a large file never blocks a notification.
• Transfers. Files are streamed from disk with a BLAKE3 check per file. Interrupted transfers resume, and a file only appears once its checksum matches.
• Consent. Pairing always asks both users. Incoming files ask first, in the app or through a desktop notification with Accept/Decline buttons, unless "Accept From Paired Devices" is on.

Front ends come and go; the service does the work. docs/protocol.md is the exact wire protocol, and the handoff for the Android app.

You only need this to change the code. To use Linksy, see Install.

Rust stable (edition 2024). The service, CLI and core build anywhere:

cargo build --release      # linksyd + linksy
cargo test                 # unit + end-to-end tests

To leave away from home out entirely (no relay code, nothing past the local network and the cable), build the service with cargo build --release -p linksyd --no-default-features.

The GTK app and the screen helper need GTK ≥ 4.14, libadwaita ≥ 1.5 and GStreamer ≥ 1.22 headers:

sudo dnf install gtk4-devel libadwaita-devel gstreamer1-devel gstreamer1-plugins-base-devel   # Fedora
sudo apt install libgtk-4-dev libadwaita-1-dev libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev
sudo zypper install gtk4-devel libadwaita-devel gstreamer-devel gstreamer-plugins-base-devel   # openSUSE
cargo build --release -p linksy-app -p linksy-screen

At run time, screen mirroring uses GStreamer plugins: pipewiresrc (pipewire-gstreamer), an H.264 encoder (VA-API, x264 or OpenH264), an H.264 decoder (libav, VA-API or OpenH264) and gtk4paintablesink (gstreamer1-plugin-gtk4).

Without root, a toolbox works: toolbox create linksy-dev, then toolbox run -c linksy-dev sudo dnf install -y gtk4-devel libadwaita-devel gcc, then build with toolbox run -c linksy-dev cargo build -p linksy-app.

linksy-qt is a second window on the same service, in Qt 6 and Kirigami, for Plasma. It needs Qt 6 (base and declarative), Kirigami, Kirigami Addons and KDE's desktop style, and the lld linker:

sudo dnf install qt6-qtbase-devel qt6-qtdeclarative-devel kf6-kirigami kf6-kirigami-addons kf6-qqc2-desktop-style lld
QMAKE=qmake6 cargo build -p linksy-qt

Without root, packaging/qt/Containerfile is that environment in a container (its header says how), and scripts/qt-shot.sh renders the app in it against two test services.

scripts/install-local.sh   # installs to ~/.local and enables the user service
linksy-app                 # the app
linksy devices             # or the CLI
linksy pair "Other Laptop"
linksy send "Other Laptop" ~/Pictures/photo.jpg
linksy clip "Other Laptop" "some text"
linksy settings auto-accept on

Or run without installing: cargo run -p linksyd in one terminal, then cargo run -p linksy -- devices.

• scripts/ui-scene.sh <dir> starts two local services ("This Laptop" and "Studio Desktop") and pairs them. Point the app or CLI at one with LINKSY_SOCKET=<dir>/a.sock.
• scripts/ui-shot.sh <socket> <out.png> [delay-ms] [light|dark] [files…] renders the app on a headless Wayland compositor (weston, inside the toolbox) and saves a screenshot. Nothing appears on screen.

Screenshots are in docs/screenshots/.

Add the version's section to CHANGELOG.md and the metainfo's <releases>, bump version in Cargo.toml, commit, and run scripts/publish-release.sh. It tags vX.Y.Z and pushes it; GitHub (the Packages workflow) builds every package and the Flatpak, installs the packages on every supported distribution, and when all of that passes publishes the release here and, as linux-vX.Y.Z (not marked latest, which belongs to the Android APKs), on linksy-releases. Flathub builds from the tag with packaging/flatpak/mg.diary.linksy.Linksy.yml. scripts/package-linux.sh and scripts/package-flatpak.sh still build everything locally, to try a package.

What's next is in ROADMAP.md.

Bug reports, translations and pull requests are welcome: see CONTRIBUTING.md. If Linksy helps you, a star or telling a friend helps it reach more people.

Linksy is open source under the GNU Affero General Public License v3.0 or later. The open-source libraries it builds in are credited, with their licenses, in THIRD-PARTY-NOTICES; regenerate it with scripts/third-party-notices.py > THIRD-PARTY-NOTICES after Cargo.lock changes.