A small native application core with a universal message bus, sandboxed WASM extensions in any language — and an engine an AI agent can build products on by itself.
Building with an AI agent · How to use it · Building the engine · Examples · Documentation · Changelog
The core owns windows, the tray icon, input (SDL), logging, and a message bus. Everything else is composed onto that bus: native modules in Rust — rendering, UI, audio, web panels, your own — and, when you turn them on, WASM extensions.
Every part talks to every other over that one bus, and none can tell whether the other is native or WASM. Extensions are optional. When used, they never touch the OS and never render directly: they publish draw commands, widget specs, or web-panel JSON, and the engine presents. That boundary is what makes an extension hot-reloadable, sandboxed, and language-agnostic.
The same boundary makes bones AI-friendly by design. Every effect is a message an agent can look up, send, record, and replay; an extension's picture is draw commands it can read as text; and every mistake an extension makes is reported with its fix. An agent builds, runs, observes, and tests a product through bones-develop and its MCP server, with no window and no engine source. Building with an AI agent says how.
flowchart LR
subgraph guests["WASM extensions — optional, any language"]
game["your game"]
tool["your tool"]
gui["your GUI"]
end
bus(("message bus"))
subgraph core["bones engine — native"]
present["renderer · egui · wry panels"]
io["input · audio · persistence"]
mine["your native modules"]
end
game & tool & gui <--> bus
bus <--> present & io & mine
The kernel infrastructure, renderer, egui UI, audio, game-core, optional web panels, hot reload, orderly shutdown, extension flow-control budgets, and custom native-module injection all work today.
Web panels let an extension build its interface in HTML, CSS, and JavaScript instead of native widgets. The engine shows the page inside its own window, using the operating system's web view through wry (WebView2 on Windows, WebKitGTK on Linux), and passes JSON messages between the page and the extension. docs/examples/web-app.md builds one.
bones is designed for AI-assisted product development, as an architectural property rather than an add-on (ADR-044). An agent can take a product from an empty folder to a tested change without the engine's source and without a person watching the window:
- Context, as plugins. agent-plugins/ holds everything bones offers an agent as Agent Plugins:
bones-userfor building a product, with the rules an agent cannot guess, a skill, the documentation, and the MCP server, andbones-devfor working on the engine. Every archive carriesbones-user, and every new project gets anAGENTS.mdand.mcp.jsongenerated from it. - A contract to look up. wit/wire-format.json specifies every core topic and its payload as data, tagged unions and lists included, and is checked against the codec.
- Eyes on the running engine.
bones-develop mcpgives an agent tools to launch the engine, send input, pause and step frames, and read the bus, the log, the frame as text, and a screenshot (bones-develop). - Proof without a window. bones-test runs a built extension headless and records what it drew as text, so a check can show that a change works.
- Errors that name the fix. The engine reports misspelt topics, malformed payloads, refused permissions, and the cause of every quarantine, once each, under the extension's name.
- Guardrails. A
[deny]table keeps an extension nobody has reviewed away from topics such asos/*(ADR-042).
Three ways in, from least to most code of your own. The first needs no Rust at all; the other two are for applications that own their binary, with or without extensions.
You ship the stock engine — the bones executable as built from a release, unmodified — and write your product — a game, a tool, a GUI — as one or more WASM extensions.
- Install the tools once:
cargo install --git https://github.com/an-dr/bones bones-develop. The bones-develop manual lists what the machine needs and covers every command. - Create a project with
bones-develop new my-game --kind game(oregui,web,embed). It pins the newest release tag and builds and passes its own headless checks from the first command; add--submoduleto vendor bones in the project instead of the shared cache in~/.bones. In a language other than Rust, generate bindings from the ABI in the engine'swit/instead. - Run
bones-develop devin the project. It builds the engine for the pinned tag on first use, builds the extension forwasm32-wasip2, starts the engine, and hot-reloads on every save.cargo testruns the checks.
examples/README.md walks through the project setup and picks the example closest to what you are building: a game, an egui tool, a web-panel app, persistent state. Start with the hello-demo tutorial.
Your application owns main and builds the engine with the Kernel builder — choosing the window and the modules in code rather than in bones.toml. Product logic can live in native modules, in extensions, or both. This is how commits and the other projects below use bones.
[dependencies]
# Drop "wasm" for a purely native application: no extensions, and no WASM runtime in the build.
bones-kernel = { git = "https://github.com/an-dr/bones", tag = "v5.0.1", features = ["wasm"] }bones-develop add writes that line into an existing crate, pinned to the newest tag. Distributed by git tag, not crates.io; docs/architecture/structure.md says what a tag promises. Opt-in modules cover what a desktop application needs around the engine: single instance, self-update, desktop registration, OS access.
When you need a capability the sandbox cannot reach — a device, a native library, an OS service — or code your application calls on a hot path, write a native module in Rust and inject it with .module(...). It joins the same bus and can define its own message vocabulary, which extensions then reach like any other. docs/design/extensions.md says when to choose a module over an extension. custom-engine is the worked example.
A release is a tag and its notes; it carries no binaries (ADR-046). bones-develop builds the engine at a tag and caches it in ~/.bones (ADR-047); a project's commands do this on first use, and you can do it ahead:
bones-develop engine install v5.0.1 --web # or without --web for the plain buildIt needs git, a C compiler, and CMake, and on Linux the packages cargo xtask linux-packages prints; docs/contributing/building.md has the details. Without bones-develop, clone the tag with --recursive and run cargo xtask dist [--features web]: dist/ then holds the engine, bones-develop, an empty extensions/ folder, the ABI (wit/), the bones-user agent plugin, a sample bones.toml with every default spelled out, the licence, and third-party notices; a zip of it lands beside the repository root. Builds differ by platform and by whether they include web panels — HTML interfaces for extensions — which need the operating system's web view at runtime. CI builds each of these with bones-develop engine install on every push:
| Build | Web panels | Your machine needs |
|---|---|---|
bones-<version>-windows-x64-web.zip |
✅ | Windows 10 or 11 — WebView2 is part of the OS |
bones-<version>-windows-arm64-web.zip |
✅ | Windows 10 or 11 on ARM |
bones-<version>-linux-x64.zip |
— | An X11 or Wayland desktop with ALSA — standard on desktop distributions |
bones-<version>-linux-x64-web.zip |
✅ | The same, plus libwebkit2gtk-4.1 and GTK 3 |
bones-<version>-linux-arm64.zip |
— | As linux-x64, on ARM64 |
bones-<version>-linux-arm64-web.zip |
✅ | As linux-x64-web, on ARM64 |
Which Linux build? Take -web if your extensions open web panels and you can install webkit2gtk (sudo apt install libwebkit2gtk-4.1-0 on Debian and Ubuntu). A -web build will not start at all where that library is missing; the plain build has no such dependency, and refuses web = true in bones.toml with an error instead.
Deliberately independent (ADR-029). An extension outlives the engine build that loaded it and may not be written in Rust, so one number cannot promise both audiences.
| Line | What it covers | Moves when |
|---|---|---|
engine — bones, bones-kernel |
the Rust API an embedder links | the library surface changes |
ABI — bones:extension, bones-messages, bones-wasm-sdk |
the contract a .wasm extension is built against |
the guest contract changes |
An extension author in Rust pins the ABI line, not the engine line:
[dependencies]
bones-wasm-sdk = { git = "https://github.com/an-dr/bones", tag = "abi-v1.3.0" }See CHANGELOG.md for what has moved.
| Platform | Status |
|---|---|
| Windows x64 and ARM64 | Supported. Tested in CI on every push and pull request, web panels included; released as archives |
| Linux x64 and ARM64 | Supported. Tested in CI on every push and pull request; released with and without web panels |
| Android | Planned — see docs/roadmap.md |
| macOS | Not built or tested. The engine is written to be portable and the SDL and wry backends are cross-platform; reports are welcome |
git clone --recurse-submodules https://github.com/an-dr/bones
cargo xtask doctor # what is missing, and where to get it
cargo xtask test # fixtures, gates, and every test
cargo run -p bones # run the engine you just builtIt needs a Rust toolchain and a C compiler with CMake, since the kernel infrastructure builds SDL3 from source — plus, on Linux, the development packages cargo xtask linux-packages lists. Nothing is installed for you. docs/contributing/building.md has every command; docs/contributing/testing.md what the suite gates.
| Project | What it is | Screenshot |
|---|---|---|
| commits | A desktop Git client. Embeds bones and runs its Git Graph view in a wry web panel | |
| crossWall | A cross-platform wallpaper manager that syncs across devices. Embeds bones as its engine | |
| DevPanel | A desktop dashboard for your git repositories: see which need a pull, push, or commit and fix them in one click. Built on bones | |
| artificial-will-game-v2 | A game about a robot named Will. Embeds bones and ships its gameplay as extensions | |
| copper | A manifest-first automation host for AI-generated extensions. Embeds bones for its settings UI and tray |
Built something on bones? Add the badge to your README, and open a pull request to list it here:
[](https://github.com/an-dr/bones)Start at docs/index.md — the architecture, detailed designs, decisions (ADRs), and worked examples. The short version:
- docs/architecture/ — the system: parts, structure, messaging, upgrading.
- docs/architecture/structure.md — what lives where and what may depend on what.
- docs/adr/ — why the design is the way it is.
- docs/roadmap.md — what comes next.
See CONTRIBUTING.md for how to build, test, and land a change, and docs/contributing/releasing.md for cutting a release — pushing a v* tag is the whole of it.
This project is developed openly with AI agents, at AI Level 3. The base agent policy — flows, roles, and skills — lives in an-dr/agents; AGENTS.md holds the rules specific to this repository.
Commits are authored by the person who reviewed and committed them. CI rejects any commit that credits an AI tool as a co-author: the tool is no more an author than the editor or the compiler.
MIT — see LICENSE.