Documentation · App Builder
How the runtime serves an app
Every published app is served by the same runtime. The runtime reads the app's manifest and does what it says: it shows the pages, signs users in, keeps the data, starts the agents, runs the schedules and takes the payments. There is no code of yours on the server. This page explains what happens and what you can rely on.
Addresses
The runtime picks the app from the address the request comes to.
| Address | Serves |
|---|---|
<slug>.webrobot.eu | The published app. |
preview-<slug>.webrobot.eu | The saved draft (App Studio's preview). |
A domain in spec.domains | The published app, on your own domain. |
spec.host | The published app, on that host. |
- An app with your own domain still answers on
<slug>.webrobot.eu. - For a domain in
spec.domains, create a DNS CNAME record pointing it at<slug>.webrobot.eu, then publish. Publishing routes the domain to the runtime. - A host or domain can belong to one app only. Publishing refuses one that another app uses: "host
<host>is already used by another app". - Links the app builds (sign-in links, Stripe return pages, emails) use the app's own address, never the address a request claims to come from. Outside local development the app is served over HTTPS only.
The preview address is not public. It opens with the token App Studio gives when you press Open preview (valid for at most one day), or for a signed-in admin of the app. Otherwise it shows the sign-in page.
From request to page
- The app. The runtime looks up the app for the address and reads its published manifest (the draft, on the preview address). The manifest is validated again: an invalid one is not served. A new publish is live within about 30 seconds.
- The language. See Languages.
- The user. The session cookie, if any, says who is signed in. The user's role comes from the manifest on every request (see Sign-in and users).
- The page.
/shows the view keyedhomewhen the user may see it, else the first menu view they can open, else the sign-in page./v/<key>shows one view; a visitor who may not see it is sent to sign in./r/<id>shows a run. - Actions. The browser's actions (a form, a run, a chat message, a purchase) go to the app's own API under
/api/…, with the checks described in Security.
When no app is published on an address, pages say "No app is published on this address." and the API answers 404 {"error": "no app on this host"}.
Data
Each app has its own document store. Every record belongs to one app and one collection, and has an id. The store also keeps the runtime's own data for the app: users, sessions, sign-in tokens, the credit ledger, runs, chats, approvals, instances, files, outbox, credentials and a few more. A manifest cannot declare, show or give a tool over these: their names are reserved (see Validation).
What keeps data apart:
- Between apps. An app reads and writes only its own store. Two apps of the same organisation share nothing.
- Between organisations. Each app's agents run on the platform with the app's own API key, which belongs to the app's organisation.
- Preview and published app. The preview has its own store and its own users. Runs, records and payments made in the preview never touch the published app's data.
- Between users. Who reads and writes which record follows the collection's owner (
user,instance,app,shared,org) and its access rules — in views, forms, agent tools and agent context alike. See Data.
Retention. A collection with retentionDays loses its older records once a day (by createdAt).
The scheduler
A scheduler tick runs every few minutes over every published app that has schedules, triggers, approvals, templates, emailOnRunDone or a retention. One tick:
- starts the schedules that are due (see Schedules);
- runs the triggers on a timer (
on.cron) and on a date (on.date); - checks form runs nobody is watching, when
notifications.emailOnRunDoneis on; - runs the template instances that are due;
- deletes records past their retention (once a day);
- decides approvals past their timeout;
- collects the scheduled and triggered runs that finished: their result becomes a record of
writesTo, the report is delivered, the instance is updated.
After a pause, the scheduler catches up at most the last 3 hours, so an outage does not replay a whole day. Cron expressions are in UTC.
Agents on the platform
The runtime does not run models itself. It starts each agent on the WebRobot platform, with the app's API key, and follows it until it ends.
- App tools. An agent with app tools calls them on the app's own MCP endpoint (
/api/mcp). Publishing gives each agent its own address and token: the agent sees and calls only its own tools. An app published before per-agent tokens existed keeps one token for all its tools until it is published again. - The app session. The runtime puts a short-lived session (3 hours) in the agent's task. The agent passes it to the tools, and the runtime maps it back to the user the work is for. This is how a tool reaches only that user's records, even if a user asks the agent for someone else's.
- Users' keys. A key a user connected (for an
httptool) is encrypted at rest, tied to the app and the user, and added to the request by the runtime. The agent never sees it. - External services.
httptools reach only the hosts inspec.egress.hosts, with the guards in Egress. - Slots. Python slots run in a WebAssembly sandbox, never in the runtime.
App tools are not served on the preview address.
Rate limits
Some limits are fixed by the runtime, whatever the manifest says.
| What | Limit |
|---|---|
| Sign-in emails requested | 10 an hour per IP address; 3 an hour per email address (more requests get the same answer, without an email); an hourly cap per app |
| Sign-in codes typed | 20 an hour per IP address |
| Chat messages | 30 an hour per user, 60 an hour per IP address |
| Forms sent by visitors (not signed in) | 5 an hour per IP address and form |
| Actions started by triggers | 20 a minute per app |
| Emails | 300 a day per app, 10 a day per recipient |
| Push notifications | 20 a day per user |
| One reply at a time | per chat conversation |
The sign-in, chat and trigger counters are kept by each runtime instance. Your own quotas go in spec.limits: see Billing.
Security
The manifest is written by people and by the builder agent from free text. The runtime treats it as untrusted input, like anything users send.
Pages and content
- Colours must be
#rrggbb; other values are dropped. - Fonts must be plain names (letters, digits and spaces, up to 41 characters); they are loaded from Google Fonts.
- Logo. An SVG logo is cleaned against an allow-list of drawing elements and attributes: no script, style, animation, links, external images or
url()outside the logo itself; at most 20,000 characters. It is shown as an image, where the browser runs no script. A logo URL must behttps://. - HTML blocks of pages are cleaned against an allow-list of layout and text tags. Script, event handlers, forms, iframes and non-https links never survive; inline style keeps only layout and colour properties, never
url(). Links to other sites open in a new tab, without access to the app's page. - Markdown (reports, chat replies, page texts) is escaped first and then rendered: headings, lists, tables, bold and italic, code,
httpslinks and same-app paths, and charts. No HTML from an agent reaches the page. - Links in the manifest must be same-app paths,
#anchorsorhttps://; anything else becomes#.
Sign-in and sessions
- Sign-in is by email: a link valid for 15 minutes and usable once, and a 6-digit code that dies after 5 wrong tries.
- The sign-in email is a fixed platform text "sent by WebRobot on behalf of the app". Only the app's name varies, cleaned to one line of at most 60 characters without links or addresses.
- The session cookie is
HttpOnly,SameSite=Lax,Secure, valid 30 days, and signed for one app: a session of one app never opens another, even though all apps live underwebrobot.eu. - After sign-in, the user is sent back only to a path of the same app.
Requests that change something
All apps share the webrobot.eu site, so the runtime does not rely on cookies alone. Every request that changes something must:
- send a JSON body (
Content-Type: application/json), or for a file uploadmultipart/form-datawith the headerX-VK-Upload: 1; otherwise 415; - come from the app's own origin (
Originheader); otherwise 403 "cross-origin request refused".
A page on another app, or on any other site, cannot act for a signed-in user.
Files
- A file field accepts the extensions it lists (default: pdf, docx, xlsx, csv, txt, jpg, jpeg, png, webp), up to its
maxMb(default 10 MB, never more than 15 MB). - The content must match the extension: a renamed file is refused ("the file is not a valid pdf").
- File names are cleaned. Text is extracted from PDF, Word, Excel, CSV and text files for the agent's goal.
- A file is readable only by the user who uploaded it and by the app's admins. It is downloaded as an attachment, never shown inline.
Webhooks and payments
- A webhook needs the trigger's own secret; a signed body is checked for tampering and replay (see Triggers).
- Stripe notifications are verified with Stripe's signature, and every Checkout session is read back from Stripe before credits are added. Prices come from the published manifest, never from the browser.
Errors
The API answers errors as JSON with an HTTP status:
{ "error": "not enough credits", "needed": 20, "balance": 5 }
| Status | Typical meaning |
|---|---|
| 400 | A value is missing or wrong ("Email is required", "invalid choice …"). |
| 401 | Sign in first. |
| 402 | Not enough credits, or a plan is needed. needed and balance come with a credits error. |
| 403 | Not allowed for this user or role. |
| 404 | No such record, view or app. |
| 409 | Not possible now ("publish the app first", "the assistant is still answering", "already decided"). |
| 413, 415 | A file or body too large, or of the wrong type. |
| 429 | A limit was reached. |
A view type the runtime does not render yet says "This view is not rendered by the runtime yet" instead of failing.
Agents that did not start. When the app starts an agent by itself (a trigger, an approval decision, a date) and the platform refuses it, or a limit stops it, the reason is kept for the app's admins. They see it at the top of the data page (/admin/data), with the agent, what started it, and when. The most common reason, a missing AI provider in the organisation, comes with what to do. Starts by schedules and template instances are not listed there.
Languages
metadata.langslists the app's languages (two-letter codes);metadata.defaultLangis the default.- The language of a page is the one the user chose, else the first one their browser asks for, else the default. A language the app does not declare is never used.
- The language switcher (
/lang?l=<code>) remembers the choice for a year and returns to the page the user was on. - Every text of the manifest can be one string or one string per language (
{en: "…", it: "…"}). A missing language falls back to the first one given. - The runtime's own words (buttons, sign-in, messages) exist in English and Italian; other languages use English.
Health
GET /api/health answers {"ok": true, …} while the runtime is up.