Skip to main content
After this guide, your web app has typed routes that read and write your agent’s data as the signed-in person, a page that calls them and follows the shell’s theme, and a release you can roll back. Start from Build and open your first web app if you have no app yet; About web apps explains the model. Verified against lua-cli 3.44.0; the page template, Look and theme, and 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>, with npm install run in its web/ folder.
  • @lua-ai-global/app-client installed in web/, 0.1 or later for a page with no theme code (see Switch to the client package if your app has web/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.
  • undefined answers 204 with no body.
  • json(value, status, headers?) sets the status. json(undefined, 204) answers with no body.
  • A Web Response is sent as it is.
A handler that throws answers with an error whose 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:
  • auth is the person using the page: userId, orgId, agentId, roles, scopes, accessLevel, and name and email when known. It is never an API key and never anonymous, so you can record who made a change. accessLevel is 'full', or 'view_only' for someone who can open only this app (Who can open the app); a view-only person has empty roles and scopes.
  • Data and the other runtime objects work as they do in a tool.
  • env('KEY') reads the agent’s environment variables. Set them with lua env.
  • fetch calls your own APIs. The page never sees the keys you use here.
  • Workflows.viewer decides a workflow approval or answers a waiting step as the signed-in person, not as the agent (Decide approvals from a route).
A GET route must only read. People who can view the app only reach every GET route, which runs with the agent’s own Data, environment variables and connections, and no other route. Create, change or delete things only in a POST, PUT, PATCH or DELETE route: for a view-only person those answer 403 VIEW_ONLY before your handler runs.

Call routes from the page

The page project in web/ 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 client gives the page: 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-client 0.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 calls lua.start() and again whenever the shell changes them.
  • Don’t manage the theme in the page. Keep void lua.start() in main.tsx and leave out any code that toggles the dark class.
  • Colour the page with the semantic tokens @lua-ai-global/ui defines, such as bg-background, bg-card, text-foreground, text-muted-foreground, bg-primary, text-primary-foreground, and border-border. A palette class like bg-blue-500 or a hex colour stays the same whatever accent or mode the person uses.
web/src/App.tsx
Version 0.3 adds components for whole pages: @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:
Its tools are 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 older lua apps new is on @lua-ai-global/ui 0.2 and sets the theme itself. Bring it up to the current template:
The upgrade raises @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, calls Workflows.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
  • agentId names 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, PATCH or DELETE call. Anywhere else, including a GET route, a tool or a job, it throws with code === 'viewer_unavailable'.
  • An approval that needs a fresh sign-in or a particular surface answers STEP_UP_REQUIRED or APPROVAL_SURFACE_DENIED; send the person to the inbox for those. Other refusals keep their own codes, such as NOT_AN_APPROVER, FOUR_EYES_REQUIRED, APPROVAL_NOT_FOUND and PAYLOAD_MISMATCH.
  • Under lua apps dev and lua test webapp the route runs as you, so the call is made with your own CLI sign-in.
Make decisions through a route. The page itself cannot call the platform’s decision routes: a request from an app’s page is refused with 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:
Locally 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:
It prints a Lua Workspace link to that version, on its own address. Its routes read the agent’s 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 named standard, 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 code APP_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 as web/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:
Then change 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

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.
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.
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.
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).
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.
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.
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.
Workflows.viewer runs only in a route handler for a POST, PUT, PATCH or DELETE call. Move the call into such a route.
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.