Flux: bridging an Omarchy desktop and your phone

One daemon and four native clients

Flux connects an Omarchy desktop to an Android phone, an iPhone or a Mac over the local network, or through Tailscale when you are away. The feature line is concrete: share files, clipboard text and clipboard images, read phone notifications, control media, and use your phone as a camera or microphone.

The packaging is the interesting part. Flux includes a CLI, a background daemon, a native Qt window, an Omarchy shell plugin, a native Android app, a native iOS app and a native macOS app, with a Windows app as well. That is not one binary but a small family of clients that share a pairing relationship.

The repository layout matches. At the top level there are cmd/, internal/, gui/, android/, ios/, macos/, windows/, dist/, docs/, scripts/, site/, skills/ and marketing/, plus a go.mod and go.sum, a Makefile, DESIGN.md, PRODUCT.md and AGENTS.md. The Go code is the core, the gui/ directory holds the Qt and QML side, and each platform has its own native application directory.

So the intended user is a person with an Omarchy desktop, a phone, and a habit of moving files and text between them several times a day, and the intended answer to the usual pile of clipboard and file transfer tools is one paired daemon.

The daemon dials out, so the firewall stays closed

The networking decision is stated early and it is the one that makes the rest work on a default Omarchy system. The fluxd daemon listens on one TCP port from 12100 to 12108 and on UDP port 12100, and it also opens the connections to the devices itself. Flux therefore works with the default Omarchy firewall, which blocks inbound traffic, and needs no new inbound rule.

That is a deliberate inversion of the usual pattern. Most local network tools expect the phone to dial the desktop, which means opening a port on the machine that is usually behind the router and often behind a firewall. Here the daemon initiates, so the desktop listens for the reply and nothing has to be exposed to the network.

The consequence for you is that pairing is not a firewall chore. You are not adding a rule, opening a port range on your workstation or reconfiguring the router. The port range is a fallback in the daemon's own listening, and the traffic direction is handled by the daemon.

Security is documented separately rather than assumed. The README points at a security document for what a paired device can do and which settings limit it, and the feature list includes per device access, notification rules and local automation, so the question of what the phone is allowed to trigger is a configuration decision rather than a fixed property.

Pairing compares sixteen characters on both screens

The pairing flow is a short list of steps that anyone can follow without a manual.

1. Install Flux for Android. 2. Connect the phone and desktop to the same local network. 3. Open the desktop window with `flux-cli open`. 4. Select + Pair new device. 5. Compare the 16-character verification key on both screens, for example `5EE6 825F 974E D59A`. 6. Accept the matching request on the phone. 7. Select Confirm in the Flux window or in the notification on the desktop. The desktop pins the phone only after this step.

Two constraints make this worth reading carefully. Each step waits at most 30 seconds, so a stale screen is not something you can sit on. And you compare all 16 characters. Earlier Flux apps show only 8 characters, which is why the README tells you to update Flux on each phone, iPhone and Mac before you pair.

The CLI can start the same exchange.

flux-cli pair "Pixel 8"

After the phone accepts, the command asks whether the phone shows the same key, and you type `y` to confirm. The pinning detail in step 7 matters too: the desktop pins the phone only after the confirm step, so a phone that shows the right key but is never confirmed is not a trusted device.

Installing on Omarchy or Arch

The install path is the Arch path, since Omarchy is Arch based. First the build tools.

sudo pacman -Syu --needed base-devel git go cmake ninja

Then the repository and the package.

git clone https://github.com/bjarneo/flux.git
cd flux/dist/arch
makepkg -si
flux-cli setup
flux-cli doctor
flux-cli open

The package includes the Qt app, the CLI, the daemon, the shell plugin, the approval helper, a desktop entry, icons and system files. You run flux-cli setup as your desktop user after installation, and flux-cli doctor is the obvious first command to run because it is there to tell you what is missing.

There is a naming detail worth knowing. The short name flux also works when no other program, such as fluxcd, uses that name.

Updates are handled by the same tooling. Flux checks for a new release once a day, and you install it with flux-cli update. The install guide covers dependencies, source builds, user-only installation, updates and removal.

The platform floors for the phone side are stated up front: Flux for Android requires Android 10 or later and is the supported phone app, Flux for iOS requires iOS 17 or later and is installed with Xcode, Flux for macOS requires macOS 14 or later, and Flux for Windows requires Windows 10 version 2004 or later.

