Ajo Engine
Overview
What the engine is, what it is not, and the verified platforms.
Ajo Engine runs an Ajo Kit application in production as a small, isolated Linux process. It is built on QuickJS-NG and executes one thing: a sealed artifact of precompiled bytecode whose manifest declares what the application may touch. Kit owns the application framework and Ajo Server owns deployment and containers; the engine owns execution and the native capabilities underneath.
Two programs, one release
The engine ships as two native npm packages built from the same source tree.
| Package | Runs on | What it does |
|---|---|---|
ajo-engine | The production host or container | The runtime: a parserless QuickJS-NG core, an epoll reactor and the narrow capability surface Kit applications need. |
ajo-engine-compiler | The build host | The toolchain: compiles a Kit build into a sealed bytecode artifact that the runtime loads. |
Both are static PIE executables linked with musl. They have no installation scripts, downloaders or runtime npm dependencies, and the installed binary runs without Node. Always use the same version of both packages: the runtime only loads bytecode written for its own engine pin, which the PIN file in each package names.
Each package also carries SHA256SUMS and PROVENANCE.json, which identify its contents and recorded build inputs. These local records do not authenticate a publisher or prove reproducible builds. Ajo-authored code is ISC licensed; linked third-party code keeps the licenses and notices listed in THIRD_PARTY.md and licenses/.
What it is not
The engine is deliberately narrow. It exists to run Kit applications, and it gives up generality to keep the production process small and its authority explicit.
- Not a Node replacement. It does not emulate Node, and general Node compatibility is not planned. Node remains the development, build and test host; it is not an alternative production runtime.
- No source evaluation. The production binary has no JavaScript parser and no REPL. It executes sealed bytecode, never JavaScript or TypeScript source, and calling
evalornew Functionthrows. - No Node module loader and no native add-ons. Modules come only from the artifact and from the engine’s own
runtime:*modules. Kit’s build rejects Node builtins before anything is compiled. - Not a browser. Web-style globals such as
fetch,URLandIntlare a deliberate subset, not browser or Node parity.
From source to a running app
Kit builds the server modules, the client assets and a compiler descriptor into
.ajo/. Node hosts this step only.ajo-engine-compilervalidates the declared module graph, compiles it with QuickJS-NG and writes a sealed artifact.ajo-enginevalidates the artifact and its pin, installs its native modules and precompiled prelude, then evaluates the entry module.The reactor dispatches I/O, timers and worker completions and drains JavaScript jobs. JavaScript stays on a single thread.
On a verified Linux host with the pair installed, the whole path is two commands, kit build and ajo-engine dist/ajo; Seal and run walks through them.
What an application can use
The runtime provides a small set of native capabilities, each exposed as a runtime:* module that an artifact must declare before it can import it.
| Area | Provided by the engine |
|---|---|
| HTTP | An HTTP/1.1 server with bounded bodies and connection budgets, server-sent events and static files. |
| Outbound requests | A bounded HTTP(S) client with TLS verification, used by the global fetch; only global destinations. |
| SQLite | Connections, prepared statements and consistent online backup. |
| Cryptography | SHA-256, HMAC, Argon2id, Ed25519 keys and signatures, ES256 and RS256 verification, and age file encryption. |
| Filesystem | Operations confined to the roots the artifact declares. |
| IPC | Atomic writes to exact, declared FIFOs. There is no process execution. |
Kit applications normally reach these through Kit itself rather than importing them. The runtime surface lists every module, export and limit.
Verified platforms
The packages declare Linux and x64 in their npm metadata. These are the environments where both executables have been verified:
| Environment | C library | Status |
|---|---|---|
| Linux x64, Alpine 3.24.1 | musl 1.2.6 | Verified |
| Linux x64, Freedesktop 25.08 runtime | glibc 2.42 | Verified |
| macOS | No support claimed | |
| Windows | No support claimed | |
| ARM, on any system | No support claimed |
No support is claimed for an untested minimum Linux kernel either. Because the binaries are static, no libc package is needed on the host. Installed as optional dependencies, as Seal and run shows, they are skipped by pnpm on any other system. A package manager may add its own command shim, but the packaged executable has no Node or shell dependency.
Pre-release status
Both packages are pre-release: changes to the artifact format or the runtime modules still need coordinated compiler and runtime pins. The engine’s source repository is not public yet; the two npm packages are its public release.
- Seal and runInstall the native pair, seal a Kit build and start it.
- The artifactWhat a sealed directory contains and why loading fails closed.
- Runtime surfaceThe runtime modules, the web globals and their limits.
- Security modelWhat the engine enforces and what it leaves to the host.
Full reference: ajo-engine on npm