Sandbox Environment

Application runtime and APIs

Overview

LuajitOS applications run in a sandboxed Lua environment with restricted access to system resources. Each app receives specific globals based on its declared permissions in manifest.lua.

Core Tables Available to All Apps

app - Application Instance

The app object represents the current application instance:

Property/Method	Description
`app.pid`	Process ID (1000-65535)
`app.appName`	Application name
`app.appPath`	Path to application directory
`app.status`	Current status: "initialized", "running", "paused", "stopped"
`app.windows`	Array of windows created by this app
`app.stdout`	Captured print output
`app:newWindow(x, y, w, h, resizable)`	Create a new window
`app:newWindow(title, w, h, resizable)`	Create centered window with title
`app:newWindow(w, h, resizable)`	Create centered window
`app:export({name, func, args, rets, description})`	Export function for IPC
`app:call(functionName, ...)`	Call exported function
`app:listExports()`	Get array of exported function names
`app:getInfo()`	Get app metadata table
`app:terminate()`	Terminate the application
`app:writeStdout(text)`	Write to stdout buffer
`app:getStdout()`	Get stdout buffer content
`app:enterFullscreen()`	Create fullscreen window (1024x768)

window - Window Object

Created via app:newWindow():

Property/Method	Description
`window.x`, `window.y`	Position on screen
`window.width`, `window.height`	Window dimensions
`window.title`	Window title string
`window.visible`	Visibility state
`window.gfx`	Graphics context for drawing
`window.onDraw`	Draw callback function
`window.onClick`	Click handler function
`window:onInput(callback)`	Set keyboard input handler
`window:show()`, `window:hide()`	Control visibility
`window:close()`	Close window (can cancel via onClose)
`window:resize(w, h)`	Resize window
`window:setSize(w, h)`	Alias for resize
`window:setPos(x, y)`	Move window
`window:markDirty()`	Request redraw
`window:render()`	Flush drawing to screen
`window:getWidth()`, `window:getHeight()`	Get dimensions
`window.onClose`	Return true to cancel close
`window.onResize`	Called on resize(newW, newH, oldW, oldH)

window.gfx - Graphics Context

Drawing operations within a window:

Method	Description
`gfx:clear()`	Clear drawing buffer
`gfx:fillRect(x, y, w, h, color)`	Draw filled rectangle
`gfx:drawRect(x, y, w, h, color)`	Draw rectangle outline
`gfx:drawText(x, y, text, color, scale)`	Draw text
`gfx:drawImage(image, x, y, w, h)`	Draw image
`gfx:drawPixel(x, y, color)`	Draw single pixel
`gfx:getWidth()`, `gfx:getHeight()`	Get drawable area size

Colors are specified as hex: 0xRRGGBB

cli - CLI Buffer

For text-based output:

Method	Description
`cli.write(text)`	Append text to buffer
`cli.writeLine(text)`	Alias for write
`cli.getText()`	Get all buffer content
`cli.clear()`	Clear buffer

args - Command Line Arguments

Property	Description
`args.str`	Original argument string
`args[1]`, `args[2]`, ...	Positional arguments
`args.flagName`	Flag values (--flag value or -f value)

Permission-Based APIs

filesystem Permission → fs

Sandboxed filesystem access (SafeFS):

Method	Description
`fs:read(path)`	Read file contents
`fs:write(path, content)`	Write file contents
`fs:open(path, mode)`	Open file handle ("r", "w", "a")
`fs:dirs(path)`	List directories in path
`fs:files(path)`	List files in path
`fs:exists(path)`	Check if path exists
`fs:getType(path)`	Returns "file", "directory", or nil
`fs:mkdir(path)`	Create directory
`fs:delete(path)`	Delete file or directory
`fs:copy(src, dest)`	Copy file
`fs:move(src, dest)`	Move/rename file
`fs:getCWD()`	Get current working directory
`fs:setCWD(path)`	Set current working directory
`fs:join(...)`	Join path components
`fs:fileName(path)`	Get filename from path
`fs:parentDir(path)`	Get parent directory
`fs:resolvePath(path)`	Resolve ~, $ placeholders
`fs:addFileHandler(ext, funcName)`	Register file type handler

