PX: File Exchange Between Trusted Devices

Sending a build artifact to a VM and retrieving its result should be a small exchange. For devices used repeatedly, the useful relationship already has a shape: this is the machine, these are the files it offers, and this is where incoming files belong.

I built PX around that relationship. Devices enroll into a small trusted pool, keep stable names, and exchange files directly. The design keeps repeated transfers convenient while limiting access to explicit file operations. A remote shell, VPN, or synchronized directory would each introduce a broader relationship than the task requires.

Devices Keep Their Identity

Enrollment establishes a relationship that later transfers can reuse. A per-user agent holds the device’s identity and maintains its connection to a self-hosted rendezvous server. A context groups that membership with the device’s file-access configuration.

Assuming both agents are enrolled in home and online, the ordinary exchange looks like this:

px --context home peers
px --context home "@vm" send ./artifact.tar.zst
px --context home "@vm" get reports/result.csv --output ./result.csv

@vm names the device within the home context. The send places a file in its inbox; the get retrieves a file it has offered. Scripts can keep addressing the same peer as its network address changes.

The unit of work remains one regular file. A directory can be archived before sending, but PX has no ongoing responsibility to reconcile two trees after the exchange. That keeps the result of each command concrete.

Establishing A Direct Connection

The Go implementation separates coordination from delivery. HTTPS/WebSocket connections carry enrollment, presence, and signaling. Pion WebRTC DataChannels carry file operations between peers, using ICE to attempt a direct path and DTLS to encrypt the session.

Signed negotiation messages bind the session to the enrolled devices’ Ed25519 identities. The connection design keeps device authentication distinct from transport encryption: a protected connection still needs to reach the intended peer.

The coordinator carries no file payloads, but remains a trusted authority for membership and identity bindings. It also sees presence and connection metadata. Keeping the data path direct reduces its role without making that role disappear.

Defining The Pool’s File Access

A PX pool is deliberately flat: active members can approve others and use the operations receiving devices enable. This suits a small group of machines trusted together. There are no per-peer roles or path ACLs, so a compromised member affects the pool’s trust boundary.

The filesystem layout expresses the authority given to that pool. An offered root contains files peers may list and retrieve. A separate inbox receives ordinary sends, with the receiving agent determining placement. Receiving a file therefore does not automatically offer it to everyone else.

Optional writes through put require a third root and are disabled by default. The file-access rules make browsing, receiving, and writing separate choices. The operator decides which directories participate instead of exposing the machine as a general remote environment.

Choose What A Completed Send Must Mean

The most consequential transfer choice is how much work completion should require. Ordinary send reads the source once and writes directly to a new, visible destination. It avoids a complete-file hash, staged publication, and retained recovery state. Existing files are refused.

That simpler path has a visible failure contract. An interrupted send can leave a partial file, and a lost completion response can leave the sender uncertain whether delivery finished. The file needs inspection before another attempt; retrying the destination will not overwrite it.

For verified content, atomic publication, and retained recovery state, select the stronger contract explicitly:

px --context home "@vm" send ./important.tar.zst --recoverable

Recoverable mode verifies content before publishing the staged file under its final name. It retains an operation identity so the peers can reconcile an uncertain result or retry the transfer. Payload retries begin at byte zero; the continuity is in the operation, not a saved byte offset. The recovery guide covers inspection and retry.

Keeping these contracts explicit lets a disposable artifact take the lightweight path while a transfer that needs stronger completion semantics pays for them deliberately.

Keeping The Coordinator Available

Both peers and the coordinator must remain online. Losing authenticated control presence cancels the context’s direct sessions, so a coordinator restart can interrupt transfers even though it carries no file bytes. This ties active exchanges to the system responsible for membership, at the cost of making coordination availability part of every transfer.

Release 2026.09.07.1 is direct-only, with no TURN fallback or offline queue. Restrictive NAT or blocked UDP can prevent a connection. New contexts use Google’s STUN service for address discovery unless configured otherwise; operators can supply their own. An enrolled peer can be online while the network still prevents the file path from forming.

A Small Pool Is The Point

The 2026.09.07.1 release includes Linux, macOS, and Windows archives for amd64 and arm64. The project page covers setup and capabilities; native filesystem validation remains an area of ongoing work, particularly for optional put operations.

PX concentrates on a relationship worth keeping and operations small enough to understand. Device identity, directory access, and completion behavior are explicit choices. Once those choices are made, the ordinary exchange can stay short: send this file, retrieve that result, and stop there.