Getting started

This page assumes a working Nix install and devenv 2.4 or newer.

Enter a dev shell#

devenv shell         # the pinned rust (1.99.1), the native libraries and mold

With direnv, cd into the checkout does the same (.envrc). The repo’s devenv.nix carries the native libraries the workspace links against (the Dioxus desktop crates need the GTK/WebKit stack even in unit tests); the fleet’s shared module (devenv-fleet’s rust, imported in devenv.yaml) brings mold, the linker .cargo/config.toml selects on x86-64 Linux, and rust 1.99.1, the release rust-toolchain.toml pins, with the wasm32-unknown-unknown target. CI runs its steps in the same shell, with the same rustc; see .github/workflows/checks.yml and .github/actions/shared-rust/action.yml.

Build everything#

just check           # cargo check --workspace --all-targets

The framework half must stay wasm-clean; CI checks it with:

cargo check --target wasm32-unknown-unknown \
  -p architect -p architect-atom -p architect-form \
  -p architect-permissions -p architect-permissions-proto \
  -p auth-proto -p auth-client -p crdt -p architect-input

Run the tests#

# The reference feature: one scenario in process, over vox and over HTTP.
cargo test -p example-greeter

# The facade: layers, HTTP face, iroh loopback, reconnect, RPC spans.
cargo test -p architect

# Everything (what CI runs).
just test

If cargo test -p example-greeter passes on a fresh checkout, your environment is wired up correctly.

Run a server#

GREETER_BIND=127.0.0.1:4040 cargo run -p example-greeter
curl -XPOST localhost:4040/greeter/greet -d '{"name":"cody"}'

EngineHost serves vox over WebSocket at /vox, the HTTP routes and SSE streams, and /health. The identity server has its own recipes (just auth-dev, just auth-demo, just auth-e2e).

Next#

Read Build a feature, end to end: it walks the whole flow (define an entity and a service, write a backend, serve it, consume it remote or in-process) against examples/greeter. Then:

• Script an app, end to end, against examples/scripting: an Action List driven from Luau as one undo step, scripts saved as actions, and an agent over MCP.
• Write an extension, end to end, against examples/extension: a manifest, a Luau overlay and a process extension with a remote view, loaded from a registry.
• The guide, chapter by chapter, and the features, one page each.

A new feature in one command#

cargo xtask feature new inventory

writes one crate, features/inventory/ (the layout): the contract in src/lib.rs (an entity, a service, its error; the default feature set, wasm-clean), an in-memory backend behind the memory flag, empty vox / ui flags, a spec/ and a scenario test that already passes in process and over vox. It adds the crate to the workspace members and to [workspace.dependencies] (with default-features = false). Then cargo test -p inventory.

examples/greeter is the same contract with a server on top: copy it when you need one.

Repo tooling#

cargo xtask has six commands: feature new, boundaries (the layer table and ratcheted idioms in boundaries.toml), docs (every repo path, page link, just recipe, cargo xtask command and -p package these docs name must exist), tags and fleet-bump, plus auth-mirror for the identity server. just --list shows the recipes.