@skyglide.com/rustapp

Skyglide for desktops and servers. Skyglide gives each member a private network for their devices: at a participating location the Wi-Fi puts a device into it, and everywhere else a Skyglide client does. This repository holds the clients written in Rust:

  • skyglided, the service. It runs with the privileges a tunnel needs, holds the device's private key, runs a standard WireGuard tunnel to the Skyglide cloud, and applies routes and DNS.
  • skyglide, the command-line client for servers and desktops. It controls the service over a local socket; every command takes --json.
  • skyglide-desktop, the tray app for Mac, Windows and Linux: a tray menu and a window (egui) that control the same service.
  • skyglide-home and skyglide-venue, the agents on OpenWrt routers: skyglide-home on a member's own router at home (home LAN access, the home connection as internet exit, home addresses), skyglide-venue on a venue's GL.iNet Flint 2 (both Wi-Fi networks, members' networks, the guest network, the site tunnel). They are packaged, with their LuCI apps, in skyglide.com/openwrt.

The iPhone and iPad app lives in skyglide.com/swiftapp, the Android app in skyglide.com/androidapp, the public site in skyglide.com/landingpage.

Unified OpenWrt runtime

The single skyglide package embeds the supervisor and both role engines. Mainapp assigns the role and configuration; the local page only onboards and shows status. New venue operation uses owned kernel interfaces, private hostapd and DHCP processes, and a native Rust captive gateway. It does not install PHP or openNDS.

Wi-Fi uplinks protect their stations and hardware radio masks, including configured stations that are reconnecting. Independent radios within one wiphy require disjoint masks. A qualified shared AP follows the live uplink channel and beacon interval; its guard stops only owned APs when that snapshot changes. No global netifd or vendor Wi-Fi reload is used by the supervisor. Unknown radio ownership withholds changes. Mainapp receives only interface/radio/band/connectivity and reserved/free radio metadata, never upstream Wi-Fi names or credentials.

A full hostapd build and an AP/VLAN-capable driver are required for per-password member isolation. On the Beryl 7's OEM 4.9.0 firmware, an isolated static AP/VLAN probe failed with EOPNOTSUPP; its repeater route/interface and configuration hashes stayed unchanged. This qualifies a limitation of that driver path, not the hardware or upstream mt76. Vendor alternatives remain unqualified. Official upstream OpenWrt 25.12.6 is a separate migration/physical qualification.

The native captive gate binds HTTP only to the guest gateway and DNS to its own port. Guests need an owned DHCP lease and matching bridge neighbour. Grants expire in the kernel within 30 seconds without refresh; rate-limited grants are withheld unless shaping is verified. The cloud signup and allowed sign-in/payment hosts must be reachable on HTTPS443. Existing fw4 flow offloading is preserved and causes a refusal because it can bypass later grant revocation.

Opt-in real packet tests require a marked disposable OpenWrt VM (portal_kernel_tests.rs); they cover both firewall backends. Never run these tests on a host or physical router. Home-address proxy leases remain refused by the native home runtime until their lifecycle is implemented.

Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit community.foss.global/. This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a code.foss.global/ account to submit Pull Requests directly.

State

The desktop clients and router engines share native configuration types. Mainapp supplies the contracts of both, generated into Rust:

  • Built and tested on Linux: the service's state machine, the device key, the userspace WireGuard data path, routes for "private network only" and "Internet through Skyglide", location detection, removal and restriction handling, the local socket with its access check, the command-line client, and the tray app's window and tray menu.
  • Desktop controller integration: skyglided signs in with a code the member confirms on the controller's /device page (skyglide login, the app's "Sign in with your browser"), enrols with a join key, follows the controller's pushes, asks where it is, lists the member's devices, renames itself, chooses its internet exit, renews its key (every 90 days, or skyglide key rotate) and leaves the network (skyglide logout). Tested against the controller's preview and, with the tunnel, its end-to-end hub. A development file can stand in for the controller (below).
  • Router agents: rendering and applying their OpenWrt configuration, idempotently and only in Skyglide's own UCI sections, the JSON interface for LuCI, pairing with a join key, and venue observations are built and tested against OpenWrt 24.10's own uci in its rootfs. The unified supervisor now pairs, fetches configuration and reports checks through generated mainapp contracts; measuring the home exit's use, DHCP relay for home addresses at venues, and vouchers (issued by the cloud) are not built. Per-member Wi-Fi passwords and VLANs are checked as UCI only, not yet on a Flint.
  • macOS: everything builds, lints and passes its tests on a Mac, and ci/macos/build.sh builds the installer package (universal binaries, the menu bar app, the launchd service). The tunnel, its routes and DNS on a Mac are covered by ci/macos/e2e.sh, which needs root on a real Mac; the tray app has not yet run in a Mac's GUI session. On a Mac, members choose between this app and the Skyglide app from the App Store; only one of them connects at a time.
  • Not built yet: the Windows named pipe, service and routes. Nothing has run on Windows yet. The kernel WireGuard path (Linux) is built but untested.

