The Aster Runtime is a shared library with one C header, aster.h (ABI 1.4; the header is MIT-licensed and the runtime ships under the Aster Runtime EULA). Your program keeps its own state and describes the screen as JSON; Aster renders it and calls you back with JSON events. There is nothing to link against except the library, and no Rust toolchain is needed on the consumer side.
Status: pre-1.0, signatures not frozen. The ABI is versioned (
ASTER_ABI_MAJOR1,ASTER_ABI_MINOR4); check the major version at start-up as the example does.Licence: the SDK and examples are MIT; the runtime ships under the Aster Runtime EULA. The commands below were run from a source checkout; with prebuilt binaries, use the delivered include and lib directories instead.
What we ran
Built on 2026-11-15 from aster-ui f19b91bcd (ABI 1.4) with Rust 1.98.0 in the project's toolchain image, from native/:
cd native
cargo build --release -p aster-runtime # produces libaster_runtime.so and the `aster` CLIThen compiled the quick-start program with warnings as errors, and ran it:
cd native/../site/content/snippets/c-abi
cc -Wall -Wextra -Werror -I ../../../../native/runtime/include hello.c \
-L <target>/release -laster_runtime -Wl,-rpath,<target>/release -o hello
./hello hello-c.pngOutput (verbatim, recorded on 2026-11-15 with the runtime built from f19b91bcd):
Aster Runtime 0.1.0, ABI 1.4
event: {"type":"action","action":"add","key":"","state":{},"selection":{}}
event: {"type":"action","action":"add","key":"","state":{},"selection":{}}
ui theme=mission-dark viewport=360x240
#heading-2 Heading rect=[20, 20, 320, 52.82]
#text-3 Text label="Counter" rect=[20, 20, 320, 33.88]
#text-4 Text label="from C" rect=[20, 55.88, 320, 16.94]
#stat-5 Stat rect=[20, 84.82, 320, 84.40]
#text-6 Text label="Clicks" rect=[36, 100.82, 288, 14.52]
#text-7 Text label="2" rect=[36, 119.34, 288, 33.88]
#add button rect=[20, 181.22, 320, 34] key=9 {focusable focused hovered}
#text-9 Text label="Add one" rect=[151.63, 189.75, 56.74, 16.94]
OKThe PNG it wrote has SHA-256 a6fc521f280e52fd6ee3dd8797b982871112ba629e91d7edd5722bb9d612e350. The repository's own smoke test (native/runtime/tests/smoke.c) renders the same app through a separate program and produced a byte-identical file (same SHA-256).
The program, annotated
snippets/c-abi/hello.c:
aster_abi_version()returnsmajor << 16 | minor. Refuse to run if the major differs fromASTER_ABI_MAJOR.aster_app_new(desc_json)creates an app from a descriptor:{"title","width","height","scale","theme","clock","state","view"}. Themes:dark(default),light,mission_dark,mission_light,mission_dusk,paper_dark,paper_light,high_contrast_dark,high_contrast_light.aster_app_on_event(app, cb, user)registers the callback. Events are JSON:{"type":"action"|"change","action":...,"key":...,"state":{...},"selection":{...}}. They are delivered on the UI thread only.aster_app_set_view(app, json)replaces the screen;aster_app_set_statemerges state; both may be called from any thread, including from inside the callback.- Headless driving, for tests and for tools that need to see the UI:
aster_app_click(app, "Label"),aster_app_type,aster_app_shot(app, "out.png"),aster_app_tree(app)(the semantic tree; free withaster_free). aster_app_run(app)opens a window and blocks until it closes (once per app).- Errors: functions returning
intgive 0 or -1; pointers giveNULL;aster_last_error()explains, per thread.
Threading in one paragraph: the thread that creates the app is the UI thread; the three setters (set_view, set_state, set_theme) may be called from any thread and are queued; everything else must be called on the UI thread or fails with a wrong-thread error and changes nothing. Free the app on the UI thread after other threads have stopped using it. The full contract is the comment at the top of aster.h.
Deterministic animation (ABI 1.2): create the app with "clock":"manual" and call aster_app_advance(app, ms) to play motion frame by frame; the same calls give the same pixels.
No code at all: the aster command-line tool
The same runtime ships a CLI, useful for design review and CI:
aster doctor # runtime and ABI version
aster shot app.json out.png # render headless to a PNG
aster tree app.json # print the semantic tree (labels, roles, rects)
aster click app.json "Say hi" # click a label headless, print the resulting tree and event
aster run app.json # open a window; events print as JSON linessnippets/c-abi/app.json is a complete app (a heading, a stat and a button). We ran aster shot app.json hello-json.png (SHA-256 b617f33d78bc1dc94b217795e67b4b32a219de20b73f774cc58d33d43844f64c) and aster click app.json "Say hi", which printed {"type":"action","action":"hi","key":"","state":{},"selection":{}}. The larger sample native/runtime/samples/garden.json renders to the "An app described as JSON" image in the gallery.
Not covered here
This guide covers the supported headless and window paths on Linux. Windows packaging (the Store package that ships the runtime) is described in docs/WINDOWS-STORE.md. The Rust facade and the wasm module are described in getting-started.md and wasm.md.
Every exported function
Generated from native/runtime/include/aster.h at aster-ui f19b91bcd (ABI 1.4, 25 functions).
| Function | Returns (parameters) | Note |
|---|---|---|
aster_abi_version | uint32_t (void) | major << 16 | minor; check major == ASTER_ABI_MAJOR |
aster_runtime_version | const char * (void) | static, do not free |
aster_last_error | const char * (void) | this thread's last error, "" when none |
aster_free | void (char *s) | free strings returned by aster_app_tree / aster_app_state |
aster_app_new | AsterApp * (const char *desc_json) | |
aster_app_free | void (AsterApp *app) | UI thread, after other threads stopped and no call on app is in progress |
aster_app_set_view | int (const AsterApp *app, const char *view_json) | |
aster_app_set_state | int (const AsterApp *app, const char *state_json) | merge a JSON object |
aster_app_on_event | int (const AsterApp *app, AsterEventFn cb, void *user) | |
aster_app_run | int (const AsterApp *app) | opens the window, blocks until closed; once per app |
aster_app_click | int (const AsterApp *app, const char *label) | |
aster_app_shot | int (const AsterApp *app, const char *png_path) | |
aster_app_tree | char * (const AsterApp *app) | free with aster_free |
aster_app_state | char * (const AsterApp *app) | free with aster_free |
aster_app_type | int (const AsterApp *app, const char *text) | type into the focused element (ABI 1.1) |
aster_app_set_theme | int (const AsterApp *app, const char *theme) | |
aster_app_set_clock | int (const AsterApp *app, int manual) | 0 auto (default), 1 manual |
aster_app_advance | int (const AsterApp *app, double ms) | clock += ms (fractions carry), render that frame |
aster_app_animating | int (const AsterApp *app) | 1 motion running or timer pending, 0 at rest, -1 error |
aster_app_pointer | int (const AsterApp *app, int kind, double x, double y) | |
aster_app_wheel | int (const AsterApp *app, double x, double y, double dy) | dy > 0 scrolls down; a notch is 40 |
aster_app_key | int (const AsterApp *app, const char *chord) | "enter", "ctrl+s", "shift+tab", "a": press + release |
aster_app_focus | int (const AsterApp *app, const char *id) | |
aster_app_resize | int (const AsterApp *app, uint32_t width, uint32_t height, double scale) | logical px, 0.25..8 |
aster_app_pixels | int (const AsterApp *app, uint8_t *rgba, size_t capacity, uint32_t *width, uint32_t *height) |
