# Build an app

At the end of this guide you have a published app that the people you chose can open from **Apps**, with its own roles deciding what each of them sees and does. You build it by describing it to a coding agent in the **Builder**; everything lands in a **draft** that only the app's Builders and Admins see until you publish. Creating an app needs the **Manage apps** permission, and whoever creates it becomes its Admin.

## Before you begin

- The **Manage apps** permission.
- A coding agent the Builder can use. **OpenCode** uses your organization's models. **Cursor** and **Codex** use your own subscription, connected under **Personal Settings** > **AI** > **Coding agents**.
- An idea of who will use the app and who decides what, for example requesters, approvers and finance.

## Create the app

1. Open **Apps** and choose **New app**.
2. Enter a **Name**. The **Address** is filled in from it; change it now if you like, because it cannot be changed later.
3. Optionally add a **Description** and a **Color**.
4. Under **Start from**, pick **Blank** or a template, such as **Expense Claims**, **Purchase Requests**, **Asset Inventory** or **Room & Desk Booking**. A template is a complete, working app with its data, roles, rules, screens and dashboard.
5. For a template, optionally tick **Add sample data** so the draft starts with example records. The published app always starts empty.
6. Choose **Create**. The Builder opens on its **Build** tab.

> **Note:** To start from an app exported from this or another Volobox, choose **Import from a file** under **Start from** and pick its zip. The app is created with the file's model, rules and screens as its draft; records, people and the logo do not come with it.

![The New app dialog over the Apps page, filled in for an Interview Scheduler app, with its Start from list open: Blank, the app templates such as Expense Claims, Purchase Requests and Asset Inventory, and Import from a file.](https://volobox.io/docs/images/apps-templates.light.webp)

*The New app dialog: a name, the address filled in from it, a description, and the Start from list with Blank, templates and Import from a file.*

## Build with the agent

1. On the **Build** tab, choose **Start a session**, pick the **Coding provider**, and choose **Start a session**. The **Model** (and **Effort**, where the model has it) can be changed under the message box at any time.
2. Describe the app, or what to change, and send. For example: "A purchase request app. Anyone can request; an approver decides; finance marks it ordered."
3. Follow the turn. The agent writes the app's data, roles, rules and screens, then Volobox checks and saves the draft and builds the screens. When a decision only you can make blocks the request, a card **The agent asks** appears: pick an option or type an answer, and choose **Submit**.
4. Read the reply. It says what the agent did and anything it needs from you; the files it changed are under **Details** > **Changed files**. **Undo this change** under the reply takes the change back.
5. Keep going, one change per message. Tell the agent about roles in plain words ("only HR sees salaries", "everyone adds their own requests") and it writes the access to match.
6. When you are done, choose **End session** in the **⋯** (**Session options**) menu. The draft stays.

> **Tip: Read what was built without reading code**
>
> The **Structure** tab draws the draft's tables and how they connect, its rules, events, schedules, access and screens. The file format is in [App files](/docs/app-files).

## Try the draft

1. In the preview beside the chat, pick a screen under **Screen in the preview**, and use the device menu to see it as a **Phone**, **Large phone** or **Tablet**, or drag the preview's edge to any width.
2. Under **View as**, pick **Member with no app role**, **Visitor (not signed in)** or one of the draft's **App roles**. The screens, menu, records and actions become that person's; **View as myself** goes back.
3. To use the draft at full size, choose **Open draft**. It is marked **Draft** and uses the draft's own data. Inbox cards and notifications its rules send reach only the app's Admins and Builders.

## Give people access

1. In the Builder, open **Settings** > **Members** and choose **Add**.
2. Choose a **Role**: **Member** uses the published app, **Builder** also builds and publishes, **Admin** also manages people and settings. Make someone a Builder only when you would trust them to write code for your workspace.
3. Choose **Person** or **Group**, search, and choose **Add** on a row.
4. Open **Settings** > **Roles**. Under **App roles**, find a role such as *approver*, choose **Assign** and pick a person or a group. Assigning a role to someone who is not a member makes them a **Member** too.
5. To open the app to the whole workspace instead, tick **Public** under **Settings** > **General** and confirm **Make public** (Admins only). Everyone becomes a **Member**, never a Builder or an Admin.

> **Note:** An app made from a description starts with one app role, **Editor**, that may change everything, and lets everyone in the app read every record and screen. Nobody holds **Editor** until you assign it. A template keeps its own roles.

## Review and publish

1. Open the **Review** tab. It compares the draft with the published app and lists every change in plain words, grouped under **Who can do what**, **Data**, **Rules** and **Screens**.
2. Read every change marked **Needs attention**: anything newly open to anyone without signing in (with the reason the app gives), a field whose type changes, a field removed and added again, a choice that gets another stored number.
3. Check **What the published app needs**. Secrets, Volobox events and Volobox access live outside the app's files, so publishing does not bring them along. **Set up** opens each item's dialog; something marked required stops the publish until it is set up.
4. Choose **Publish**. You see **Published version n.**, and people get the new version the next time they open a screen.

> **Warning: Publishing never deletes data**
>
> A removed table or field keeps its data and gets it back if it returns. A field whose type changes is converted when you publish; when a value would not survive the conversion unchanged, publishing stops with a message and nothing changes.

![The Field Visits app in the App Builder on its Review tab: version 6 is live and a Publish button, what the published app needs (Projects and tasks, Task closed, both ready), the data and screen changes in the draft, and the draft version made by a Builder request.](https://volobox.io/docs/images/app-publish.light.webp)

*The Review tab in the Builder: the live version and Publish, what the published app needs, and the data and screen changes in the draft.*

## Export or import a version

Under **Settings** > **Export and import** (Builders and Admins):

1. **Export draft** or **Export published** downloads that version as a zip: its model, rules, screens and packages. No records, people, logs or logo.
2. **Import a new version** takes such a zip and asks **Replace the draft?**, warning when the zip comes from another app. Confirm **Replace draft**. The app keeps its name, address, records and people, and the next Builder turn starts from the imported files.
3. Publish the imported draft like any other.

## Check that it works

- The **Review** tab reads **Version n is live.**, and **Open the app** opens the published app in a tab of its own.
- A member opens the app from **Apps** and sees only the screens and records their roles allow.
- An Inbox card the app sends for work that waits appears in the right person's Inbox, with the app's own buttons.

## Troubleshooting

| Symptom | Fix |
| --- | --- |
| **The draft's screens could not be built, so it cannot be published.** | Choose **Go to Build**, open the last turn's **Screen build log**, and ask the agent to fix it |
| **The draft changed while you were reviewing it.** | Someone, or the agent, saved the draft meanwhile. Read the updated list and publish again |
| **The draft matches the published app. There is nothing to publish.** | Nothing changed since the last publish |
| People still see the old version | They opened the screen before you published. Reopening the screen loads the new version |
| A rename lost a field's data | The agent gave the field a new id. Restore an earlier version on **Review**: the data was parked, not deleted |
| A rule failed for someone | Open **Structure** > **Runs**, pick **Published**, turn on **Only problems**, and ask the agent to fix the rule |

## Next steps

- [App files](/docs/app-files)
- [Call other systems from an app](/docs/call-external-systems)
- [Apps](/docs/apps)
- [Write a code workflow](/docs/write-code-workflow)
