Skip to main content

​
Bun and Rust projects

Four of Orbit’s nine projects are not Composer projects. This page shows how to install, run, and check each one. The contributor guide covers the five PHP projects and the process that every change follows. bin/bootstrap installs the Composer projects. With --with-bun it also runs bun install --frozen-lockfile in the web app, the Pi server, and the desktop app. With --with-rust it runs cargo fetch --locked for the Node agent and the desktop app. It does not install Bun or Rust themselves. bin/bootstrap does not check these projects, and bin/test runs only the Composer projects. Check these four projects from their own directories. Root composer check runs some of the web app and Pi server checks when a change touches them, as Web and Pi server checks lists. For the web app it runs bun run check, bun run build, and a generated-types check, but not bun run test. It does not check the Node agent or the desktop app.

​
Prerequisites

Install the tools for the projects that you change. Vite+ is a dev dependency of the web app and the Pi server, so the bun run scripts find its vp command without a global install. When Bun resolves a version, it takes only releases that are at least three days old, as Dependencies explains.

​
Web app

Install the dependencies and serve the app with demo data:
bun run demo serves the app against an in-memory fixture fleet, so it needs no Gateway. bun run dev serves it against the Gateway in your CLI profile instead. That machine must be a WireGuard peer of the fleet. The web app README describes both modes, the layout of the source, and how to run the app against a disposable topology. Run the checks before you submit a change:
bun run check formats, lints, and type-checks. bun run test runs the unit tests in Node and the browser tests in headless Chromium. Both need Playwright’s browsers, because the web verification tests in the unit project launch Chromium and WebKit. Install them once with bunx playwright install webkit chromium. After a change to docs/openapi.json, run bun run types and commit the regenerated src/api/schema.d.ts. A UI change also follows web verification. The web app page describes how the Gateway serves and releases the app.

​
Pi server

Install the dependencies and run the checks:
bun run build type-checks the server and compiles it to one binary, dist/pi-server. bun run build:linux compiles the x86_64 and aarch64 Linux binaries that Nodes run. Run the tests on Linux. Test worker file access lists the tools they need. To try the server without a provider sign-in, serve it with a scripted model:
The scripted model runs one bash command in the session’s workspace on each turn and then answers. The server listens on 127.0.0.1 at the port you give, 3790 by default, and accepts workspaces only under the path you give. The Pi server page describes the real server’s flags, its API, and how a Node runs it.

​
Node agent

The agent runs only on Linux Nodes. It talks to systemd over D-Bus and reads its configuration from /etc/orbit/agent, so you check it locally and run it on a Node.
Run cargo test as a normal user, not as root. The agent refuses to tail a log file that root owns, and one log stream test fails when root creates its fixture. Commit Cargo.lock with any dependency change. CI also builds static musl binaries for x86_64 and aarch64 with cross. On a pull request, CI builds the agent only when the change touches apps/agent or the CI workflow. To watch what an installed agent reports, join its Node’s presence channel with the viewer script:
Run it from a WireGuard peer of the fleet. The Node agent page describes what the agent observes, how the Gateway installs it, and how a tag releases it.

​
Desktop app

Install the dependencies of both apps, then open the window:
bun run dev starts the web app’s dev server and opens it in a desktop window. The desktop app has no tests yet. Before you submit a change, run cargo fmt --all -- --check and cargo clippy --locked --all-targets -- -D warnings in apps/desktop/src-tauri; CI runs the same checks. The desktop app page describes the build and its limits.

​
CI

The Web, Pi server, Rust agent, and Desktop app jobs check these projects on every pull request. The Rust agent and Desktop app jobs skip their steps when the pull request does not change their project or the CI workflow. CI lists the steps of each job. CI checks the desktop app’s Rust shell but does not build a bundle.