How it works

A device away from a location is one WireGuard peer of the Skyglide cloud, with a fixed address in its member's away subnet. By default only the member's private network and its DNS go through the tunnel; with Internet through Skyglide all traffic does, IPv6 included, and the cloud inspects it. After every network change the service asks the controller where the device is: when the answer names the device's own member network (it is on skyglide.com at a location), the tunnel stays idle. A Wi-Fi name alone never idles the tunnel.

Build

Rust 1.95 (see rust-toolchain.toml).

cargo build -p skyglided -p skyglide-cli -p skyglide-desktop

The router agents are static musl binaries for OpenWrt's architectures: aarch64 (the GL.iNet Flint 2), 32-bit ARM, MIPS, i586 and x86_64. With the musl cross compilers x86_64-linux-musl-gcc and aarch64-linux-musl-gcc on PATH (jemalloc compiles C), the default build covers x86_64 and aarch64; other architectures take an OpenWrt SDK's compiler through SKYGLIDE_CC_<TARGET> (see the script's header; skyglide.com/openwrt builds the whole matrix that way):

ci/router/build.sh            # target/router-dist/<triple>/skyglide-home and skyglide-venue, stripped

On Linux the tray app needs libxkbcommon-x11 at run time and a StatusNotifierItem host (KDE, most desktops; GNOME with the AppIndicator extension).

macOS

The Mac package installs the tray app as a menu bar app (/Applications/Skyglide.app), the command-line client (/usr/local/bin/skyglide) and the service (/usr/local/libexec/skyglided, a launchd daemon), creates the skyglide group and adds the user at the screen to it. sudo /usr/local/libexec/skyglide-uninstall [--keep-state] removes everything again.

Build it on a Mac with Xcode and rustup's aarch64-apple-darwin and x86_64-apple-darwin targets:

ci/macos/build.sh   # <target>/macos/Skyglide-<version>.pkg, universal, signed ad hoc

With SKYGLIDE_APP_IDENTITY and SKYGLIDE_INSTALLER_IDENTITY (Developer ID Application and Installer) it signs with the hardened runtime, and with SKYGLIDE_NOTARY_PROFILE (a notarytool keychain profile) it notarizes and staples the package.

On a Mac the service sets DNS up itself: a resolver file in /etc/resolver sends the member network's names through the tunnel, and Internet through Skyglide points every network service's DNS at the cloud, keeping the previous settings in the state directory until the tunnel stops (or the next start after a crash). While the Skyglide app from the App Store has its tunnel up, the service pauses its own (state other_app) and says so; it connects again when the other app disconnects.

Use

Install and start the service, then let your user control it:

sudo skyglide service install
sudo usermod -aG skyglide "$USER"                      # Linux
sudo dseditgroup -o edit -a "$USER" -t user skyglide   # macOS (install adds the installing user itself)

The service talks to the Skyglide controller at https://app.skyglide.com unless it is started with --controller <origin> (skyglide service install --controller <origin> writes that into the service definition).

Sign a desktop in with skyglide login: it shows a code to confirm at the controller's /device page on any device, and finishes on its own. Then skyglide status, skyglide up [--internet | --private-only], skyglide down, skyglide devices, skyglide ip, skyglide ping <device>, skyglide netcheck, skyglide rename <name>, skyglide exit [<exit> | --network], skyglide key rotate and skyglide logout [--local]. A server enrols with a join key from the member portal, read from a file (mode 0600) or standard input, never from the command line:

skyglide up --join-key-file /etc/skyglide/join.key --name build-server

skyglide devices --json answers {"devices": [...], "cached": …}, each device with online.

Development without a controller

skyglided --dev-config <file> takes the device configuration from a TOML file instead of the controller and reads it again on every refresh, so editing it acts like a push from the controller:

[device]
network = "net_alice"
device_name = "build-server"
address_v4 = "10.42.0.9"
private_prefixes = ["10.42.0.0/24", "10.42.1.0/24"]
dns = ["10.42.0.1"]

[device.hub]
endpoint = "hub.example.net:51820"
public_key = "<the hub's WireGuard public key>"

# optional: what the controller answers to "where am I?"
[location]
network = "net_alice"
site = "Location A"

Set removed = true at the top to act out a removal in the member portal, billing = "restricted" under [device] for a restricted membership.

Router agents

On an OpenWrt router (packaged in skyglide.com/openwrt, which also runs them under procd):

skyglide-home status --json
skyglide-home pair --join-key-file /tmp/join-key         # a file only its owner can read, or - for stdin
skyglide-home set --share-lan on --offer-exit on --home-addresses off
skyglide-venue apply --desired /tmp/desired-venue.json   # until the controller sends it
skyglide-venue status --json                             # counts only, never a device or a person

--uci-confdir <dir> works on a scratch copy of /etc/config without reloading anything; --dev-config <file> stands in for the controller (examples/home-config.json, examples/desired-venue.json).

Test

cargo test --workspace

ci/e2e/run.sh tests the data path in Docker against an independent WireGuard hub (boringtun-cli): connection, reachability both ways, forged source addresses, location detection, Internet through Skyglide, switching off, removal. ci/shots.sh takes screenshots of the tray app's window against a running service and reads its tray menu back over D-Bus. Both need Docker and /dev/net/tun; see their headers. ci/router/openwrt-test.sh runs the x86_64 router agents in the official OpenWrt 24.10 rootfs (pinned by digest) against a scratch UCI directory: both agents' configuration imported by OpenWrt's own uci, idempotency, foreign sections left byte for byte, the JSON interface, the join-key rules and venue observations from canned hostapd answers.

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the repository license file.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

Company Information

Task Venture Capital GmbH
Registered at District Court Bremen HRB 35230 HB, Germany

For any legal inquiries or further information, please contact us via email at hello@task.vc.

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.

Unified OpenWrt supervisor

apps/router builds skyglide-router-agent, installed as /usr/sbin/skyglide by the single OpenWrt skyglide package. The package embeds both existing role engines. Mainapp's console issues the setup code and selects the role; the router page is only onboarding and status. The supervisor pulls configuration, reports compatibility, and applies only when its role check passes. Unsupported venue routers report their limitations without receiving the site's configuration.

Use skyglide setup --controller https://controller.example/typedrequest --code-file -, supplying the code on standard input, then start the package's procd service. skyglide status --json exposes connection state without credentials; skyglide check --json diagnoses both roles without changing networking. skyglide reset stops the service and removes Skyglide-owned configuration before changing roles.

The wire types are generated with rustsupport-codegen from mainapp's focused schema/routers.openapi.json. apps/router/schema/source.json pins its upstream revision and SHA-256; refresh both schema and generated Rust together. The supervisor uses rustsupport's verified TLS TypedRequest transport. Its private enrollment remains under /etc/skyglide.

The unified supervisor also maintains an outbound TLS device-management worker independent of role capability checks. The console can lease an interactive root shell for five minutes. It uses a native PTY, bounded nonblocking I/O, sequence acknowledgements, and reconnect backoff; acknowledged input is never replayed after transport loss. Worker or controller restarts close the old shell. The browser can resume a live session, and disconnect, expiry, or operator-session revocation terminates it. No inbound listener, router SSH package, history file, terminal transcript, or credential-bearing process argument is added. A disposable OpenWrt 21.02.7 VM qualifies execution, Ctrl+C, resize, child cleanup, and cleanup under output backpressure. Physical end-to-end qualification is separate.

Wi-Fi sign-in on skyglide.com

A device that joins skyglide.com is asked for a username and a password. The venue router does not check them: its hostapd is the 802.1X authenticator and a RADIUS client of the cloud's Wi-Fi sign-in service, which it reaches inside the site tunnel. The router learns only the outcome, and with an accepted sign-in the VLAN of the member's network (Tunnel-Type 13, Tunnel-Medium-Type 6, Tunnel-Private-Group-ID the VLAN number). It holds no member's credential.

  • The member BSS runs WPA2-Enterprise and WPA3-Enterprise together (WPA-EAP WPA-EAP-SHA256), with protected management frames offered: WPA3 devices use them, WPA2 devices may join without. The sign-in service comes from the desired state's wifi.member_signin (address, port, shared secret); the NAS identifier is the site's id.
  • RADIUS leaves from the site tunnel address and only through the tunnel. The runtime routes the service's address into the tunnel in the main routing table and keeps an unreachable route behind it, so a missing tunnel makes the service unreachable instead of sending sign-ins to the uplink. hostapd starts only after the tunnel has its address.
  • A VLAN is required: a sign-in whose answer names none, or one this location has no network for, is refused. Each member network and the billing network have their VLAN interface and bridge as before.
  • While the sign-in service cannot be reached, connected devices stay connected (hostapd does not re-authenticate periodically) and a device that signed in recently rejoins from the key it holds with the access point (12 hours, unless the service's answer sets a session time). A new sign-in fails until the service answers again.
  • When a member network's signin_epoch changes (a renewed password, a username that changed with the email address), the agent makes hostapd forget its cached keys and disconnects the stations of that member's VLAN, so that they sign in again; nothing is rebuilt and other members' devices stay associated. The billing network has its own signin_epoch, which changes with the set of restricted members: its stations then sign in again, and a member who paid lands in their own network. A network that leaves the configuration (a member who becomes restricted, a member who left) is removed with a rebuild of the access points, which disconnects every station; until a location has a network, a sign-in answered with its VLAN is refused there. The access point's side of an ended sign-in is immediate (no VLAN, no keys); a device that protects management frames can take until it next sends something to notice.
  • skyglide check reports wifi_signin: a hostapd with 802.1X and VLANs from the sign-in's answer (the full builds) on a driver that creates AP/VLAN interfaces. The venue role needs it. per_psk_vlan is still reported, for the device network that is not built yet, and does not keep the role from running.
  • hostapd knows the signed-in username of each station (its control interface's station entry, dot1xAuthSessionUserName, the name the service returns with the answer, or else the outer identity the device sent). The agent does not read or send it.

The opt-in kernel test native::kernel_tests::sign_ins_select_private_bridges_and_preserve_reference_uplink runs this in a disposable OpenWrt VM on mac80211_hwsim radios with real 802.1X clients, a WireGuard hub and a RADIUS server (skyglide.com/openwrt's ci/hwsim-test.sh).

When a guest's access ends on skyglide.com_guest

A phone looks for a captive portal when it joins a network, not while it stays on one. A guest whose internet access ended would otherwise keep a Wi-Fi that leads nowhere until some plain HTTP request happens to be intercepted. So the router disconnects that guest's station from the guest Wi-Fi once. The device rejoins the known open network by itself, checks for a portal as on every join, meets the interception and shows the sign-in page. It needs no certificate and nothing from the device; the cost is one short Wi-Fi drop at a moment when the internet is gone anyway.

  • What ends access. The grant's absolute expiry has passed, which the router knows and enforces itself, also while the controller cannot be reached. Or an accepted answer of the portal sync (router.venue.portal.sync) lists no grant for the client any more: the controller revoked it or dropped it.
  • After the kernel let go. The disconnect follows the router's own enforcement, not the controller's word: the station goes once no kernel authorization of it can exist any more. That is at once after a policy round whose command replaced the kernel's sets without the station, and after the authorization's timeout (30 seconds at most) when that command failed.
  • Once per ended grant. A station is remembered when the kernel acknowledged its authorization, and forgotten when it is disconnected. Nobody is disconnected who never had access, nobody again while they stay captive, and nobody a starting daemon does not know (the memory is the process's; a daemon's start rebuilds the access points, which disconnects every station anyway).
  • No disconnect while a grant runs. A pass that is renewed or extended, or a new sign-in before the old grant ran out, is a listed grant for the same station: nothing happens. A grant the router cannot enforce for a while is no ended grant either: the controller does not answer and the kernel authorizations lapse within 30 seconds, the client's neighbour entry is missing while the device sleeps, shaping failed. Access comes back by itself then, and a device sent through a new join would show a sign-in page it does not need.
  • Deauthentication, on the guest BSS that holds the station. The agent asks each guest BSS of its own hostapd processes (the open one and the hidden Enhanced Open twin, on every radio) whether it holds the station, and deauthenticates it there. A deauthentication ends the whole link, so the device comes back with a new authentication and association, which its system takes for a new join. After a disassociation the station stays authenticated and may reassociate inside its driver like a roam, which the system need not notice. A station no BSS holds is skipped, nothing is tried twice, no cached key is flushed, and the other guests, the member network and the uplink are not touched.
  • A device with protected management frames (every device on the Enhanced Open twin) can miss the frame while it sleeps and notices when it next sends something.

The opt-in kernel test native::kernel_tests::ended_guest_access_disconnects_the_station_once_and_the_portal_returns runs this in a disposable OpenWrt VM on mac80211_hwsim radios: three guest devices on the open network and its Enhanced Open twin, the captive gateway with its policy rounds, a WireGuard hub, and a stand-in for the controller's two portal calls.

Device measurements and shared venue passes

The unified router supervisor reports read-only CPU, memory, uplink byte counters and measured bandwidth every five seconds. Wi-Fi client counts are deduplicated across owned APs; logged-in guests count only while their kernel authorization remains applied. Missing counters and first rate samples remain unknown. No telemetry is written to router flash. The controller keeps the latest received sample in memory and marks it stale after fifteen seconds.

A venue-pass grant requires a positive shared upload/download limit and a pass rate-group id. Every device on that pass maps to the same HTB class in each direction. Missing, inconsistent or unverifiable group terms withhold access; no per-device or unbounded fallback is used. Only owned guest and tunnel interfaces are shaped, preserving the underlay uplink.

On Linux, ci/router/shared-rates-test.sh qualifies actual two-client delivery in an empty disposable Docker network namespace with the existing mainapp E2E fixture image (Node is mounted from the host). It requires Docker NET_ADMIN/SYS_ADMIN only inside that container, refuses nonempty/enrolled networks, checks both aggregate directions and detects/repairs a removed client filter. These are isolated Linux kernel results, separate from physical OpenWrt qualification.

S
Description
Skyglide for desktops and servers: the skyglided service, the skyglide command-line client and the egui tray app for Mac, Windows and Linux.
Readme MIT
1.8 MiB
0 Stars 3 Watchers 0 Forks
Languages
Rust 95.9%
Shell 3.4%
JavaScript 0.3%
Python 0.2%
Dockerfile 0.1%