Mojo Quickstart

Mojo Quickstart

Call the signed Algenta native runtime from a Mojo program — no Python glue, no HTTP server, just the Mojo standard library and direct C FFI. Source: examples/mojo-quickstart/.

The engine (closed source) compiles its numeric kernels with Mojo and ships them inside the signed algenta-runtime-native wheel on PyPI. This example drives that artifact directly from Mojo.

Run it

Prerequisites: pixi, and a platform with a published runtime wheel — macOS on Apple Silicon (macOS 14+) or Linux x86_64 with glibc ≥ 2.35 (Ubuntu 22.04+). There is intentionally no Windows or Intel-macOS runtime wheel.

git clone https://github.com/thyn-ai/algenta-sdk
cd algenta-sdk/examples/mojo-quickstart
pixi run demo

First run resolves the Mojo toolchain (Modular's stable max channel), CPython 3.14, and the signed runtime wheel, compiles main.mojo, and produces:

Algenta × Mojo quickstart
  python prefix:  …/examples/mojo-quickstart/.pixi/envs/default
  runtime worker: …/site-packages/algenta_runtime_native/algenta-runtime-worker
  launching worker …
  connected: /tmp/algenta-mojo-demo-11782.sock
  < handshake: {"status":"ready"}
  > ping: {"type":"ping"}
  < {"status":"ok"}
  > library_execute activations.gelu: {"type":"library_execute","module":"activations","function":"gelu","args":[1.0]}
  < {"result":0.841191990607477}
  ✓ activations.gelu(1.0) = 0.841191990607477 (deterministic)
  > shutdown: {"type":"shutdown"}
  < {"status":"bye"}
ok: handshake, ping, library_execute and shutdown all succeeded

Command	What it does
pixi run demo	build main.mojo, then run the demo
pixi run build	compile only, to ./algenta-mojo-demo
pixi run dev	compile + run in one step (mojo run)

Any failure prints an error: diagnostic and exits 1.

What it demonstrates

1. Artifact resolution — locates the runtime worker executable inside the pixi-installed Python environment.
2. Process management — spawns the worker with std.os.process.Process, configuring the embedded-interpreter environment it expects (PYTHONHOME / MOJO_PYTHON_LIBRARY).
3. Mojo FFI — speaks the runtime's wire protocol through raw external_call bindings to libc (socket, connect, poll, send, recv). Mojo's stdlib has no socket module yet, so main.mojo doubles as a compact reference for POSIX FFI in Mojo.
4. Deterministic round-trip — the worker evaluates activations.gelu(1.0) and the demo verifies the result before exiting 0.

The wire protocol (public, stable)

launch:    algenta-runtime-worker --server <unix-socket-path>
handshake: worker sends {"status": "ready", ...}     (fields are additive)
ping:      > {"type": "ping"}                        < {"status": "ok"}
execute:   > {"type": "library_execute", "module": M, "function": F, "args": [...]}
           < {"result": ...}
shutdown:  > {"type": "shutdown"}                    < {"status": "bye"}

Every frame is a 4-byte big-endian length followed by a UTF-8 JSON payload, in both directions.

Environment overrides

Variable	Meaning
ALGENTA_RUNTIME_LIB	Absolute path to an algenta-runtime-worker executable. Overrides site-packages resolution.
CONDA_PREFIX	Set automatically by pixi run; used as the worker's PYTHONHOME. Outside pixi, the demo falls back to a python3.14 on PATH.

The worker embeds CPython 3.14 but ships no standard library, so PYTHONHOME must point at a real interpreter installation — the pixi environment provides one automatically.

What the signed runtime is (and isn't)

algenta-runtime-native is a wheels-only, per-platform PyPI package carrying the prebuilt runtime: sharded algenta-runtime-worker executables (the compiled Mojo kernels), a manifest.json with SHA-256 hashes of every artifact, and a detached manifest.sig signature. The wheel is proprietary data — it contains no importable public API.

When you use the full Python client (pip install algenta), the SDK verifies the manifest signature and every artifact hash against its embedded trust anchor before it will execute the runtime — fail-closed. This quickstart instead relies on the install path itself (pip/uv verify wheel hashes against PyPI; pixi.lock pins exact versions) and focuses on the Mojo-side mechanics. Treat it as a language-integration example, not a hardened client.

Files

examples/mojo-quickstart/
├── pixi.toml           # workspace: max (Mojo) + CPython 3.14 + the runtime wheel
├── pixi.lock           # pinned, reproducible resolution (commit it)
├── main.mojo           # the demo — read it top to bottom
└── recipe/recipe.yaml  # rattler-build recipe for the modular-community channel

Where next

• Architecture → Execution paths — where this worker fits
• Security → Supply-chain verification — the signature story
• thyn-ai/mojo-kernels — clean-room Mojo kernels you can read and vendor (BM25, fuzzy search, electron-density grids)