WebRobot
App Builder · pages

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:

KeyValue
apiVersionAlways webrobot.eu/v1alpha1.
kindAlways VerticalApp.
metadataThe app's identity: slug, name, languages.
specEverything the app does.

No other top-level key is accepted.

metadata

FieldRequiredWhat it is
slugyesThe app's unique name. It gives the default address <slug>.webrobot.eu.
displayNameyesThe app's name, shown in the header, the browser tab and the sign-in email. A plain string.
taglinenoOne line about the app. It becomes the page description for search engines. Translatable.
descriptionnoA longer description. Translatable.
langsnoThe languages of the app, as two-letter codes, e.g. [en, it]. At least one, no duplicates.
defaultLangnoThe language used when the visitor's language is not in langs. It must be one of langs.
timezonenoAn IANA time zone, e.g. Europe/Rome. Today the runtime uses it only for service hours when those do not set their own zone.
organizationIdnoThe 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.

KeyWhat it is forRead more
patternThe shape of the app: report, chat, dashboard or pipeline.below
hostA different default host name for the app.below
domainsYour own domains, served by the app.below, Publishing
brandingColours, fonts, logo, theme, buttons.below
headerThe top bar for visitors: links, a call to action, an announcement.below
authSign-in method, what visitors may open without signing in, roles.Sign-in and roles
limitsRate limits and quotas per user (admins are exempt).Agents and automation, Data
agentsThe AI agents of the app, their goals, tools and memory.Agents and automation
inputFormThe form a user fills in to start a run of the main agent.Views, Data
dataCollections of records, data jobs, credentials users connect.Data
viewsThe pages of the app.Views
schedulesAgents or jobs that run on a timetable.Agents and automation
triggersEvents that start an agent, a team or a job, send an email, write a record or charge credits.Agents and automation
teamsAgents that work together as one.Agents and automation
approvalsHuman checkpoints an agent waits for.Agents and automation, Views
templatesAgents each user creates for themselves, with their own parameters and schedule.Agents and automation, Views
slotsSmall Python functions the runtime runs in a sandbox.Agents and automation
egressThe external hosts the app's HTTP tools may call.Agents and automation
channelsWhere conversations come from (the web chat, a phone number, a bot, a mailbox).Messaging
notificationsEmails to users when their run ends.Messaging
serviceHoursWhen the app's chat must answer fast.Agents and automation
billingHow users pay: credits, packs, plans.Billing
mobileThe phone app and the phone features it uses.Export
exportsEndpoints the app serves to other programs.Reference
extensionsCustom 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: Bookings
    
  • or 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:

  1. the string for lang, if the object has it;
  2. otherwise the first string in the object, in the order you wrote it;
  3. 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).

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.

FieldWhat it does
paletteThe colours: primary, accent, background, foreground. Each is #rrggbb.
paletteDarkThe same four colours for the dark theme.
themelight, dark or auto. auto follows the device's setting and needs paletteDark. dark uses paletteDark when it is set.
tokensExtra named colours (#rrggbb), e.g. one per status value. Each becomes a CSS variable --<name> (_ becomes -).
tokensDarkThe tokens for the dark theme.
fontsbody, 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.
logoAn inline SVG (up to 20,000 characters, cleaned) or an https:// image URL.
wordmarkThe app's name in up to 4 parts, each with an optional color (a palette or token key). Replaces displayName in the header.
bylineSmall text after the name, e.g. "by Acme". Translatable.
buttonThe palette or token key used for main buttons (default accent).
buttonShapepill (default), rounded or square.
ghostButtonSecondary buttons: outline (default, in the button colour) or neutral.
headingWeight400 to 900, in steps of 100 (default 700).
headingTrackingnormal or tight (slightly closer letters in headings).
brandWeightWeight of the name in the header: 500 to 900.
widthPage 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

spec.header is the top bar for visitors.

FieldWhat it does
linksUp 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.
ctaOne button {label, href}. It replaces the Sign in button for visitors who are not signed in.
announcementOne 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:

ValueShape
reportA user fills in a form, an agent runs, the user gets a report.
chatA conversation; each message starts the agent.
dashboardAgents or jobs run on a schedule; users read the results.
pipelineAn 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:

  1. an app whose spec.host or one of whose spec.domains equals the host;
  2. 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:

  1. 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.

  2. 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);
    • defaultLang is one of langs; theme: auto has paletteDark;
    • a form view writes a declared collection that has fields;
    • a booking view writes a collection ownedBy: user;
    • placeholders in an agent's goalTemplate are 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. credits needs 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: user or instance) that pages, tools, selects or triggers read, but that nothing writes (no form, booking, agent tool, writesTo or trigger write).
  • Forms that cannot save. A form for everyone on a shared or app collection: 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.mobile is 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.
  • home is open to visitors (auth.anonymous.views). Its Sign in button is hidden once the user is signed in.
  • brief (type report) 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.