Apps
What a BotDojo App is, why you'd build one, and how to get one working and shared.
A BotDojo App is a mini-application built to work with an AI agent. People use it beside their agent in a BotDojo Workspace, or in other AI agents such as Claude and ChatGPT. It has its own screens, its own data, and rules in code about who may do what, and the agent works under the same rules as the person it is helping. For example, in a Purchase Requests App anyone can file a request or ask their agent to file one, but only approvers can approve it.
Build one when a chat with an agent is no longer enough: the work needs a screen, records the whole team shares, and rules the agent cannot get around. An App also comes with change management built in: tests, separate environments, releases you review before they go live, and database migrations.
Get an App working
You write an App in TypeScript and React with the botdojo-app CLI. You need
Node.js 22.13 or later and project administrator access to a BotDojo project.
- Install the CLI and sign in. Select Create a new App and the Purchase Requests starter.
- In the App folder, run
npm test, thennpm run devto try the App on your computer. - Run
botdojo-app deploy --vars-file .env.local --seed. Then open Apps in the project, select the App, and choose Preview App. - Select Share on the App page. Then an account administrator gives a group the App in Account → Groups.
How an App reaches people
- Environment. A running copy of the App with its own data. Start with
development, and addproductionwhen people rely on the App. - Deploy. Builds your code into a release, runs the database migrations, and makes the release the one the environment runs. You review table and role changes first, and the data stays.
- Share. Creates the App connection, an MCP server. No member can open the App yet.
- Group. Members of a group that has the App see it under Apps in their Workspace, with the default role unless the group picks others. Administrators see every shared App in the account.
See Environments and Deploys and Roles, Sharing, and Access.
When to use an App
- Workspace HTML file. For a one-time report, preview a single HTML file in your Workspace.
- Shared artifact. When other people need the report, publish a reviewed copy of the file as an artifact and share its link.
- BotDojo App. When you need discoverability, access over MCP, data persistence, role-based security, and change management.
For reusable instructions without a UI, use a skill. For a repeatable process that can call an agent or wait for input, use a workflow.
How Apps work
| Piece | Use it for |
|---|---|
| UI | Showing a queue, editing a draft, or asking a person to confirm an action. |
| Function | A bounded operation, such as updating a Store row, enforcing an approval limit, or calling an external tool through a connection. The UI and agents can call the same permitted function. |
| Workflow Run | Longer work that needs multiple steps. A run can retain progress, call tools and agents, pause for a person to answer, then continue. |
| Skill | Instructions an agent can reuse. They ship with the App's release. |
See Write an App in code, Functions and UI, and Workflows and Skills.
Work alongside an agent
Design the App so a person can work in its screens while an agent helps in the chat beside it. In an invoice review App:
- An Ask about this invoice button starts a conversation about it.
- The agent can see which invoice is open.
- The agent can open an invoice it found.
See send a message and share page state and offer tools to the agent.