Skip to main content
In this tutorial you build ops-dashboard, a web app on your agent. It has a page that lists tickets and opens new ones, and two routes that read and write a Data collection as the person using the page. At the end, the app is live and open in Lua Workspace in your browser. Allow 20 minutes. You need a project created with lua init and a user session from lua auth configure (Install the CLI and sign in), and Node.js 20 or later. Verified against lua-cli 3.44.0; the page template, main.tsx, and lua apps upgrade against lua-cli 3.55.0. The complete project is in the examples repository: lua-apps-ops-dashboard. It adds a third route that closes a ticket.

What you’ll build

  • A web app listed on your agent, with a page project in src/apps/ops-dashboard/web.
  • A GET /tickets route and a POST /tickets route with a Zod body schema.
  • A React page that calls both routes with lua.api() and follows the shell’s theme.
  • A local run with hot reload, a route test from the terminal, and a pushed version.
  • An agent version that makes the app live, opened by its URL.
1

Scaffold the app

Run this in the root of your agent project, where lua.skill.yaml is:
Output
The command writes two things. app.ts holds the routes, which run on Lua. web/ is a Vite + React project with the @lua-ai-global/ui components and Tailwind; it runs in the browser. From lua-cli 3.55.0 it uses @lua-ai-global/ui 0.3, the same design as Lua Workspace. The command also lists the app under webApps on your LuaAgent and keeps the page project out of the agent’s TypeScript build. It never overwrites an existing app. Once the app is live it also has the agent pane, a chat with your agent that Lua adds to the page and the person opens with Chat in the app’s top bar; the page needs no code for it. lua-cli 3.53.0 and 3.54.0 bundle a pane into main.tsx instead, which lua apps upgrade takes out; see Talk to the agent from your app.
2

Install the page project

The page project has its own dependencies:
@lua-ai-global/app-client is the page side of the app. It opens the session that the shell hands over, talks to the shell, calls your routes, and, from version 0.1, applies the shell’s look to the page. The template of lua-cli 3.55.0 and later already depends on 0.1.
lua-cli 3.42 to 3.45 copy the client into web/src/lua/client.ts instead of adding the package, and their main.tsx sets the theme itself. Run lua apps upgrade ops-dashboard (lua-cli 3.55.0 or later): it switches the page to the package, raises it to 0.1, and removes the theme lines. To switch by hand instead, install the package as above, 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; the theme lines can stay, or go once the package is at 0.1.
3

Write the routes

Replace src/apps/ops-dashboard/app.ts:
src/apps/ops-dashboard/app.ts
A route key is a method and a path. The handler gets the request already checked against the route’s schemas: a body without a title is answered with 400 before your code runs. auth is the person using the page, never an API key. A handler that returns a value answers 200 with it as JSON; json(value, status) sets another status.Run lua compile --ci. The summary counts the app:
Output
4

Call the routes from the page

Replace src/apps/ops-dashboard/web/src/App.tsx:
src/apps/ops-dashboard/web/src/App.tsx
src/apps/ops-dashboard/web/src/main.tsx starts the client. With @lua-ai-global/app-client 0.1 or later, which you installed in the previous step, lua.start() also gives the page the shell’s light or dark mode, density, and the accent the person picked in Lua Workspace, so the page needs no theme code. An older client (0.0.x) does not apply them; keep the theme lines your template wrote, or run lua apps upgrade ops-dashboard. Colour it with the ui tokens (bg-background, text-foreground, text-muted-foreground) as above, never fixed colours; see Look and theme. Your main.tsx should look like this:
src/apps/ops-dashboard/web/src/main.tsx
lua.api(method, path, body?) calls a route of this app as the signed-in person and resolves the JSON it answers. In web/, npx tsc --noEmit reports no errors.
5

Run it locally

The command compiles the agent, starts the page on the app’s own Vite server with hot reload, and prints its URL. Open it, add a ticket, and it appears in the list. Locally the routes run in the sandbox on your machine as you, against the agent’s live Data, so the ticket is a real entry in the tickets collection. Edit App.tsx and the page reloads; edit app.ts and the routes recompile. Press Ctrl+C to stop.
6

Test a route from the terminal

lua test webapp calls one route the way the platform would, with you as auth:
Each call prints the status, the response headers, and the body. The first answers 201 with the new ticket; the second lists it. A body that fails the schema answers 400. Add --json to get the result as JSON for a script.
7

Push a version

The push builds the page with the app’s own Vite, uploads it with the route bundle, and creates a web-app version. --force picks the next version number without asking. The version is staged, not live: the command ends with Staged but NOT live yet and the two commands of the next step.
8

Go live

Deploy the version you just pushed. Only this web app goes live; anything else you staged on the agent stays staged:
To roll back, deploy the previous version with --set-version <version>. lua deploy webapp needs lua-cli 3.49.0 or later. On lua-cli 3.42 to 3.48, a web app goes live with the agent version that pins it: lua version create -m "Add the ops dashboard", then lua version promote <n> with the number it prints.
9

Open the app

Open it by URL in your browser. <agentId> is agent.agentId in lua.skill.yaml:
The app opens full page in Lua Workspace, signed in as you, and lists the tickets you added locally. The admin console lists the agent’s apps at https://admin.heylua.ai/admin/agents/<agentId>/apps. Neither has a menu entry for apps yet.
The app opens at its Workspace URL, a ticket you add there shows your name, and lua test webapp --name ops-dashboard --route 'GET /tickets' lists it.

What you learned

  • A web app is part of an agent: defineWebApp in src/apps/<name>/app.ts, listed under webApps. About web apps explains where it opens and who can open it.
  • Routes are typed handlers that run on Lua as the person using the page, with Data and env(). The page calls them with lua.api(). Write routes and pages covers params, query, errors, and limits.
  • lua apps dev and lua test webapp run the routes locally against live data.
  • lua push webapp stages a version; lua deploy webapp makes it live on its own, and deploying an earlier version rolls just that app back (lua-cli 3.49.0 or later). On lua-cli 3.42 to 3.48, an agent version makes it live, and promoting an earlier one rolls it back.

Next steps

Write routes and pages

The full defineWebApp shape, the page client, and limits.

lua apps reference

lua apps new and lua apps dev.

Store and search data

More on the Data collections your routes use.

Talk to the agent from your app

The agent pane: open it or ask it with lua.pane, page context, and lua.chat.

lua-apps-ops-dashboard example

The full project, ready to clone and run.