Lua Modules, Tools, and Examples

Overview

This repository contains ready-to-use Lua modules, tools, Lua scripts, and Lua Server Pages (LSP) examples that can be dropped directly into real applications or used as practical reference material. The examples cover common web and device use cases for the Barracuda App Server, Mako Server, and Xedge product family, including forms, REST services, AJAX and WebSocket interaction, authentication, databases, IoT messaging, and embedded-device workflows.

If you are new to Lua, start with the online Lua tutorial.

AI-assisted development

The root AGENTS.md teaches an AI agent how to work correctly with BAS, Mako Server, Xedge, Xedge32, LSP, routing, authentication, SQLite, SMQ, and browser interfaces. Prepared examples also include local AGENTS.md files with more specific instructions.

Start a new project

Copy AGENTS.md into the root of the new working directory and keep the filename unchanged. Start the AI agent in that directory and use this bootstrap prompt:

Read and follow AGENTS.md. Complete its mandatory reference bootstrap before
doing any work. If downloading is blocked, request the required permissions; if
that fails, give me the exact download links and destination paths.

Then inspect this workspace and tell me what you found. Do not change any
application files until you have confirmed the target runtime, application
root, and relevant example or architecture with me.

The agent downloads the required API references and skills into .agents/reference/rtl/, then uses them as the source of truth for the work. For an offline project, copy the complete reference directory together with AGENTS.md.

Develop on a running system with LSP-Claw

LSP-Claw is an MCP server that lets an AI agent inspect examples, create files, run a controlled lab app, and debug Lua/LSP code directly on Mako Server, Xedge, or Xedge32. Use it when the agent should select an example, build and test the application, and inspect runtime trace output without modifying production code first.

On embedded systems, LSP-Claw can restart or replace only the lab application without restarting the device, RTOS, or hosting server.

Files

• Basic HTML form - Source code for the tutorial HTML Forms and LSP for Beginners.
• Anti-Session - Shows how to carry a browser state through multiple pages without using a server session.
• Authentication
  • Authentication and Authorization - Use of the JSON Authenticator with a file server.
  • General - Introduction to the Barracuda App Server authentication mechanism.
  • OAuth 2.0 - Example showing GitHub OAuth 2.0 access.
  • RADIUS - RADIUS integration for BAS authentication.
  • Single Sign On - Single Sign-On example designed to avoid pre-installed password vulnerabilities.
  • WebAuthn - Passwordless, FIDO2-compliant authentication examples.
• CGI Plugin and Examples - CGI compatibility layer implemented in Lua.
• CryptoIO - AES-GCM file encryption
• Debug Lua - Visual Studio Code debugging workflow for Lua and LSP.
• Dynamic Navigation Menu
• Email + Logging - Sending email directly and through the Mako logging system.
• File Upload, including drag and drop
• GitHub IO - GitHub repository presented as a BAS file system.
• How to add require search paths to an app
• htmx Examples - htmx + LSP examples for server-rendered interactive pages.
• IoT
  • ESP32 Microcontroller Examples - Examples designed for Xedge32.
  • MQTT and AWS - AWS IoT Core connection example.
  • MQTT Broker - A ready-to-use MQTT broker and example code.
  • MQTT Sparkplug - Sparkplug library notes and example applications.
  • SMQ Examples - Device-management and messaging examples built on SMQ.
• MinnowSim - Source code for the tutorial Your First Embedded Single Page Application.
• QNX: PPS to SMQ Bridge - Extension example for QNX Persistent Publish Subscribe.
• REST / AJAX / RPC - different names, same idea
  • AJAX / REST / RPC Over WebSockets
  • AJAX / REST: For Beginners
  • RESTful - Designing RESTful services in Lua.
• Sockets and WebSockets examples
• SQL
  • MySQL and Redis Examples
  • PostgreSQL Example
  • SQLite Examples
• The ephemeral request/response environment
• Web Shell
• WebDAV and Web File Server
• Website Template Engine for Embedded - Embedded dashboard templates with optional TPM-backed user database support.
• Xedge App Deployment - Source layout for packaging MyApp.zip for Mastering Xedge Application Deployment: From Installation to Creation.

How to run

There is no single startup command for the repository as a whole. Open the README in the specific subdirectory you want to explore and run that example from its own directory.

How it works

Each subdirectory is a mostly self-contained example application, module, or tutorial companion. Some entries are ready-to-run Mako apps, some are reusable Lua modules, and some are index pages that point you to a smaller example beneath them.

Notes / Troubleshooting

Most of the examples include hidden files or directories such as .preload, .config, or .lua. In BAS products, resources whose names start with a dot are hidden from HTTP clients and are intended for server-side use only. On Linux, use:

ls -a

to make sure you see the complete example structure.