Skip to content

Building from Source

Ryan Stoffel edited this page Oct 29, 2026 · 1 revision

Building from Source

How to build plxd and the app, run them in development, and run the same checks CI runs. For how the pieces fit together, see Architecture.

Prerequisites

Tool Version Notes
Rust 1.98.1, pinned in rust-toolchain.toml Install rustup, then run rustup toolchain install in the repo to get the pinned toolchain with rustfmt and clippy.
C compiler Any The bundled SQLite and ring need one. On Linux, Debian's build-essential or similar. On Windows, the Visual Studio C++ build tools, plus clang on Windows arm64.
Node 24, pinned in apps/desktop/.node-version Used by the app, the relay, the mobile app, and the packages
pnpm 11.10.0, pinned in each package.json Run corepack enable once. Run pnpm inside a package folder, such as apps/desktop, where corepack finds the pinned version.

To run agents, the host also needs Node 22.16 or newer with npm, since plxd installs the Claude Agent SDK and Cursor SDK sidecars with npm ci. Linux workers need bwrap and socat (see daemon/README.md).

Build plxd

From the repo root:

cargo build -p plxd

A dev checkout of the app runs target/debug/plxd, so build the debug binary for pnpm dev. For a release binary, use cargo build --release -p plxd.

plxd has two Cargo features:

  • fake-backend: a scripted agent for tests, which the e2e tests and the load harness use. Release builds refuse it.
  • sandbox-tools: embeds static bwrap and socat on Linux, built by scripts/ci/build-sandbox-tools.

Run the app in development

cargo build -p plxd
cd apps/desktop
pnpm install
pnpm dev

pnpm dev serves the renderer with hot reload, rebuilds the main process and preload on change, and restarts Electron when they change. Quitting the app or pressing Ctrl-C stops everything. Extra arguments go to Electron, such as pnpm dev --remote-debugging-port=9222.

The app finds plxd in this order: PLXD_PATH, then target/debug/plxd, then PATH. Set PLXD_DATA_DIR to give plxd a data folder other than ~/.parallax.

Browser preview

The preview serves the real renderer in a plain browser, with no Electron and no plxd. From apps/desktop:

pnpm exec vp dev -c preview/vite.config.ts

It runs at http://localhost:5199/. preview/mockBridge.ts answers every plxd method the renderer calls from the fixtures in preview/fixtures.ts, and writes change in-memory state until the page reloads. A URL hash opens a view, such as #thread=Rework the updater or #onboarding. Keep the fixtures in step with what plxd reports. Details are in apps/desktop/preview/README.md.

Tests

Component Folder Commands
Rust (plxd and crates) repo root scripts/ci/check-rust
Desktop app apps/desktop pnpm check (format, lint, type-check), pnpm test (Vitest), pnpm build. pnpm fmt fixes formatting.
App end to end repo root scripts/ci/e2e-app
Relay relay pnpm install --frozen-lockfile, pnpm check, pnpm test (Miniflare)
Relay with plxd relay node scripts/e2e.mjs runs plxd's relay test against the Worker under wrangler dev
Mobile apps/mobile scripts/ci/check-mobile, or pnpm check and pnpm test
plx-connect packages/plx-connect npm ci, npm run check, npm test
clerk-verify packages/clerk-verify npm ci, npm run check, npm test
Claude sidecar sidecar/claude npm ci, then npm test. It runs against target/debug/plxd.
Cursor sidecar sidecar/cursor npm test

Every script in scripts/ci/ finds the repo root itself, so it runs from any folder. scripts/ci/README.md describes each one.

check-rust

scripts/ci/check-rust runs, with --locked:

cargo fmt --all --check
cargo clippy --workspace --all-targets --locked -- -D warnings
cargo test --workspace --locked

The tests include two protocol checks. Every sample in crates/parallax-protocol/samples/v1/ must still decode, so a change that isn't additive fails. The committed TypeScript types must match the Rust types. After changing a protocol type, regenerate them and commit the result:

cargo run -p parallax-protocol --bin generate-typescript

Some tests skip unless their dependency is set up:

  • The Claude Code sandbox tests need PLX_SANDBOX_CLAUDE set to a Claude Code binary, and on Linux, bubblewrap and socat.
  • plxd attach over a real ssh localhost runs through scripts/ci/ssh-localhost and scripts/ci/check-ssh-attach. daemon/README.md has the steps to run it by hand.

End-to-end tests

scripts/ci/e2e-app builds plxd with --features fake-backend (unless PLXD_PATH names one), builds the app, and runs Playwright from apps/desktop/e2e. The tests launch the built app against that plxd in a temporary data folder, with PLXD_FAKE_BACKEND naming the script the fake agent plays. On Linux with no display it runs under xvfb-run.

Mobile

apps/mobile is an Expo app. pnpm start runs Expo's dev server for a development build, and pnpm ios builds and runs the app, which needs Xcode. CI runs only the type check, the unit tests, and expo export --platform ios, which fails on an import the phone can't resolve.

Load bench and budgets

scripts/bench/load.py streams fake-backend threads through plxd at once and measures delivery latency, bytes and events per subscription, and plxd's CPU and memory:

cargo build --profile bench -p plxd --features fake-backend
scripts/bench/load.py target/release/plxd --threads 30 --out load.json
scripts/ci/check-load load.json unfiltered

--filtered and --orchestration change how the harness subscribes. Check each result against the budget set of the same name in scripts/bench/budgets.json (unfiltered, filtered, or orchestration). check-load fails on any value outside its budget, any missing metric, or any resync.

scripts/bench/threads.py times real thread starts against a signed-in claude CLI. CI doesn't run it.

What CI runs

.github/workflows/ci.yml runs on every pull request, and only on pull requests.

Job Runs on What it does
changes Linux Decides whether the PR touches Rust or its inputs
rust macOS arm64, Linux x64 and arm64, Windows x64 and arm64 scripts/ci/check-rust, then plxd attach over ssh. On Linux, the Claude sidecar test. On Linux x64, plxd through the relay under wrangler dev. Skipped when no Rust changed.
plxd macOS, Linux, Windows Builds plxd with fake-backend for the e2e and load jobs
relay Linux Type-checks the Worker and runs its tests in Miniflare
app macOS, Linux, Windows scripts/ci/check-app (the app, plx-connect, and clerk-verify), then scripts/ci/launch-app
mobile Linux scripts/ci/check-mobile
e2e macOS, Linux, Windows scripts/ci/e2e-app against that OS's plxd build
load Linux load.py with 30 threads in all three modes, each checked against its budget
actionlint Linux Lints the workflows, tests the release plan, and checks that ci needs every other job
ci Linux Passes when every other job succeeded or was skipped. It is the only required check.

rust-cache.yml saves the Rust caches on each push to develop, since a PR can't read another PR's caches. Releases are built by release.yml (see Release Channels and Updates).

Contributing

Read CONTRIBUTING.md before you open a pull request. In short:

  • A new feature or a change in behavior needs an agreed Ideas discussion first. A small, obvious bug fix can skip the issue.
  • One problem per PR, against develop, using the PR template.
  • The title is a Conventional Commit, since PRs are squash-merged.
  • Show evidence that it works. UI changes need before and after screenshots.
  • CI runs on an outside PR only after a maintainer approves it.

Security issues go through SECURITY.md, not public issues.

Clone this wiki locally