REFERENCE / FORMAT 1

A small language for big ideas.

The functions and components Lantern actually supports. Pages are structured data; Lua runs on the host.

Looking for step-by-step tutorials? Read the complete Lantern documentation →

Quick start Lua functions Components Responses Limits & security

quick.start

Your first handler.

Save this as app.lua. A package contains an optional handler plus JSON page files. Returning nil falls back to a matching static JSON page.

return function(ctx)
  local P = ctx.page
  return {
    kind = "page",
    page = P.document("Hello", {
      P.heading{text="Hello, other worlds!"},
      P.link{text="Explore", href="hub://directory/"}
    })
  }
end

Start from a template ↗

request.context

Built-in Lua functions.

ctx.method

GET or POST.

ctx.path

The requested site path, e.g. / or /sign.

ctx.fields

String/boolean form values. Validate them on the server.

ctx.requestId

A request identifier used for replay/duplicate handling.

ctx.page.document(title, children)

Build a version-1 page document.

ctx.page.<component>{...}

Construct any component in the table below.

ctx.read(key, default)

Read this site’s stored data; return default if missing.

ctx.write(key, value)

Persist JSON-compatible data on POST. Use alphanumeric/hyphen keys, 2–40 characters, for compatibility with local hosts.

The cloud environment exposes assert, error, ipairs, pairs, next, pcall, select, tonumber, tostring, type and the math, string, table, utf8 libraries. No os, io, require, package, load, debug, shell or arbitrary network access is exposed.

Each cloud request starts in a fresh isolated VM. Keep persistent state in ctx.read/ctx.write, not global variables. Local owner-installed Lua runs with the computer’s privileges and is not sandboxed.

page.components

Everything a page can be made of.

JSON pages use {"version":1,"title":"Hello","children":[...]}. Every node has a type. Lua builders add the type for you.

heading / paragraph

text
Titles and wrapped body text.

list

items: string[]
Up to 128 list items.

link

text, href
A relative site path, hub:// address or ln:// address.

image

rows: string[], text?
CC palette digits 0–f, spaces transparent. Up to 128 × 64 pixels.

section / columns

children
Group nodes; columns stack on narrow terminals.

form

action, children
Submits POST fields to a path on the same site. No nested forms.

input

name, text, password?
String field, up to 2,048 characters. password: true masks terminal input.

checkbox

name, text
Sends true or false.

select

name, text, options
Sends a selected string; 1–32 options.

submit

text
Submits its containing form.

Form field names contain letters, digits, underscores or hyphens, up to 40 characters. All fields must be inside a form. Input is untrusted: validate types, length and allowed choices in the handler.

handler.responses

Send something back.

{kind="page", page=P.document("Title", {...})}
{kind="redirect", path="/"}
{kind="error", status=400, message="Please enter a note"}
nil -- Fall back to a static JSON page

Redirects stay on the same site. The cloud protocol supports page, redirect and error responses. Local hosts also accept a bounded resource response, but arbitrary uploaded assets/resource delivery are not part of the current Hub package format.

boundaries.matter

Limits and safe patterns.

Page documents: 512 components, 12 levels of nesting, 128 KiB.
Upload package: 1–32 files, 256 KiB; app.lua up to 64 KiB. Other files must be valid page JSON.
Cloud site storage: 128 KiB. GET cannot persist writes. Concurrent conflicting writes are rejected; reload before resubmitting.
Lua execution: one million instructions, three-second process limit, 64 MiB JavaScript heap, 15-second VM lifetime. These are ceilings, not guaranteed capacity.
Per-site request and platform execution rate limits apply. Replay IDs prevent silent duplicate form execution.
Password masking only hides typing. Site operators receive submitted fields. Never reuse a real password in a demo; there are no site-user accounts, login sessions, password hashing or password-reset APIs built in.
Cloud requests use HTTPS. Local modem connections require seeded cryptography and fingerprint verification for independently verified identities.
History stores addresses. The browser caches GET pages, so do not return secrets in cacheable page documents.

Check service status →

shell.commands

At your computer.

lantern edit

Create, edit, validate, preview, host or upload a local site. The editor offers six templates.

lantern hub://help/

Other commands: lantern host, lantern publish name, lantern doctor, lantern update, lantern repair, lantern uninstall. Update and repair take a trusted offline installer path; uninstall keeps user data.

Follow the beginner walkthrough →