Path placeholders:

$ → App directory (e.g., /apps/com.dev.myapp)
~ → User home directory (/home)

system-all Permission → sys

System management (requires system-hook for sys.hook):

Property/Method	Description
`sys.applications`	Table of running apps by PID
`sys.environments`	Sandbox environments by PID
`sys.activeWindow`	Currently focused window
`sys.screen[1]`	Screen info: .width, .height, :setResolution()
`sys.hotkeys`	Registered hotkeys table
`sys.registerApplication(app)`	Register an app
`sys.unregisterApplication(pid)`	Unregister an app
`sys.getAllApplications()`	Get all running apps
`sys.addHotkey(scancode, modifiers, event, handler)`	Register hotkey
`sys.addHotkeyString(combo, handler)`	Register hotkey (e.g., "ctrl+alt+r")
`sys.removeHotkey(scancode, modifiers, event)`	Remove hotkey
`sys.sendInput(key, scancode)`	Route input to active window
`sys.setActiveWindow(window)`	Set active window
`sys.openFile(filepath)`	Open file with registered handler
`sys.browser:newHTMLWindow(options)`	Create HTML-based window

Modifier constants: sys.MOD_SHIFT, sys.MOD_CTRL, sys.MOD_ALT, sys.MOD_META

Key constants: sys.KEY_A through sys.KEY_Z, sys.KEY_ENTER, sys.KEY_ESCAPE, sys.KEY_SPACE, etc.

system-hook Permission → sys.hook

Event hook system:

Method	Description
`sys.hook:add(event, name, callback)`	Register event hook
`sys.hook:remove(event, name)`	Remove specific hook
`sys.hook:run(event, ...)`	Trigger event hooks
`sys.hook:getHooks(event)`	Get hook names for event
`sys.hook:getEvents()`	Get all event names

System events:

ApplicationStart — App started
WindowCreated — Window created
WindowClosed — Window closed

draw Permission

Graphics and image functions:

Function	Description
`VESASetMode(w, h, bpp)`	Set display mode
`VESAClearScreen(color)`	Clear screen
`VESAFillRect(x, y, w, h, color)`	Draw filled rectangle
`VESADrawString(x, y, text, color)`	Draw text
`PNGLoad(data)`	Load PNG from binary data
`BMPLoad(data)`	Load BMP from binary data
`ImageDraw(img, x, y)`	Draw image
`ImageDrawScaled(img, x, y, w, h)`	Draw scaled image
`ImageGetInfo(img)`	Get image info {width, height}
`ImageGetWidth(img)`, `ImageGetHeight(img)`	Get dimensions
`ImageGetPixel(img, x, y)`	Get pixel r, g, b, a
`ImageDestroy(img)`	Free image memory

imaging Permission → Image

Image creation and manipulation library:

Method	Description
`Image.new(w, h, hasAlpha)`	Create new image
`Image.load(path)`	Load PNG file
`Image.open(path)`	Load PNG or BMP (auto-detect)
`img:writePixel(x, y, color)`	Set pixel
`img:readPixel(x, y)`	Get pixel as hex string
`img:getPixel(x, y)`	Get pixel as {r, g, b, a}
`img:setPixel(x, y, rgba)`	Set pixel from {r, g, b, a}
`img:fill(color)`	Fill entire image
`img:clear()`	Clear to transparent
`img:fillRect(x, y, w, h, color)`	Draw filled rectangle
`img:drawLine(x1, y1, x2, y2, color)`	Draw line
`img:addImage(src, x, y, w, h, opacity)`	Alpha composite
`img:saveAsPNG(path, options)`	Save as PNG
`img:saveAsBMP(path, options)`	Save as BMP
`img:clone()`	Create copy
`img:getSize()`	Returns width, height
`img:getInfo()`	Get metadata table
`img:getBuffer()`	Get raw binary data

