Building from Source

The canonical source is github.com/ferroxlabs/wayland-core. The workspace uses Rust 2021 edition on the stable toolchain. All crates build with a standard cargo build; no build.rs code generation step requires external non-Rust tooling unless you enable the seccomp or live-docker features.

Prerequisites

Rust stable toolchain. Install via rustup. The workspace does not require nightly.
cargo-nextest for the preferred test runner: cargo install cargo-nextest --locked.
just and vx for the just push workflow (optional for building, required for the lint-fix+test+push cycle). See AGENTS.md for the vx install one-liner.

On Linux, bwrap must be in PATH for the sandbox to activate at runtime. The build succeeds without it; the engine simply falls back to FailClosedBackend at spawn time unless WAYLAND_ALLOW_NO_SANDBOX=1 is set.

Quick start

git clone https://github.com/ferroxlabs/wayland-core
cd wayland-core
cargo build --release
./target/release/wayland-core --version

The release binary is target/release/wayland-core. All features that do not require a system C library or a live external process are compiled in by default.

Installing via cargo

cargo install --git https://github.com/ferroxlabs/wayland-core wcore-cli

This installs the binary as wayland-core on your PATH (via ~/.cargo/bin).

The npm package @ferroxlabs/wayland-core wraps the same binary for Node.js-hosted environments:

npm install -g @ferroxlabs/wayland-core
wayland-core --version

Cargo feature flags

Features are declared per-crate. The ones relevant to a production build are described below.

`wcore-memory`: embedder backend

Feature	Default	Effect
`local-embedder`	on	Compiles the `bge-small` local embedding model via `candle`. Enables fully offline vector memory without a cloud embedder API key. Adds binary size.

To build without local embeddings (cloud embedder only, smaller binary):

cargo build --release -p wcore-cli --no-default-features --features remote-registry,workflow

`wcore-observability`: OTLP export

Feature	Default	Effect
`otlp`	off	Enables the OpenTelemetry OTLP exporter sink (`opentelemetry`, `opentelemetry-otlp`, `opentelemetry_sdk`). Off by default to keep the binary size within the notarization budget.

To build with OTLP:

cargo build --release --features wcore-observability/otlp

`wcore-browser`: browser backends

Feature	Default	Effect
(none)	on	Camoufox sidecar over HTTP (localhost:9377). The sidecar must be running; `WebFetch` works without it.
`chromium`	off	Adds `chromiumoxide` CDP backend (~30 MB of additional dependency surface). Requires a Chromium binary at runtime.
`browserbase`	off	Enables Browserbase cloud backend, env-gated at runtime via `BROWSERBASE_API_KEY` and `BROWSERBASE_PROJECT_ID`. No extra compile-time deps.

# Build with chromiumoxide fallback
cargo build --release --features wcore-browser/chromium

`wcore-sandbox`: Linux hardening layers

These features require system C libraries and only apply on Linux.

Feature	Default	Effect
`landlock`	off	Builds Landlock LSM ruleset support (`landlock` + `libc`). Applied via a `pre_exec` closure in the bwrap child (Linux 5.13+). Degrades gracefully on older kernels.
`seccomp`	off	Builds a `libseccomp` BPF filter for `SyscallPolicy::Strict` and passes it to bwrap via `--seccomp <fd>` (Linux only). Requires `libseccomp` installed on the build host.
`live-docker`	off	Enables the `bollard`-based Docker backend for tests and the `WAYLAND_SANDBOX=docker` runtime path.

# Linux: full sandbox hardening
cargo build --release --features wcore-sandbox/landlock,wcore-sandbox/seccomp

`wcore-cli`: workflow and registry

Feature	Default	Effect
`remote-registry`	on	Compiles the GitHub releases resolver used by `self-update` and the plugin registry. Pulls in `reqwest` and `wcore-egress`. Disable to build a fully offline binary.
`workflow`	on	Compiles the `ForgeFlows` workflow subcommand and its RON DSL runner.

Cross-platform notes

Linux

The full feature set is available. The sandbox activates automatically when bwrap is in PATH. Landlock and seccomp require opt-in build features and a compatible kernel.

Linux Wayland CUA (wcore-cua) requires wlrctl and grim at runtime. It refuses on restricted compositors (GNOME Mutter, Hyprland) because those compositors do not expose the required Wayland protocols.

macOS

SandboxExecBackend activates automatically via /usr/bin/sandbox-exec. The Tahoe (macOS 26.x) fix is baked in so zsh 5.9 on Tahoe does not hit the deny-default profile during shell init.

One known gap: mach-lookup is intentionally unfiltered in the SBPL profile. There is no AllowHosts-style DNS gate for the bwrap backend on Linux either. See the status matrix for details.

CUA uses CGEvent for input synthesis and requires Accessibility permissions on macOS 13+.

Windows

AppContainerBackend activates when the real-spawn probe passes. Filesystem ACL wiring for the AppContainer is not yet complete; the interim posture is safe default-deny on the process but without per-path ACL grants. See the status matrix.

CI runs on Windows (confirmed in AGENTS.md). The build does not require WSL. Windows-specific path handling uses dirs::config_dir() and Path::join(), not hardcoded paths.

Running tests

cargo test                  # all unit and integration tests
cargo nextest run           # preferred: per-test output, parallel
just push                   # lint-fix + fmt + test + git push

Tests that require live external processes (real Chromium, Docker, a running LLM API) are gated behind feature flags (browser-live-tests, live-docker, harness-failure-injection) and are not run in the default cargo test invocation. The CI matrix enables each gate in a dedicated job.

Clippy and formatting

cargo clippy         # must pass with zero warnings; the egress-chokepoint lint is enforced here
cargo fmt --all      # CI enforces no diffs

The workspace clippy.toml bans reqwest::Client::new, reqwest::Client::builder, reqwest::ClientBuilder::new, and reqwest::get via disallowed-methods. Any network call that bypasses wcore_egress::EgressClient fails CI. The only sanctioned exceptions have a local #[allow(clippy::disallowed_methods)] comment in wcore-egress/src/client.rs and wcore-providers/src/retry.rs.