The CLI is where the automation lives

Everything in the feature table is reachable from a terminal, and that is what makes Flux more than a file transfer utility.

flux-cli status
flux-cli send "$HOME/Downloads/report.txt"
flux-cli clip
flux-cli url https://omarchy.org
flux-cli ring
flux-cli notify --run -- make test

The last line is the one to notice. A notification can carry a command that runs on the desktop, so a phone can trigger a build or a test and report back, without you being at the keyboard.

When more than one device is connected, you name the target with the --device option.

flux-cli --device "Pixel 8" send "$HOME/Downloads/report.txt"

That flag matters in practice because the daemon holds several paired devices at once, and an unqualified command has to guess. Naming the device removes the ambiguity, and the CLI reference is the place to look for the full command set and script examples.

Beyond the terminal, the feature table covers offline file queuing, folder archives, saved clipboard snippets, per device access rules, notification rules, local automation, reading notifications from the phone, sending SMS, controlling media, running desktop commands from the phone, syncing Do Not Disturb and pausing media during calls, using the phone as a webcam or microphone, screen mirroring into a desktop window, using the phone as a touchpad and keyboard, remote desktop in both directions, and approving sudo with the phone's fingerprint sensor. There is also a Tailscale guide for reaching the phone away from home and a guide for herdr coding agents.

Go core, Qt6 interface, native apps

The build system shows the split between the core and the interface. The Go module is named flux and targets a recent toolchain.

module flux

go 1.27.1

Its direct dependencies are small and specific: a TOML parser, a D-Bus client, an SFTP library, and the golang.org/x crypto and sys modules. That is a core that talks to the desktop session bus, moves files over SFTP, handles configuration in TOML and does its own cryptography.

The Makefile builds three Go binaries: fluxd, flux-cli and flux-approve, and the comment explains why the third one is special. The PAM helper is static, so that it depends on no shared library, which matters because it is the piece that approves a sudo request using the phone's fingerprint.

The interface is a separate stack. The GUI build runs cmake with Ninja on gui/app in Release mode and passes the version, and the comment describes the target as the Qt6 C++ app with the shared views in gui/qml compiled into it. The Omarchy plugin is installed into ~/.config/omarchy/plugins/flux and consists of manifest.json, Service.qml, Backend.qml, BarWidget.qml and Panel.qml, laid out the way the omarchy plugin validate command expects.

The developer commands are short.

make build test vet
make android

On a Mac with Xcode and XcodeGen there are separate targets, make test-macos macos and make install-macos, and make ios test-ios builds the iOS app and runs its tests in a simulator.

Continuous integration runs only on master

The release arrangement is stated precisely, and the detail worth noting is what does not run.

GitHub Actions builds the complete Arch package, the Android APKs, and the macOS and iOS apps for each push to the master branch. Pull requests run no build.

That is a deliberate trade, and it has a consequence. Contributors get fast feedback on the parts that the review process can judge by reading, but a pull request is not compiled until it lands on master, so a broken build is discovered by the branch pipeline rather than by the author. For a project that ships five platform artefacts from one repository, that keeps CI minutes down, but it also means the safety net is one merge away.

Stable version tags produce a signed APK, an Arch package, an AUR recipe, an ad hoc signed macOS app, an unsigned iOS app for sideload tools, and checksums. The optional AUR job publishes the tested recipe after the GitHub release succeeds, so the package lands only once the release artefacts are in place.

The release list shows v0.16.0 and v0.17.0 on 2026-10-11 and v0.18.0 on 2026-10-16, and the last push was on 2026-10-21. Three releases in five days is fast movement, and the 0.x version numbers signal that the interfaces are still settling. The licence is MIT, with the terms in the LICENSE file at the repository root, and the repository also carries a skills/ directory and an AGENTS.md for agent driven work.

Editorial conclusion

Flux suits someone running an Omarchy or Linux desktop who wants their phone to act as a second device for files, clipboard, notifications, camera and approvals, and who is comfortable pairing a local daemon with a native app. It does not suit a team that needs a shared, managed deployment, since each device is paired individually and the project is at version 0.x. Verify first that your phone platform meets the floor, Android 10, iOS 17, macOS 14 or Windows 10 version 2004, and read the security document before granting a paired device desktop command execution.

Frequently asked questions

Official sources

1. bjarneo/flux on GitHub
2. License: MIT
3. Project website
4. README
5. Releases