Start here
This gets a shell to a native Auro window with the published alpha CLI, then explains what the default dev loop actually does. Auro is pre-alpha: use this to evaluate the shape of the framework, not to ship a product.
Before you start
You need:
- Rust stable with
cargoonPATH. The scaffold uses edition 2024 and declaresrust-version = "1.90". - The platform build dependencies. Linux needs the native libraries listed in platform support; macOS and Windows need their normal native build toolchain.
- The alpha CLI. There is no stable release. The published version is
0.1.0-alpha.7.
The CLI is a cargo-installed binary named auro; the crate is auro-cli.
1. Install the CLI
cargo install auro-cli --version 0.1.0-alpha.7
auro --version
If the second command does not run, check that ~/.cargo/bin is on PATH. To build the CLI from
a checkout instead, follow CONTRIBUTING.
2. Create the app
auro new hello
cd hello
auro new refuses a non-empty directory. It writes a four-crate workspace plus configuration:
| Path | Role |
|---|---|
Auro.toml | App identifier, windows, dev watch list, hot-mode switch and bundle icon. |
src/main.rs | Thin binary: calls the UI crate with the hot boundary function. |
ui/ | Render, window, element tree and command functions. It does not depend on data. |
data/ | The hot boundary: view_data() -> HotData, deliberately tiny and framework-free. |
types/ | Shared ViewData and the fixed HotData frame; no framework dependency. |
The split is the hot-reload boundary: changing data/src rebuilds a small crate and relinks the
binary, while ui and GPUI stay compiled. That is why the boundary is separate, and why a change
outside it is not a view reload.
3. Run it
auro dev
The command builds the app, launches it as a native window, and watches the paths in [dev] watch.
A save rebuilds, relaunches and restores opted-in state from a snapshot when the snapshot version is
compatible. The previous app stays visible while a replacement builds.
This default loop is not hot reload. It is a build-and-restart loop, and the output says
restarted (state restored) or restarted (state reset) rather than pretending otherwise.
To check the toolchain, GPUI pin, config parse, hot-mode availability and Linux libraries:
auro doctor
On Linux, auro doctor reports each native library as ok or MISSING. Missing libraries are a
build problem, not an Auro bug.
4. Know what the hot path covers
Hot mode is opt-in. Set it in Auro.toml:
[dev]
hot = true
It also needs dioxus-cli 0.7.x on PATH (tested with 0.7.10) or an explicit AURO_DX path.
auro doctor reports whether the app declares the hot-reload feature and whether the devserver is
available.
With hot mode on:
- A save in
data/srcis a boundary edit. The patch replaces that function; the running host keeps its window and state. - A save in
ui,types, the binary, a dependency, a manifest or the profile is host code. It rebuilds and restarts the devserver and app, restoring the snapshot when compatible. - On Linux, boundary-only edits in the generated app measured 368 ms median save-to-render (N=12, 325-394 ms). Windows measured 813 ms median; the shared macOS runner measured 509.5-956 ms across runs. Those are above the 500 ms target.
- The measurement is for the documented data boundary only. It is not a general layout or view reload, and it is not GA.
The full contract, including failure behavior and what is not reloadable, is in hot reload and spec 0004.
5. Build and bundle
auro build
auro bundle
auro build produces the release binary. auro bundle asks the platform bundler for the host's
installers. Packaging support is uneven by platform and is documented in
platform support; do not assume every target produces every
installer.
Useful variants:
auro dev --dir /path/to/app
auro dev --dir . --config app.product-name="Demo"
auro build --dir .
auro bundle --dir .
Where to go next
| If you want to | Read |
|---|---|
| Understand the app loop | Architecture overview |
| Follow a command across threads | Threading and IPC |
| Change configuration | Configuration |
| Know what is actually verified | Platform support |
| Know why a decision was made | Decision records |
| Check the alpha gates | Alpha release |
For a bug or a build failure, include the output of auro doctor, the host OS and compositor, the
CLI version, and the commit or crate version. The project is pre-alpha; a reproducible report is
more useful than a compatibility claim.