API reference

Talk to the runtime.

Four surfaces, one model. The kernel API is capability-typed Rust. The energy bridge and MCP bridge are language-agnostic over HTTP/stdio. The browser embed is one line of JavaScript. Everything you measure comes back as a JCR-1 receipt.

crates/joule-os-kernel

The kernel API

Authority is a type. You cannot call a gated path without holding the capability for it — and you can only get one from the ledger.

use joule_os_kernel::{Ledger, Capability, NetworkSend};

// A capability can ONLY come from the ledger.
let cap: Capability<NetworkSend> =
    ledger.issue::<NetworkSend>(grant)?;

// Delegation only narrows — never widens.
let scoped = cap.attenuate(to_host("api.example"))?;

// Constructive revocation: invalidates derived caps too.
ledger.revoke(cap.generation());

use joule_os_kernel::{Intent, dispatch};

// One intent, resolved down the refine cascade.
let intent = Intent::parse("summarize surface 4")?;
let outcome = dispatch(&mut ctx, intent)?;

// Outcome carries which tier closed it + the cost.
assert!(outcome.tier <= RefineFamily::TinyRecursive);
println!("{} µJ  [{}]", outcome.joules_uj, outcome.prov);

Symbol	Kind	Purpose
Ledger::issue::<T>	fn	the only constructor of a Capability<T>
Capability<T>	type	unforgeable authority for one of 8 classes
Intent	type	a parsed request, lowered to the IR
dispatch	fn	resolves an intent down the cascade, returns tier + joules
RefineFamily	enum	L0 Lawful … L6 LlmInLoop
Oracle	trait	AppleSilicon / Rapl / Estimator
Receipt	type	seals a JCR-1 envelope

localhost:9911

Energy bridge — HTTP

Run joule-os-native --bridge and any client (including the browser PWA) can read live, measured energy.

$ curl -s localhost:9911/v1/energy | jq
{
  "oracle": "AmuAgx",          // measured, not estimated
  "uj_total": 4820391,
  "by_class": {
    "W_render":  { "uj": 3104882, "prov": "AmuAgx" },
    "W_infer":   { "uj":  812004, "prov": "AmuAgx" },
    "W_storage": { "uj":  140221, "prov": "AmuAgx" }
  },
  "ts": 1718500000
}

Method	Path	Returns
GET	/v1/energy	current per-class joule totals + provenance
GET	/v1/surfaces	live surfaces with per-surface attribution
POST	/v1/intent	dispatch an intent; returns tier + cost + receipt

crates/joule-os-mcp-bridge

MCP bridge — stdio

JouleOS exposes its dispatch + energy surface as Model Context Protocol tools, so an agent can drive the OS and read what every action cost.

# register the JouleOS MCP server (stdio JSON-RPC)
joule-os-mcp-bridge

# tools exposed:
#   jos.dispatch(intent)   -> { tier, joules_uj, prov, receipt }
#   jos.energy()           -> per-class totals
#   jos.surfaces()         -> workspace state
# every call gated by a Capability and sealed as JCR-1.

crates/joule-os-pwa

Browser embed — one line

The full shell is a ~2 MB WASM module. Drop the pkg/ output on any host and initialize it.

<script type="module">
  import init from '/pkg/joule_os_pwa.js';
  init();                       // creates its own <canvas id="joule-os">
</script>

Or boot the real bare-metal kernel inside the in-browser VM — see the live page. For the build steps, see Quickstart.