network Permission → http

SafeHTTP with domain restrictions:

Method	Description
`http:get(url)`	HTTP GET request
`http:post(url, body, contentType)`	HTTP POST request

Allowed domains must be declared in manifest.allowedDomains.

import Permission → apps

Access to other running applications:

local otherApp = apps["com.dev.otherapp"]
if otherApp then
    local result = otherApp:call("exportedFunction", arg1, arg2)
end

run Permission → run()

Launch other applications:

local success, appInstance = run("appname")
local success, appInstance = run("appname", "arg1 -v")
local success, appInstance = run("appname", "arg1", "-v")

ramdisk Permission

Direct ramdisk access:

Function	Description
`CRamdiskOpen(path, mode)`	Open file handle
`CRamdiskRead(handle)`	Read file content
`CRamdiskWrite(handle, data)`	Write to file
`CRamdiskClose(handle)`	Close handle
`CRamdiskList(path)`	List directory
`CRamdiskExists(path)`	Check if path exists
`CRamdiskMkdir(path)`	Create directory
`GetManifest(appId)`	Get app manifest table

load Permission → loadstring()

Dynamic code execution:

local func, err = loadstring(code, chunkname, env)
-- env defaults to sandbox_env if not provided

scheduling Permission → os.schedule

Task scheduling API (from Scheduler.lua).

system Permission → system

Read-only system information:

local apps = system.getApplications()  -- List running apps

admin Permission

Administrative functions:

Function	Description
`ADMIN_AppAddPermission(app, permission)`	Grant permission
`ADMIN_AppAddPath(app, path)`	Add allowed path
`ADMIN_StartPrompt(app)`	Start admin prompt
`ADMIN_FinishPrompt(app, success)`	Complete admin prompt

Timer API

Available to all apps with auto-namespacing:

Method	Description
`Timer.simple(name, seconds, callback)`	One-shot timer
`Timer.new(name)`	Configurable timer
`Timer.get(name)`	Get timer by name
`Timer.remove(name)`	Remove timer
`Timer.list()`	List all timers

Timer object properties:

timer.interval — Delay in seconds
timer.autoReset — Auto-restart after elapsed
timer.repeats — Number of repeats (or true for infinite)
timer.onElapsed — Callback function

Timer methods: timer:start(), timer:stop(), timer:reset(), timer:destroy()

Dialog Library

Available to all apps:

Dialog.fileOpen(startPath, options)

File open picker. Returns dialog object.

Dialog.fileSave(startPath, defaultName, options)

File save picker with filename input.

Dialog.confirm(message, yesText, noText, options)

Confirmation dialog with two buttons.

Dialog.prompt(message, autocompleteValues, options)

Text input dialog with optional autocomplete.

Dialog.promptPassword(message, options)

Password input (masked with asterisks).

Dialog.alert(message, options)

Simple alert with OK button (shows immediately).

Dialog methods:

dialog:openDialog(callback) — Show and get result
dialog:onSuccess(callback), dialog:onCancel(callback) — Set callbacks
dialog:show(), dialog:close() — Visibility control

Built-in Globals (All Apps)

Global	Description
`print(...)`	Output to stdout and CLI buffer
`osprint(...)`	Direct kernel output (debugging)
`require(moduleName)`	Load module from app's src/ or /os/libs/
`tonumber`, `tostring`, `type`	Type conversion
`pairs`, `ipairs`, `next`	Iteration
`pcall`, `xpcall`, `error`, `assert`	Error handling
`setmetatable`, `getmetatable`	Metatable access
`string`, `table`, `math`, `bit`	Standard libraries
`crypto`	Cryptography library
`Dialog`	Dialog library
`os.date`, `os.time`, `os.clock`, `os.difftime`	Safe os functions