Luau Scripting on AntOS

AntOS hands the operating system to you through a scripting language. System tools, commands, monitors, network utilities, and UI behaviour are written in Luau and can be changed live. This is your starting point.

Want to write a command right now? The Script Developer Quickstart is the fast path — the os.arguments parser, the term.init() / term.shutdown() lifecycle, the console glyph set, and the conventions that make a new script feel native, with a full working example.

What Luau is

Luau is a fast, small, gradually-typed scripting language derived from Lua. It was created by Roblox and is developed in the open; AntOS embeds a Luau virtual machine compiled from the current official Luau repository, so the language and its built-in libraries track upstream Luau rather than any particular release of standard Lua.

That distinction matters, and it is the single most important thing to understand before writing scripts for AntOS:

Luau is not standard Lua. It is based on Lua 5.1, adds a type system and a number of modern language features, selectively incorporates features from later Lua versions, and — crucially for an embedded OS — removes or sandboxes the parts of the standard library that touch the host system. AntOS supplies its own libraries in place of the ones Luau sandboxes away.

If you have written Lua before, read how Luau differs from Lua first. The differences will trip you up otherwise — no goto, a single number type, bitwise work through bit32 rather than operators, and no standard io library are the ones that surprise people most. For the exhaustive, version-pinned list of every difference, see the complete Lua 5.1 → Luau reference; to port real code pattern by pattern, follow the migration tutorials.

Why AntOS uses Luau

AntOS runs on Linux on DeMon, the Raspberry Pi CM5 supervisor. Rather than compiling every tool and behaviour into the OS image, AntOS exposes the kernel — tasks, queues, timers, events, storage, UI, networking — to a Luau layer that can be inspected and rewritten at runtime. The design goal, stated plainly in the AntOS overview: if you can't do something weird with it, it's failed.

Luau is a good fit for this because it is:

  • Small and fast — the VM is compact and quick, with ample headroom on DeMon (the CM5), and Luau is among the fastest scripting languages of its class
  • Safe by construction — Luau is designed to be sandboxed, so handing the system to user scripts doesn't hand over the ability to wreck it
  • Familiar — Lua heritage means a gentle learning curve, while the optional type annotations help larger scripts stay maintainable
  • Self-contained — no external runtime, no package manager to provision on the device

The detailed pages

This document is the hub. The depth lives in three companion pages:

  • The Luau language — how Luau differs from standard Lua: the type system, continue, compound assignment, string interpolation, generalized iteration, if-expressions, the single number type, and the features Luau deliberately omits. Read this first if you know Lua.
  • Standard built-in libraries — the libraries that ship with the Luau VM itself: math, table, string, coroutine, bit32, utf8, os, buffer, vector, and the global functions. Also documents what the standard library deliberately leaves out, and why.
  • AntOS libraries — the libraries AntOS adds on top of the VM: io, os, fs, terminal, net, data, sys, ai, and more — what give scripts access to DBFS storage, the terminal, the network, and AI. Documented per library, each with a reference (antos_<lib>) and a binding page (luau_<lib>); the hub indexes them.

Where scripts live and how they run

AntOS storage is DBFS, a database-backed filesystem on SQLite, mounted as the D: drive. User scripts live under D:/scripts. The terminal locates a command by name there — typing speedtest runs D:/scripts/speedtest.lua.

Each script runs in the Luau VM with arguments passed in through the global arg table: arg[1] is the first argument, arg[2] the second, and so on, exactly as a shell would pass them. A script that needs its arguments typically starts with local args = arg or {} so it works whether or not any were supplied.

Storage handles files of essentially unlimited size through streaming BLOB I/O — DBFS uses SQLite's incremental BLOB interface, so a file is limited by disk space rather than by available RAM.

The help-header convention

Every well-behaved AntOS script follows a small convention so that the system help command can describe it without executing it — help scans D:/scripts and reads each script's header by pattern-matching the source text, never by running the script. A script declares three locals at the top and handles a ? argument:

local desc  = "Measure network throughput"
local long  = "Downloads a series of sized payloads from a CDN and reports " ..
              "the sustained transfer rate. Use -q for a quick single-sample run."
local usage = [[
speedtest
speedtest -q
speedtest ?
]]

local args = arg or {}
if args[1] == "?" then
    -- print desc / long / usage and exit
    return
end

-- ... the actual script ...
  • desc — a one-line summary, shown in command listings.
  • long — a fuller description, shown when help is requested for that specific command.
  • usage — the invocation forms, usually a [[ ]] long string.
  • args[1] == "?" — when the user runs command ?, the script prints its own help and exits rather than doing its work.

Keeping to this convention means a new script becomes self-documenting the moment it is dropped into D:/scripts — help picks it up automatically.

A note on the terminal

Scripts that produce terminal output use the AntOS terminal library, required as require("terminal") (conventionally aliased term). It provides coloured, attributed output and, for interactive tools, an application mode with cursor control and key input. The exact API — and the rules around when a script must initialise and tear down the terminal — is documented on the AntOS libraries page.

Where to go next

Important: The Ant64 family of home computers are at early design/prototype stage, everything you see here is subject to change.