lua apps creates, runs, previews and deletes web apps: pages and typed routes that belong to the agent. new writes a new app into the project; dev runs one on your machine; upgrade brings an app made by an older new up to the current template; none of them pushes anything. preview opens a version you pushed before it is live, without touching live data or sending anything. delete removes an app from the agent for good, after you confirm with a code sent to your email. Use lua test webapp to call one route and lua push webapp to create a version.
Requires lua-cli 3.42.0 or later; lua apps delete requires lua-cli 3.48.0 or later; lua apps preview requires lua-cli 3.51.0 or later; the agent pane in lua apps dev and --chat-env require lua-cli 3.53.0 or later; lua apps upgrade requires lua-cli 3.54.0 or later, and lua-cli 3.55.0 for @lua-ai-global/ui 0.3 and to remove the bundled agent pane.
Synopsis
Description
lua apps new
lua apps new <name> runs in the root of an agent project, where lua.skill.yaml is. It writes src/apps/<name>/:
It then edits two project files:
src/index.ts: imports the app and adds it towebAppson yournew LuaAgent({...}), creating the property when it is missing. When it cannot find the agent, orwebAppsis not an array, it leaves the file as it is and prints the two lines to add.tsconfig.json: addssrc/apps/*/webtoexclude, so the agent’s TypeScript build never loads the page project. When the file is not plain JSON (it has comments or trailing commas), it prints the line to add instead.
src/apps/<name> exists it stops. From lua-cli 3.67.0 it then runs npm install in web/ itself, so lua apps dev and lua push can build the pages; if that install fails, the app is kept, the command exits 1 and names cd <web> && npm install. --skip-install skips it and prints that command as a required step. On earlier releases, run npm install in web/ afterwards.
lua-cli 3.42 to 3.45 also write the page client into
web/src/lua/client.ts. To use the @lua-ai-global/app-client package instead, run npm install @lua-ai-global/app-client in web/, change from './lua/client' to from '@lua-ai-global/app-client' in web/src/main.tsx and web/src/App.tsx, and delete web/src/lua/client.ts.lua apps dev
lua apps dev <name> compiles the project and runs the app locally:
- The pages are served by the app’s own Vite (the one installed in
web/), with hot reload. The command prints the URL. - Every route call from the page runs in the sandbox on your machine, as you.
Dataandenv()are the live ones, as forlua test, so writes are real. The project’s.envis loaded once for the whole session. - Route files are watched. A change recompiles the routes, and the next call runs the new code. When the recompile fails, the previous routes keep serving and the error is printed.
- Chat with the app’s agent works too (lua-cli 3.53.0 or later):
lua.chatfrom the page and, for pages that still bundle<AgentPaneLayout>, that pane. The platform’s agent pane is not served locally; Lua adds it once the app is deployed, andlua.panecalls do nothing until then. For pages that still bundle a pane, the command points tolua apps upgrade <name>.--chat-envpicks the agent chat talks to:sandbox(the default) is your agent with the project’s local skills, processors and persona, pushed to the sandbox on the first message, aslua chat -e sandbox;productionis the agent that is live, aslua chat -e production. When that push fails, the message fails with the reason and the next message tries again. Local skills are pushed once per run, so restart the command after changing a skill. - Local chat runs on a conversation of your own, kept apart from your conversation in the live app. It follows the live pane’s rules: one reply at a time, the same limits, and nothing with
agentPane: false.
lua apps upgrade
lua apps upgrade <name> runs in the root of an agent project and edits an app made by an older lua apps new so it matches the current template:
web/package.json: raises@lua-ai-global/uiand@lua-ai-global/app-clientto at least the template’s versions. A newer version of yours is kept.web/src/main.tsx: removes the old template’s lines that set thedarkclass, because@lua-ai-global/app-client0.1 applies the shell’s light or dark mode, density and accent itself. Only lines exactly as the template wrote them are removed.web/src/lua/: an unchanged copy of the page client is deleted and its imports point at@lua-ai-global/app-client.web/src/**: the agent pane that lua-cli 3.53.0 and 3.54.0 bundle comes out, and the platform’s pane takes its place.<AgentPaneLayout>is replaced with what it wraps; acontextprop that is its only prop and reads only top-level values becomeslua.pane.setContext(...).useAgentPane()becomeslua.panefrom@lua-ai-global/app-client, which is then raised to at least 0.0.5. Once nothing imports@lua-ai-global/app-chat, it is removed fromweb/package.jsonand its styles fromweb/src/index.css. A file with<AgentPane>, other layout props, acontextthat reads component state, a read ofisOpen, orluabound to something else is left as it is, with the steps printed, and app-chat stays while it imports it (Move an older app off the bundled pane).- With
agentPane: falseindefineWebApp, the pages are upgraded and the pane stays off.
npm install in web/. A file it does not recognise, or one you changed, is left alone, and the command prints what to do by hand. Run it again and it says the app is up to date.
@lua-ai-global/ui 0.3 keeps every export and variant name of 0.2, so the pages need no code changes; buttons, inputs, tabs and cards get smaller and flatter. Look the pages over with lua apps dev <name> before you push.
From lua-cli 3.56.0, lua push webapp and lua apps dev warn when an app’s pages are built with @lua-ai-global/ui older than 0.3 and point to lua apps upgrade <name>. The warning does not stop the push: Lua restyles older apps in the meantime.
lua apps preview
lua apps preview <name> opens a version of the app you pushed with lua push webapp, before it is live, and prints a Lua Workspace link to it. It picks the latest push; --version <version> picks another. A version that is live, or an older one, can be previewed too.
A preview is safe to click through:
- It runs on its own address, never the live app’s, so it cannot read or change what the live app keeps in the browser.
- Its routes see the agent’s
Data, but what they write, update or delete goes to a copy. The live data is never changed, and the copy is deleted when the preview ends. - Emails and messages a route sends are recorded instead of sent;
--effects <id>lists them. - A
fetch, or any other outside network call, fails withTEST_EGRESS_BLOCKED. It is not sent and not recorded, so a route that calls an outside API gets an error in a preview. - Of the other runtime objects,
Dataworks as above andenv()reads the agent’s environment variables as usual.Products,Baskets,Orders,Templates,CDNandJobsanswertest_session_tier_unsupported, andWorkflows.vieweranswersviewer_unavailable: a preview never acts as the person viewing it.
--ttl: hours (36, 36h) or days (2d), at most 168 hours (7 days). It ends earlier with --close <id>. Once it ends, the link says so and its routes answer with the code PREVIEW_ENDED; open a new one to keep going.
A preview runs on the agent version that is live. An agent with no version yet is refused with WEB_APP_PREVIEW_NEEDS_AGENT_VERSION: run lua version create once.
The other forms work on previews that already exist:
--json prints the server’s answer as JSON, for scripts.
lua apps delete
lua apps delete <name> removes a web app from the agent for good: the app and every version of it. It cannot be undone:
- Nobody can open the app again, and the agent version that is live stops listing it.
- Rolling the agent back to an older version does not bring the app back.
- Pushing an app with the same name later creates a new app.
- The agent’s
Datais kept: routes write to the agent, not to the app.
--ci is off. Anywhere else, such as a CI job or a pipe, it emails the code and exits; run it again with --code <code> to delete.
Only a person can delete an app: sign in with lua auth configure, or use an API key you own. A key that belongs to an organization or a service is refused. The code goes to the verified email address of your Lua account. You need the same access to the agent as for pushing.
After the delete, inside the agent’s project, the command also removes the app from the project, so the next lua push does not create it again:
- its row under
webAppsinlua.skill.yaml; - its import and its entry in
webAppson yournew LuaAgent({...})insrc/index.ts. When it cannot edit the agent, it prints what to remove.
src/apps/<name>/ stays; delete it yourself when you no longer want it. With --agent outside the project, no local file is touched. When the platform no longer has the app but the project still lists it, the command removes it from the project and exits 3.
Arguments
Options
Examples
Scaffold an app and install its page project:Output
Output
Output
Output

