Skip to main content
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 to webApps on your new LuaAgent({...}), creating the property when it is missing. When it cannot find the agent, or webApps is not an array, it leaves the file as it is and prints the two lines to add.
  • tsconfig.json: adds src/apps/*/web to exclude, 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.
The name must be lower-case letters, digits, and dashes, starting with a letter. The command never overwrites anything: when 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. Data and env() are the live ones, as for lua test, so writes are real. The project’s .env is 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.chat from 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, and lua.pane calls do nothing until then. For pages that still bundle a pane, the command points to lua apps upgrade <name>. --chat-env picks 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, as lua chat -e sandbox; production is the agent that is live, as lua 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.
There is no handoff from a shell locally: the page runs as you without signing in. Ctrl+C stops the server.

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/ui and @lua-ai-global/app-client to 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 the dark class, because @lua-ai-global/app-client 0.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; a context prop that is its only prop and reads only top-level values becomes lua.pane.setContext(...). useAgentPane() becomes lua.pane from @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 from web/package.json and its styles from web/src/index.css. A file with <AgentPane>, other layout props, a context that reads component state, a read of isOpen, or lua bound 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: false in defineWebApp, the pages are upgraded and the pane stays off.
It shows the changes and asks before writing, then runs 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 with TEST_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, Data works as above and env() reads the agent’s environment variables as usual. Products, Baskets, Orders, Templates, CDN and Jobs answer test_session_tier_unsupported, and Workflows.viewer answers viewer_unavailable: a preview never acts as the person viewing it.
The link opens in Lua Workspace in the browser, under a Preview banner with the version and when the preview ends. Anyone who can edit the agent can open it, so you can send it to another builder; the copy of the data is shared by everyone who opens it. An app that is switched off, or has no live version yet, can still be previewed. Opening a preview of a version that already has an open one gives you that one instead of a new one. A preview lasts 24 hours unless you pass --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 Data is kept: routes write to the agent, not to the app.
To switch an app off for a while instead, disable it. The command first shows what it will delete: the app, its agent, the version that is live, and how many versions there are. It then emails a 6-digit code to you and asks for it. A wrong code asks again and says how many attempts are left; after 5 wrong attempts, or once the code has expired (after 15 minutes), run the command again for a new code. Asking again within a minute sends no new email, and the code you already have keeps working. There is no flag that skips the code. The command asks for the code only when it runs in a terminal (both input and output) and --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 webApps in lua.skill.yaml;
  • its import and its entry in webApps on your new LuaAgent({...}) in src/index.ts. When it cannot edit the agent, it prints what to remove.
The app’s source in 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
Run it on a fixed port:
Chat with the live agent in the pane instead of the sandbox:
Bring an older app up to the current template, looking at the changes first:
Call one route, then push a version:
Preview the latest push for two days, then see what it recorded and end it:
Output
Output
Delete an app, confirming with the emailed code:
Output
Delete from CI in two steps: the first run emails the code, the second deletes with it:

Exit codes

See also