lua apps upgrade against lua-cli 3.55.0; view-only access, route logs and the per-agent limits against lua-cli 3.59.0.
Before you begin
- An app created with
lua apps new <name>, withnpm installrun in itsweb/folder. @lua-ai-global/app-clientinstalled inweb/, 0.1 or later for a page with no theme code (see Switch to the client package if your app hasweb/src/lua/client.ts).
Define the app
A web app is one file,src/apps/<name>/app.ts, that default-exports defineWebApp({...}). List it under webApps on your LuaAgent; lua apps new does both.
src/index.ts
defineWebApp takes:
lua compile fails with a clear message when the name, a route key, or a nav entry is wrong, or when the app has no routes.
Write a route
A route key is a method (GET, POST, PUT, PATCH, or DELETE), one space, and a path. A path segment that starts with : is a parameter. Wrap each handler in route() so the schemas are checked and the handler’s arguments are typed.
src/apps/ops-dashboard/app.ts
route() takes:
The handler’s return value is the response:
- A value (an object, an array) answers 200 with it as JSON.
undefinedanswers 204 with no body.json(value, status, headers?)sets the status.json(undefined, 204)answers with no body.- A Web
Responseis sent as it is.
code is HANDLER_ERROR. Every error the platform produces has the body { code, message }; a body your handler returns is passed through as it is.
A Zod .default() in a query or body schema fills the value in at runtime, but the handler’s type still allows undefined. Add ?? <default> where you read it, as query.status ?? 'open' above.
What a route can use
Routes run in the Lua sandbox, the same place as your tools and webhooks:authis the person using the page:userId,orgId,agentId,roles,scopes,accessLevel, andnameandemailwhen known. It is never an API key and never anonymous, so you can record who made a change.accessLevelis'full', or'view_only'for someone who can open only this app (Who can open the app); a view-only person has emptyrolesandscopes.Dataand the other runtime objects work as they do in a tool.env('KEY')reads the agent’s environment variables. Set them withlua env.fetchcalls your own APIs. The page never sees the keys you use here.Workflows.viewerdecides a workflow approval or answers a waiting step as the signed-in person, not as the agent (Decide approvals from a route).
Call routes from the page
The page project inweb/ is a normal Vite + React project. The template uses @lua-ai-global/ui components and Tailwind v4; add any npm package you need. The page talks to your routes through @lua-ai-global/app-client. With @lua-ai-global/app-client 0.1 or later (the template of lua-cli 3.55.0 and later, or any app after lua apps upgrade), lua.start() also applies the shell’s look to the page, so main.tsx needs nothing else (Look and theme). On an older client, keep the theme lines your template wrote until you upgrade:
web/src/main.tsx
web/src/App.tsx
The session lives in memory only. The page keeps no token in cookies or storage, and a reload asks the shell for a new session.
A link to another site (
http or https on another origin), and a mailto: or tel: link, opens in a new window, so the app stays where it is. Links within the app and download links behave as usual.
Look and theme
Apps made with lua-cli 3.55.0 or later use@lua-ai-global/ui 0.3, the same design as Lua Workspace: flat surfaces, a 6px radius, denser controls, and the Inter font. The page follows the person who opens it, with no code of yours:
@lua-ai-global/app-client0.1 applies the shell’s light or dark mode, its density, and the person’s accent (the colour they picked in Lua Workspace) to the page’s<html>, when the page callslua.start()and again whenever the shell changes them.- Don’t manage the theme in the page. Keep
void lua.start()inmain.tsxand leave out any code that toggles thedarkclass. - Colour the page with the semantic tokens
@lua-ai-global/uidefines, such asbg-background,bg-card,text-foreground,text-muted-foreground,bg-primary,text-primary-foreground, andborder-border. A palette class likebg-blue-500or a hex colour stays the same whatever accent or mode the person uses.
web/src/App.tsx
@lua-ai-global/ui/page (PageColumn, PageTitle, PageSection, Panel, StatGrid, Stat), @lua-ai-global/ui/list-row (ListRow), and @lua-ai-global/ui/empty-state (EmptyState). Import each component from its own path.
Find components and their props
The catalog of@lua-ai-global/ui, with every component’s props, variants, and example code, is a public MCP server at https://ui.lua.dev/mcp. It needs no sign-in. Add it to your coding assistant so it checks a component before writing it:
list-all-documentation (every component) and get-documentation (one component, for example button or list-row). The catalog follows the latest release of @lua-ai-global/ui. If a component isn’t in the version your app has installed, run lua apps upgrade <name> before using it.
Upgrade an older app
An app made with an olderlua apps new is on @lua-ai-global/ui 0.2 and sets the theme itself. Bring it up to the current template:
@lua-ai-global/ui and @lua-ai-global/app-client to the template’s versions, removes the old template’s theme lines from main.tsx, and takes out the agent pane that lua-cli 3.53.0 and 3.54.0 bundle (<AgentPaneLayout> and @lua-ai-global/app-chat), since Lua now adds the pane itself (Move an older app off the bundled pane). Version 0.3 keeps every export and variant name of 0.2, so your pages need no code changes. Look them over with lua apps dev ops-dashboard, push the app, and open the pushed version with lua apps preview before you deploy it.
An app still on @lua-ai-global/ui 0.2 is shown with the new design’s colours and shapes where Lua can apply them, but it doesn’t get the new components or follow the person’s accent and density. Upgrade it to get all of that. From lua-cli 3.56.0, lua push and lua apps dev print a warning for an app whose pages are on a version below 0.3; the warning does not stop the push.
Decide approvals from a route
A route that approves or denies a workflow approval, or answers a step that waits for input, callsWorkflows.viewer. The decision is made as the person using the page, exactly as if they decided it in the inbox: the platform checks that they can see the agent and that they may approve this step (approver lists, four-eyes, the initiator exclusion), and records them as the decider. The agent never decides. Available in lua-cli 3.50.0 and later.
src/apps/ops-dashboard/app.ts
agentIdnames the agent whose run it is, for an app that shows several agents’ approvals. It defaults to the app’s own agent, and the person must be able to decide that agent’s runs.- Only in a route handler for a
POST,PUT,PATCHorDELETEcall. Anywhere else, including aGETroute, a tool or a job, it throws withcode === 'viewer_unavailable'. - An approval that needs a fresh sign-in or a particular surface answers
STEP_UP_REQUIREDorAPPROVAL_SURFACE_DENIED; send the person to the inbox for those. Other refusals keep their own codes, such asNOT_AN_APPROVER,FOUR_EYES_REQUIRED,APPROVAL_NOT_FOUNDandPAYLOAD_MISMATCH. - Under
lua apps devandlua test webappthe route runs as you, so the call is made with your own CLI sign-in.
403 DECISION_ORIGIN_DENIED.
Run and test locally
lua apps dev <name> serves the page on the app’s own Vite server with hot reload, and runs each route in the sandbox on your machine as you. Data and env() are the live ones, so writes are real. lua test webapp calls a single route:
auth.roles is empty: who may open an app is decided by the platform, not on your machine. See lua apps and lua test.
Release a version and roll back
lua push webapp builds the page with the app’s Vite and creates a web-app version. It is staged, not live. lua deploy webapp makes it live on its own, without taking anything else you staged on the agent live:
lua push webapp --auto-deploy does both in one step. To roll back, deploy the previous version: lua deploy webapp --name ops-dashboard --set-version <version> --force. When a deploy fails, the app keeps serving what it served before. lua deploy webapp needs lua-cli 3.49.0 or later.
To release a web app together with other changes, use an agent version: lua version create pins the latest pushed version of every primitive, web apps included, and lua version promote <n> makes them live at once. Bare lua push and lua push all --force push web apps too. See Release an agent to production.
Preview a version before it is live
To click through a version you pushed before anyone sees it, open a preview:Data, but their writes go to a copy that is deleted when the preview ends. Emails and messages are recorded, not sent, and fetch calls fail with TEST_EGRESS_BLOCKED. Anyone who can edit the agent can open the link. A preview lasts 24 hours by default. See lua apps preview; it needs lua-cli 3.51.0 or later.
Who can open the app
Open a live app by URL, or in the Lua desktop app:
The app opens full page. Who can use it depends on whether they can read the agent:
Access is checked on every request. View-only access ends as soon as the share is removed, the person who shared it loses access to the agent or leaves the organization, the app stops showing to the whole organization, or the app is switched off. Anyone else, including people in other organizations, sees that the app does not exist or that they cannot open it.
The Standard view
Every agent also has a Standard view that Lua provides: what the agent is waiting on, the sources it reads, and what it has done today. It is a web app namedstandard, so it appears in the agent’s list of apps and can be shared like any other. Nobody can delete it, rename it or push a version of it, and it does not count towards the agent’s apps. To hide it, switch it off.
Switch an app off
An admin can switch an app off, and on again, from the agent’s Apps page in the admin console. The change takes up to about 30 seconds to reach everyone. While it is off, the app does not open and its routes answer with the codeAPP_DISABLED.
Switching off keeps the app. To remove it for good, use lua apps delete; it asks for a code sent to your email, and no rollback brings the app back.
Limits
lua push webapp refuses a build that breaks one of these before it uploads anything:
Keep large data out of
index.html, and rename source files whose built names would use other characters.
An agent can have up to 30 web apps, not counting its Standard view. Pushing a new app beyond that is refused with WEB_APP_LIMIT_REACHED; delete one with lua apps delete first.
Switch to the client package
lua-cli 3.42 to 3.45 copy the page client into your app asweb/src/lua/client.ts, and their main.tsx sets the theme itself. lua apps upgrade <name> switches the page to the package and removes those theme lines in one step. To switch by hand instead:
from './lua/client' to from '@lua-ai-global/app-client' in src/main.tsx and src/App.tsx, and push the app again. The theme lines in main.tsx can stay; with the package at 0.1 they are no longer needed.
If it isn’t working
400 VALIDATION from a route
400 VALIDATION from a route
The request did not match the route’s
params, query, or body schema. LuaApiError.message says which field. Check the body you pass to lua.api() against the schema.No web app named … in the compiled agent
No web app named … in the compiled agent
The app is not listed under
webApps on your LuaAgent, or lua compile failed. Add the import and the webApps entry that lua apps new prints.The agent build loads files from web/
The agent build loads files from web/
tsconfig.json must exclude src/apps/*/web. lua apps new adds it when your tsconfig.json is plain JSON; add it by hand when the file has comments.The app opens, but nothing changed after a push
The app opens, but nothing changed after a push
A push is staged. Deploy the app with
lua deploy webapp --name <name> --set-version latest --force, or create an agent version and promote it (Release a version and roll back).A route answers 500, or does something you don't expect
A route answers 500, or does something you don't expect
Read the route’s logs:
lua logs --type webapp --name <name> shows each route run with its console output and errors (lua-cli 3.50.0 or later). The X-Lua-Execution-Id response header names the run. See lua logs.403 VIEW_ONLY from a route
403 VIEW_ONLY from a route
The person can only view the app, so only
GET routes reach your handlers (Who can open the app). They need read access to the agent to do more. Keep the page usable without the other routes, for example by hiding buttons that change things when such a call is refused.WEB_APP_NAME_RESERVED or WEB_APP_LIMIT_REACHED on push
WEB_APP_NAME_RESERVED or WEB_APP_LIMIT_REACHED on push
standard is the agent’s Standard view; give the app another name. An agent can have up to 30 web apps; delete one you no longer need with lua apps delete.403 DECISION_ORIGIN_DENIED from the page
403 DECISION_ORIGIN_DENIED from the page
The page called a workflow decision route directly. Call one of your routes instead, and decide there with
Workflows.viewer.Next steps
About web apps
Where apps open and how access works.
lua apps reference
lua apps new and lua apps dev.Data reference
Every
Data method your routes can call.Release an agent
Agent versions, promote, and rollback.

