Documentation · App Builder
The manifest
One document per app
Every app is one manifest: a document with kind: VerticalApp. It describes the pages, the forms, the data, the
roles, the agents, what starts them and how users pay. App Studio, its co-pilot and the runtime all read and write
the same document. There is no other source code.
A manifest has four top-level keys, all required:
| Key | Value |
|---|---|
apiVersion | Always webrobot.eu/v1alpha1. |
kind | Always VerticalApp. |
metadata | The app's identity: slug, name, languages. |
spec | Everything the app does. |
No other top-level key is accepted.
metadata
| Field | Required | What it is |
|---|---|---|
slug | yes | The app's unique name. It gives the default address <slug>.webrobot.eu. |
displayName | yes | The app's name, shown in the header, the browser tab and the sign-in email. A plain string. |
tagline | no | One line about the app. It becomes the page description for search engines. Translatable. |
description | no | A longer description. Translatable. |
langs | no | The languages of the app, as two-letter codes, e.g. [en, it]. At least one, no duplicates. |
defaultLang | no | The language used when the visitor's language is not in langs. It must be one of langs. |
timezone | no | An IANA time zone, e.g. Europe/Rome. Today the runtime uses it only for service hours when those do not set their own zone. |
organizationId | no | The organization that owns the app. The platform sets it when you publish: do not write it by hand. |
Slug rules
The slug must match ^[a-z][a-z0-9-]{1,38}[a-z0-9]$:
- 3 to 40 characters;
- lowercase letters, digits and hyphens;
- it starts with a letter and does not end with a hyphen.
The slug is fixed once the app exists. When you save a draft, the platform checks that metadata.slug matches the
app you are saving.
Versions
The manifest has no version field. The platform numbers each publish (published v1, v2…) and App Studio shows the number. See Publishing.
The sections of spec
spec needs two keys: pattern and agents. Everything else is optional. No key outside this list is accepted.
| Key | What it is for | Read more |
|---|---|---|
pattern | The shape of the app: report, chat, dashboard or pipeline. | below |
host | A different default host name for the app. | below |
domains | Your own domains, served by the app. | below, Publishing |
branding | Colours, fonts, logo, theme, buttons. | below |
header | The top bar for visitors: links, a call to action, an announcement. | below |
auth | Sign-in method, what visitors may open without signing in, roles. | Sign-in and roles |
limits | Rate limits and quotas per user (admins are exempt). | Agents and automation, Data |
agents | The AI agents of the app, their goals, tools and memory. | Agents and automation |
inputForm | The form a user fills in to start a run of the main agent. | Views, Data |
data | Collections of records, data jobs, credentials users connect. | Data |
views | The pages of the app. | Views |
schedules | Agents or jobs that run on a timetable. | Agents and automation |
triggers | Events that start an agent, a team or a job, send an email, write a record or charge credits. | Agents and automation |
teams | Agents that work together as one. | Agents and automation |
approvals | Human checkpoints an agent waits for. | Agents and automation, Views |
templates | Agents each user creates for themselves, with their own parameters and schedule. | Agents and automation, Views |
slots | Small Python functions the runtime runs in a sandbox. | Agents and automation |
egress | The external hosts the app's HTTP tools may call. | Agents and automation |
channels | Where conversations come from (the web chat, a phone number, a bot, a mailbox). | Messaging |
notifications | Emails to users when their run ends. | Messaging |
serviceHours | When the app's chat must answer fast. | Agents and automation |
billing | How users pay: credits, packs, plans. | Billing |
mobile | The phone app and the phone features it uses. | Export |
exports | Endpoints the app serves to other programs. | Reference |
extensions | Custom logic the manifest cannot express yet, written down as documented gaps. | Reference |
The full list of fields of each section is in the reference.
Conventions used everywhere
Keys
The key of a view, an agent, a role, a team, a data job and similar entries follows the pattern
^[a-z][a-z0-9_-]*$: it starts with a lowercase letter and holds lowercase letters, digits, _ and -.
A field name is stricter: ^[a-z][a-z0-9_]*$ (no hyphens), because field names become placeholders in agent goals
such as {city}.
Keys must be unique in their own list. Other parts of the manifest refer to them by key, and validation refuses a reference to a key that does not exist (see Validation).
Translatable text
Every field shown to users as text (titles, labels, help, page content, options) takes either:
a plain string, used in every language:
title: Bookingsor one string per language, keyed by two-letter code:
title: { en: Bookings, it: Prenotazioni }
An object needs at least one language. Only two-letter lowercase keys are accepted.
How the runtime picks the text for a page shown in language lang:
- the string for
lang, if the object has it; - otherwise the first string in the object, in the order you wrote it;
- otherwise a fallback chosen by the runtime (often the key of the item, e.g. a view's key in the menu).
The fallback in step 2 is the first language written, not defaultLang. Write the default language first in every
object to get the same result everywhere.
The page language itself is chosen this way: the language the visitor picked with the language switch, else the
first language of the browser's preferences. If that language is not in langs, the page uses defaultLang, else
the first entry of langs. See Sign-in and roles.
The runtime's own words (Sign in, Sign out, Start, Download CSV…) exist in English and Italian. In any other language they appear in English.
Markdown
Page content, page sections, the header announcement and agent reports use a small, safe Markdown: headings, lists,
tables, bold, italic, code, and links to https:// addresses or to paths of the same app (/login, /v/new). Raw
HTML in Markdown is shown as text, never run. A page can hold custom HTML only in an html section, which is cleaned
against an allow-list (see Views).
Links
Every href in the manifest (header links, hero buttons) must start with / (a path of the same app, not //), #
(an anchor on the page) or https://. Anything else is refused by validation; at render time an unsafe link becomes
#.
Branding and theme
spec.branding sets the look of the app. The runtime turns it into CSS variables on every page.
| Field | What it does |
|---|---|
palette | The colours: primary, accent, background, foreground. Each is #rrggbb. |
paletteDark | The same four colours for the dark theme. |
theme | light, dark or auto. auto follows the device's setting and needs paletteDark. dark uses paletteDark when it is set. |
tokens | Extra named colours (#rrggbb), e.g. one per status value. Each becomes a CSS variable --<name> (_ becomes -). |
tokensDark | The tokens for the dark theme. |
fonts | body, display (headings) and mono: Google Fonts family names, loaded with weights 400 to 900. A name may hold letters, digits and spaces, up to 41 characters; anything else is ignored. |
logo | An inline SVG (up to 20,000 characters, cleaned) or an https:// image URL. |
wordmark | The app's name in up to 4 parts, each with an optional color (a palette or token key). Replaces displayName in the header. |
byline | Small text after the name, e.g. "by Acme". Translatable. |
button | The palette or token key used for main buttons (default accent). |
buttonShape | pill (default), rounded or square. |
ghostButton | Secondary buttons: outline (default, in the button colour) or neutral. |
headingWeight | 400 to 900, in steps of 100 (default 700). |
headingTracking | normal or tight (slightly closer letters in headings). |
brandWeight | Weight of the name in the header: 500 to 900. |
width | Page width: normal (1080 px) or wide (1200 px). |
Only colour values of the form #rrggbb reach the page. Validation refuses theme: auto without paletteDark.
branding:
theme: auto
palette: { primary: "#14324a", accent: "#c0522b", background: "#faf7f2", foreground: "#1b1f24" }
paletteDark: { primary: "#9cc3e0", accent: "#e58a5f", background: "#111418", foreground: "#e9e6e1" }
fonts: { body: Inter, display: Fraunces }
buttonShape: rounded
width: wide
Header
spec.header is the top bar for visitors.
| Field | What it does |
|---|---|
links | Up to 8 links, each {label, href}. Shown to visitors who are not signed in, and to signed-in users who have no page in their menu. |
cta | One button {label, href}. It replaces the Sign in button for visitors who are not signed in. |
announcement | One line above the header, in Markdown (links allowed). Shown to everyone. |
Signed-in users see the app's menu instead of the links: their pages, plus extra links for admins. See Views.
header:
links:
- { label: { en: How it works, it: Come funziona }, href: "#how-it-works" }
- { label: Pricing, href: /v/pricing }
cta: { label: { en: Start free, it: Inizia gratis }, href: /login }
announcement: { en: "New: [weekly city watch](/v/watches)", it: "Novità: [osservatorio settimanale](/v/watches)" }
The header also shows the language switch when langs has more than one language.
pattern
pattern names the shape of the app:
| Value | Shape |
|---|---|
report | A user fills in a form, an agent runs, the user gets a report. |
chat | A conversation; each message starts the agent. |
dashboard | Agents or jobs run on a schedule; users read the results. |
pipeline | An agent sets up a data pipeline, the app runs it and reports on the data. |
The runtime does not change its behaviour based on pattern. What the app does comes from its views, agents,
triggers and schedules. App Studio uses pattern to describe the app.
Host and domains
The runtime picks the app by the host name of each request:
- an app whose
spec.hostor one of whosespec.domainsequals the host; - otherwise the app whose slug is the subdomain:
<slug>.webrobot.eu.
An app always answers on <slug>.webrobot.eu, even when it has a host.
host: a different host name for the app. Do not put your own domains here.domains: your own domains (e.g.app.example.com). Each needs a DNS CNAME record pointing to<slug>.webrobot.eu, and a certificate issued when you publish. Lowercase domain names only; no duplicates. See Publishing.
Sign-in links, redirects and payment return pages always use the app's own address, never a host name sent by the browser.
YAML or JSON
The manifest is the same document in either format:
- YAML is easier to read and write by hand. The examples in these pages use YAML.
- JSON is what the platform stores and what App Studio saves. The co-pilot proposes manifests in JSON.
A model writing a long JSON document sometimes closes one bracket too many or adds a character after the end. When App Studio reads a manifest proposed by the co-pilot, it repairs only those two mistakes, at most 6 times, and never guesses content. Any other syntax error stays an error.
Validation
Two checks run on a manifest. They differ in what they block.
Errors: validateManifest
Errors block publishing. App Studio runs this check as you edit and shows the count of problems; the Publish button stays disabled until there are none. Saving a draft with errors is allowed, so work in progress is never lost. The runtime validates the published manifest again before serving it: an app whose manifest is not valid is not served, and its address shows "No app is published on this address."
The check has two parts:
The JSON Schema. Types, required fields, enums, patterns, value ranges and unknown keys. The message names the path, e.g.
/spec/views/2/type: must be equal to one of the allowed values.References and rules the schema cannot see. Among them:
- every name points at something that exists: views shown in pages and dashboards, agents, data jobs, collections, plans and packs, form fields, approvals, templates, roles;
- no collection uses a reserved name (the runtime's own data, such as
users,runs,files); defaultLangis one oflangs;theme: autohaspaletteDark;- a form view writes a declared collection that has fields;
- a booking view writes a collection
ownedBy: user; - placeholders in an agent's
goalTemplateare filled by something (a form field, a context key, a built-in); - visitors who are not signed in cannot reach the owner's private data through an agent;
- billing modes are consistent (e.g.
creditsneeds a way to get credits); - teams have no cycles, delegation does not loop, and an approval is decided by a role nobody gets just by
signing up (or by the user who asked, with
decidedBy: requester).
Messages are plain sentences, e.g.
view home: a block shows unknown view 'pricing'.
Warnings: lintManifest
Warnings point at design problems. They never block publishing, and a published app keeps working when a new warning is added. App Studio shows them once the manifest has no errors, and sends them back to the co-pilot.
The main checks:
- Who fills each collection. A collection of user records (
ownedBy: userorinstance) that pages, tools, selects or triggers read, but that nothing writes (no form, booking, agent tool,writesToor trigger write). - Forms that cannot save. A form for everyone on a
sharedorappcollection: only admins can add records there. - Admins with an empty menu. The admin role is in none of the menu pages'
roles. - The phone app (when
spec.mobileis set). Phone capabilities declared but not used, or used but not declared, and other checks the export applies too. See Export.
A complete example
A small report app: visitors see a landing page, users sign in, pick a city and a goal, and an agent writes a brief. This manifest passes both checks with no errors and no warnings.
apiVersion: webrobot.eu/v1alpha1
kind: VerticalApp
metadata:
slug: city-brief
displayName: City Brief
tagline:
en: A one-page brief on a city, for your goal.
it: Un brief di una pagina su una città, per il tuo obiettivo.
langs: [en, it]
defaultLang: en
spec:
pattern: report
branding:
theme: light
palette: { primary: "#14324a", accent: "#c0522b", background: "#faf7f2", foreground: "#1b1f24" }
fonts: { body: Inter, display: Fraunces }
auth:
method: magic_link
anonymous: { views: [home] }
roles:
- { key: admin, assignedBy: admin_emails }
- { key: user, assignedBy: signup }
limits:
- { action: run, per: user, max: 10, window: day, roles: [user] }
agents:
- key: writer
role: main
description: Writes the brief from its own knowledge (no tools).
profile:
inline:
display_name: City Brief writer
crews:
- id: writer
engine: agent_sdk
model: claude-sonnet-5-5
max_turns: 4
system_prompt: >-
You write short, factual city briefs. Use Markdown with a level-1 title and
four level-2 sections. Under 350 words. Never invent figures.
goalTemplate: |-
City: {city_label}
Goal: {goal_kind_label}
{?notes}Notes from the user: {notes}{/notes}
Write the brief in the language with ISO code {lang}.
output: markdown
inputForm:
title: { en: New brief, it: Nuovo brief }
fields:
- name: city
type: select
required: true
label: { en: City, it: Città }
options:
- { value: bologna, label: Bologna }
- { value: lisbon, label: { en: Lisbon, it: Lisbona } }
- name: goal_kind
type: select
required: true
label: { en: Goal, it: Obiettivo }
options:
- { value: live, label: { en: Living there, it: Viverci } }
- { value: visit, label: { en: Visiting, it: Visitarla } }
- name: notes
type: textarea
maxLength: 400
label: { en: Notes (optional), it: Note (facoltative) }
views:
- key: home
type: page
nav: false
sections:
- type: hero
title: { en: "A **one-page brief** on any city", it: "Un **brief di una pagina** su ogni città" }
text: { en: Pick a city and a goal. An AI agent writes the brief., it: Scegli una città e un obiettivo. Un agente AI scrive il brief. }
actions:
- { label: { en: Sign in to start, it: Accedi e inizia }, href: /login }
- { key: new, type: new_run, title: { en: New brief, it: Nuovo brief }, roles: [user, admin] }
- { key: briefs, type: history, title: { en: My briefs, it: I miei brief }, source: run, roles: [user, admin] }
- { key: brief, type: report, source: run, printable: true, nav: false }
- { key: account, type: account, title: { en: Credits, it: Crediti }, roles: [user, admin] }
billing:
modes: [credits]
signupCredits: 100
costs:
agent:writer: 10
packs:
- { key: small, credits: 200, price: 5 }
What the pieces do:
{city_label}and{goal_kind_label}are built-in placeholders: the label of the option the user chose, in the run's language.{?notes}…{/notes}is included only when the user wrote notes.- The agent is
inline: it is created on the platform when the app is published. See Agents and automation. homeis open to visitors (auth.anonymous.views). Its Sign in button is hidden once the user is signed in.brief(typereport) is where a finished run is shown. It is not in the menu.- Each brief costs 10 credits; new users get 100. See Billing.
To learn the manifest step by step, follow the manifest tutorial.