Skip to main content
A web app is a primitive of an agent, like a skill or a webhook. It gives the people who work with the agent a page of their own: a ticket board, a review queue, a dashboard. You build it with lua apps new and release it with the agent.

What a web app is

A web app has two parts:
  • Pages. A Vite + React project in src/apps/<name>/web. It runs in the browser. The template uses the @lua-ai-global/ui components and Tailwind, so the app looks like the rest of Lua: from lua-cli 3.55.0 it is on @lua-ai-global/ui 0.3, the design Lua Workspace uses. The page follows the light or dark mode, density and accent of the person who opens it, with no theme code of yours (Look and theme).
  • Routes. Typed handlers in src/apps/<name>/app.ts, defined with defineWebApp. They run on Lua, in the same sandbox as your tools, with Data, env(), and fetch. The page calls them with lua.api() from @lua-ai-global/app-client.
Every app also has an agent pane by default: a chat with the app’s own agent, where each person has their own conversation. Lua provides it, so the pages add nothing for it. In Lua Workspace the person opens it with Chat, the rightmost item in the app’s top bar, and it starts closed every time. The page can open it, ask it something, and tell it what is on screen with lua.pane from @lua-ai-global/app-client. See Talk to the agent from your app. The app is listed under webApps on your LuaAgent. lua push webapp creates a version of it, and lua deploy webapp makes that version live on its own, without taking anything else you staged on the agent live (lua-cli 3.49.0 or later). An agent version that pins the version makes it live too, together with the rest of the agent; that is the only way on lua-cli 3.42 to 3.48. Rolling the agent back rolls the app back with it, and deploying an earlier version of the app rolls back just the app.

Where it opens

A live app opens full page, by URL:
  • In Lua Workspace in the browser, at https://workspace.heylua.ai/apps/<agentId>/<appName>. All your apps are listed at https://workspace.heylua.ai/apps.
  • In the admin console, at https://admin.heylua.ai/admin/agents/<agentId>/apps.
The Lua desktop app opens them too. In Lua Workspace in the browser, and in the desktop app from version 0.75.0, an app’s top bar ends with Pin and Chat. The admin console shows no agent pane for apps for now.

Who can open it

The agent’s read permission decides. Anyone who can read the agent can open its apps: every member of the organization for an agent that is not private, and only the people who can see the agent for a private one. A member of the organization who cannot read the agent can still view one app when someone shared it with them, or when the app shows to the whole organization: they see its pages and get its GET routes, and nothing else (Who can open the app). Anyone else, including people in other organizations, is told that the app does not exist or that they cannot open it. An admin can switch an app off, and on again, from the admin console.

How it stays safe

  • Its own origin. Each app runs on an origin of its own, separate from Lua Workspace, the admin console, and every other app. A page cannot read another app’s data or the shell’s.
  • A handed-over session. When you open an app, the shell hands it a session for you. The page never sees your password or the shell’s own token, and it keeps the session in memory only.
  • Routes run as you. Every route call carries the signed-in person as auth. A route never runs anonymously or with an API key, so a write can record who made it, and the page needs no secrets: the keys your routes use stay on Lua.

Next steps

Build and open your first web app

Scaffold, run, push, and open an app in 20 minutes.

Write routes and pages

Schemas, the page client, versions, access, and limits.

Talk to the agent from your app

The agent pane, lua.pane, page context, and lua.chat.