Totalum platform handbook

This page is the reference for the Totalum platform at platform.totalum.app — the app builder you sign up to and build in. It is deliberately terse: one or two lines per task, naming the exact screen. For the REST API and MCP, see the API overview.

#1 · Account and access

Accounts created on the old Totalum (accounts.totalum.app) are separate; the platform offers a one-time handoff when it recognises the address.

#2 · Plans and credits

Credits pay for everything the AI and the servers do. Two balances, and the plan credits are always spent first:

• Plan credits — granted monthly, reset each period, never roll over.
• Purchased credits — packs, referrals, signup bonus. Never expire.

People is how many can be on the account including you — Free's 1 means you alone, with no invitations available. A pending invitation holds a seat until it is accepted, revoked or expires.

One plan per account, covering every project on it. Projects is how many you may have at once — delete one and the slot is free immediately. New projects is how fast you may create them; it exists so a create-and-delete loop cannot provision servers faster than a person would.

Every paid plan lets you edit your code (in the browser editor or with the visual editor), download the full source, connect GitHub, attach your own custom domain and build Android and iOS apps — on every one of your projects, with no per-project allowance — backs up each live database every night, and publishes without the "Made with Totalum" badge. Buying a domain on Totalum needs Starter or above. Professional and Enterprise also give every project a <projectId>.webapp-project.com address with no "totalum" in it. Viewing your source code is free on every plan; only editing and downloading are paid. Connecting Figma is free on every plan too, including Free — you bring your own Figma token.

The API and MCP are on every plan, including Free; to white-label and resell, any paid plan. There is no other tier requirement: the only thing an API call needs is a positive credit balance, and API keys can be created from any account. See §12.

Accounts in Europe are billed in EUR, elsewhere in USD at the same number. Prices exclude tax.

Infrastructure, the database and the built-in integrations are billed with credits, not by the plan. Your plan's monthly credits pay for them and you can top up at any time.

#What the plan does not cap — backend and database

Your projects' backend and database grow with your traffic. The plan sets no ceiling and there is nothing to provision in advance:

• Unlimited database records — a table is bounded only by the database size (Limits).
• No limit on requests per second overall; the per-visitor rate limit and the emergency stop still apply (Limits).
• About 300 database queries per second per database copy (Limits). A database runs queries one at a time, so slower queries mean proportionally fewer per second.

You pay only for what you actually use, in credits:

These rates are the same on every plan — what a bigger plan buys is more monthly credits to spend on them.

#Built on Cloudflare

Your project's frontend and backend are deployed across Cloudflare's global network — 300+ cities in 100+ countries at once. There are no regions to choose, no servers to size and nothing to scale by hand: each request is served from a location near whoever made it. Scaling needs no change on your side, within the Limits.

Your project's database is fully managed by Totalum: a SQL database for development and another for the published site, nothing to provision, and EU-only storage when the project is created with EU data residency. Backups work like this: on every plan the database can be put back to any minute of the last 30 days; on a paid plan the live database is also backed up every night (a night with no changes makes no new copy), kept 7 days, 4 weeks and — Builder 3, Professional 6, Enterprise 12 — months, shown with a download and a restore button in the project's Database → Backups tab. These backups count as storage of the project; the free plan has no scheduled backups.

What costs credits. A prompt is metered by what the AI actually uses (at least 3 credits, usually 3 to 50; a run that fails without producing anything is refunded), so it has no fixed price — everything else is fixed (Get Credit Costs has the current list): create project 2 · publish 0.5 · start/restart server 2 · read source code 2 · restore a version 2 · rebuild 2 · custom domain 4 · export 4 · import 12 · manual database backup 2 · restore the database to a point in time 4 (back to a restore point is free) · pause or resume a project 2 · apply a visual edit 0.6. Uploading files and saving files are free. A mobile build is metered by its build time: 13.3 credits are held when it starts and settled on the real time when it ends (given back if it fails or is cancelled in the queue). A domain bought on Totalum is paid with the card on the account, not with credits, at the yearly price shown before buying.

Monthly fees, charged on each project's monthly anniversary: 3 credits for each month a project is live on a paid plan, that is published and online at any time in that month (1 for the project, 2 for its hosting; once per month; a month it stays unpublished or paused throughout is free) and 3 credits for each active custom domain.

Infrastructure and built-in integrations are metered in credits — the rates in the table above, and each integration call (AI, email, PDFs, scraping, browser sessions, …) by what it uses. The fixed prices and monthly fees above never change with usage.

You need at least 1 credit to start any of it, including a prompt.

Running out of credits mid-prompt. The agent stops, saves a working version of what it built so far (the preview keeps the last working one) and charges only what it used. Add credits (or turn on auto-recharge) and write "continue" in the chat to finish the pending work. A prompt that crosses the project's monthly development limit stops the same way: raise the limit, then write "continue".

Monthly limits per project. Every project has a monthly limit for development credits (the agent, publishing, project actions) and one for infrastructure credits (what the running app spends). Projects created in the platform start at 50,000 and 10,000; projects created through the API at 5,000 and 300. Change them in the project's Usage & limits; the projects page lists any project that reached one, with a Raise limit button.

A negative balance. Hosting keeps running at 0 credits, so a balance can go below 0; the app's built-in features (AI, e-mail, files…) stop until you add credits. At −300 we e-mail you and pause every site 48 hours later unless you add credits; a balance negative for 90 days in a row pauses the sites too (warned 7 days before); sites pause at once at −30 on the free plan and at −400, −600, −900 or −2,000 on Starter, Builder, Professional or Enterprise. Nothing is deleted, and the sites come back within a minute of adding credits. All the numbers: Limits.

Every charge in one table:

Where: Settings → Billing for the plan, credit packs, auto-recharge and cancellation. Upgrades apply immediately; a cancellation keeps the plan until the end of the period it is paid for.

#Free credits

• Invite someone (Settings → Referrals): 100 credits each when they first pay. New accounts only, never yourself, once per person, paid into purchased credits.
• Post about Totalum (the "Get free credits" menu): post on LinkedIn, X or Reddit, send us the link, ask for 200 credits (100 for X). A human reviews it and answers in your support chat. One open request at a time, keep the post public.
• 50 credits on signup, once.

#Payments, invoices, auto-recharge

• Payment method: Settings → Billing → manage the subscription; card changes happen on Stripe's own page.
• Invoices: Settings → Invoices — PDF or the Stripe copy. Business details for future invoices are edited from that page; issued invoices are final and cannot be changed.
• Auto-recharge: Settings → Billing. Pick a threshold and an amount and the saved card tops the balance up automatically, so a long build does not stop halfway.

#3 · Projects

Create one — the prompt box on /projects: describe the app and press Create. Costs 2 credits; the first build takes a few minutes.

What gets built: a Next.js 16 + React 19 app in TypeScript with Tailwind CSS 4, running on Cloudflare Workers, with its own SQL database (one for development and the preview, another for the published site), sign-in with better-auth, file storage, payments into your own Stripe account (connected through Stripe's onboarding, no key to paste) and the built-in integrations (e-mail, AI, PDF, scraping, scheduled jobs…) with no provider accounts to open. Every project is a real repository of code you can read, edit, download or push to GitHub.

Sign-in pages are built in, off until the app needs them. Ask for accounts ("users can sign up") and the app gets /login, /register, /forgot-password and /account. E-mail confirmation is off unless you ask for it; then the user types an 8-digit code sent by e-mail. Every site gets a browser icon by itself: your logo, or the app's initials on its brand colour.

Projects created before 8 October 2026 (or without the new engine) are legacy projects: they keep working exactly as before, forever, with no migration needed. Their database and SDK are described in Legacy Totalum SDK.

#4 · Building

You build by talking to the agent in the project's chat. One run at a time per project.

Mode (the agent tier) — the selector next to the prompt box: Auto (the default: picks the tier for each prompt), Cheap (the lowest price, for landing pages, redesigns and small edits), Normal (full apps and features) or Expensive (the most capable, for complex apps and bugs that keep coming back; uses the most credits).

Send the next prompt early — once a run says Ready (the change is in the preview), you can send the next prompt while it finishes; it waits and starts as soon as that run ends. Stop cancels the waiting prompt first.

The agent checks its own work — it opens the preview in its own browser and reads the app's logs (development and live). If something doesn't work, say what you did and what you saw; the agent reads the error logs first.

Development and production — every prompt changes the preview and its development database (with demo data); the published site and its live database only change when you Publish. The agent writes real production rows only when your prompt says so ("in production, mark order 42 as shipped").

The preview is broken / blank / unstyled. The workspace tells you which of two things it measured and offers the fix:

1. "This preview is broken" — the page is empty, unstyled, or showing the sandbox error screen. Press Ask the AI to fix it; it sends a prompt describing exactly that.
2. "This preview isn't running" — the HTML renders but no JavaScript loads, so nothing is clickable. Same button, different prompt.
3. "Cached snapshot · the server is asleep" — the sandbox archived itself after being idle. It wakes on its own; a prompt or a restart brings it back.

Restart the development server — the preview panel → Restart the server. Takes 2 to 4 minutes, the preview goes offline and prompts are paused meanwhile. Code and data are untouched. Costs 2 credits.

Edit visually — the Visual editor button over the preview: click any text, image, colour or size, change it, then apply. The changes are written into the real code. Paid plans only.

Edit the code — the Code tab: load the files (2 credits, then free for the session), open one, edit, Save. Saving does not change the running app — press Rebuild now (1 to 4 minutes) to make it live (2 credits). Files over 1 MB open only by downloading the project.

Go back to an earlier version — Project menu → Version history. Every completed run leaves a snapshot; Restore replaces the current code with it. Anything built since is lost and it cannot be undone. Costs 2 credits (Get Credit Costs has the current price) and takes 1 to 4 minutes.

Secrets (API keys, tokens your app needs) — Project menu → Secrets. Encrypted, never shown again after saving, and you choose development, production or both. Paste a whole .env at once if you like.

When the agent needs a key (for example another service's API key), it asks with a card in the chat instead of in its text: paste the value, choose the environment (development, production or both, or a different value for each), save, then press Tell the agent it can continue. Never paste keys into the chat itself.

#5 · Database

The Database tab in the workspace is the app's real data. Which database switches between Dev (the preview's test data, safe to change) and Live (the published app's real data).

Tables managed by Totalum (sign-in, sessions, migrations) are listed apart as System tables, read-only. For structural changes ask the agent ("add a status field to orders").

Legacy projects keep the older view: open a table → Edit on a row, files up to 12 MB each, and Filters with and / or groups and conditions on linked tables.

#6 · Publishing, domains and logs

Publish — the Publish button in the workspace. Takes a few minutes: it applies the pending database changes to the live database, then puts the new code live on the public <projectId>.totalum-project.com address; you can keep working while it runs. If the build fails, the agent tries to fix it and the live site keeps serving the previous version. A change that would delete live data asks for your confirmation first. Publishing again replaces what is live and keeps the same address. Costs 0.5 credits; a published project on a paid plan then costs 3 credits a month (1 for the project, 2 for its hosting).

An address without "totalum" — on Professional and Enterprise every published project also answers at <projectId>.webapp-project.com; both addresses serve the site, and the project's settings choose which one is the main address (shown and used for links). When webapp-project.com is the main address, the app's emails are also sent from p-<projectId>@mail.webapp-project.com instead of mail.totalum-project.com. On any paid plan you can use your own domain instead.

Custom domain — Project menu → Custom domain. Publish first (a domain points at the published app), then add one domain per project — a subdomain (app.example.com) or a whole domain (example.com, served as www.example.com) — copy the DNS records shown into your domain provider, and wait: DNS usually takes minutes but can take hours, then HTTPS is issued automatically. Nothing to confirm — it is detected. Costs 4 credits, then 3 credits a month while it is active; available on every paid plan, on as many projects as you like. If HTTPS fails, a DNS record is almost always missing or mistyped: fix it, remove the domain, add it again.

Buy a domain — Settings → Domains: search, buy it in your name with the card on your account (Starter or above), and attach it to a project with no DNS work. The registrant contact needs the country as a 2-letter code (ES) and the phone in international format (+34600111222). The first year can cost less than the yearly renewal; both prices are shown before buying. It renews every year automatically: the card is charged 30 days before the expiry (retried 21 and 15 days before), and if the renewal is still unpaid 14 days before the expiry, automatic renewal is switched off and you get an e-mail — use Renew now on the Domains page before the expiry to keep it.

Domains are per project. Each project has its own address and its own custom domain. One domain that replaces the address of every project of an account at once is not supported.

Emergency stop — if the app suddenly uses far more than normal (a loop of requests, database writes or paid built-in calls), its site is paused to protect your credits: visitors see a paused page and you get an e-mail. The workspace shows what was measured, Ask the AI why (fix the cause first) and Bring it back online; otherwise it comes back by itself after 24 hours. Before that, once the app spends half of that amount in one hour, its image, video and speech AI wait until the next hour; text AI keeps working. The numbers: Limits.

Logs — Project menu → Logs, with two sources:

• Development — live output from the server behind your preview.
• Production — requests to your published site. Delivered in batches, so the last couple of hours may be missing — that is normal, not a fault. Searchable across the whole window with regular expressions.

Mobile apps — the Mobile app button in the workspace header (it appears once you ask for a mobile app) or Project menu → Mobile apps, on any paid plan. Ask the agent to make it work as a mobile app, publish, then build: Android (an .apk to install, or an .aab for Google Play) and iOS (a simulator build, or a signed .ipa for TestFlight). The app opens your published site, so publish first. Signed builds and store uploads use your own developer accounts: a Google Play account for Android and an Apple developer account for iOS. One build per project per hour; builds wait in a queue when others are running.

Payments — ask the agent for a checkout or subscriptions; once the project takes payments, a Set up payments button appears in the workspace header (Manage payments once connected). Stripe's checkout opens in a new tab. The preview always takes Stripe test cards (4242 4242 4242 4242). To receive real money, publish first, then connect your own Stripe account from that window and switch the published site to real payments. Payment events (renewals, refunds…) reach the app by themselves, on the site where the checkout was made. Under Advanced: also send them to another address, or use your own Stripe key instead. Details: Payments.

Your users' own accounts (Google Calendar, Gmail, Drive, Outlook, Slack…) — ask the agent, e.g. "when a call is scheduled, create an event with a Google Meet link in my calendar and invite the client". The app shows a Connect your Google account button; each user signs in on Google's own page (a new tab) and the app then acts on that user's account only. No Google Cloud project, client id or key is needed. A new connection costs a few credits once and each action a small fraction of a credit. Details: totalum.connections.

#7 · GitHub and Figma

Connect GitHub — the project's Code tab → Sync with GitHub. You need a fine-grained personal access token (github_pat_…) scoped to one existing repository with Contents: Read and write (the panel's longer list of permissions also works). If the repository already has code it needs develop and main branches. On the first connection you choose which side wins: Totalum → GitHub, or GitHub → Totalum. Paid plans only, on as many projects as you like.

How the two-way sync works — this is the whole contract:

• Before every prompt Totalum pulls the latest from develop; if your commits and the agent's change touch the same lines, the agent merges them in the same run.
• After every prompt (and every file edit, visual edit or restore) it commits and pushes to develop.
• When you publish, main moves to the published code. Nothing on GitHub is force-pushed: your commits stay in the history.
• Work on develop on your own machine; commits pushed straight to main are not deployed.
• Pull from GitHub at any time from the same panel.

Run the code on your computer — project menu → Project API keys → Run the project on your computer → Download .env (development; the live .env.prod is beside it). Put it in the cloned folder, then npm ci and npm run dev. Never commit it. Step by step: Connect to GitHub.

If the token expires or is revoked the panel says so; reconnect with a new one.

Connect Figma — Project menu → Figma, paste a Figma personal access token. The agent can then read the designs you link in a prompt and build from them. Available on every plan, including Free — you bring your own Figma token, so there is nothing for us to meter. Each project is connected separately, and you can disconnect from the same panel.

#8 · Team

Settings → Team. Invite someone by email (a +tag address works; if their mailbox already has a Totalum account, invite the exact address they sign in with) and pick what they can do:

• Admin — everything in the account.
• Manager — only what you tick: which projects (view or edit, or all projects now and later), whole groups, create projects, manage billing, see usage, manage API keys.

Members work on your projects and spend your credits. Nobody but the owner can change or cancel the plan, invite people, delete a project or close the account. How many people fit is set by your plan — Free 1 · Starter 3 · Builder 5 · Professional 10 · Enterprise 500, and the owner is one of them, so a free account can invite nobody. A pending invitation holds a seat until it is accepted, revoked or expires. Invitations can be resent, revoked or edited; a member can be removed or signed out of every device.

#9 · Notifications

Settings → Notifications, three kinds:

• Emails — product news (monthly at most) · your first build finishing · running low on credits. Each is a separate switch.
• Browser notifications — two switches: "tell me when a long build is ready" and "tell me when support replies". The first one notifies when a prompt that took more than 5 minutes finishes while the project's tab is in the background (the tab must stay open; with the tab closed, the first build still sends its email). The chat also offers it once, during your first build. Granted per browser, so the switches only apply to the browser you set them in. If it is blocked, allow notifications for the site next to the address bar and try again.
• Sound — the chime when a run finishes, in Settings → Preferences.

#10 · Usage

Settings → Usage: where credits went, by day, project and action. The sidebar always shows the balance, split into plan credits and purchased credits — the tooltip explains which is spent first.

Per project — Project menu → Usage & limits: what the project spent (live site, preview, building with AI) by feature; its monthly limits for the AI agent (development) and for the app's features (infrastructure); each built-in feature on or off with its own monthly limit (in credits, or in calls, e-mails, pages… under Advanced).

Projects at their limit — /projects shows a notice when a project reached a monthly limit, and a badge on its card. Review lists them: Raise limit for one, or Raise all… (double, add a fixed amount, or no limit). Only the account owner can raise them.

#11 · Limits worth knowing

Every limit, and which ones we can raise on request, is on Limits. The ones people meet most:

• 1 credit minimum to start any paid action; a prompt is metered, not fixed-price.
• One agent run at a time per project; a publish, rebuild, restore or import blocks the others while it runs.
• How many projects you may have at once is set by your plan (Free 2 · Starter 10 · Builder 50 · Professional 300 · Enterprise unlimited). Reaching it does not affect anything you have already built: delete a project you no longer need, or move up a plan. We email you the first time you hit it.
• How fast you may create them is also set by your plan (Free 1 a minute · Starter 5/min · Builder 10/min · Professional 30/min · Enterprise 100/min). Unlike the limit above, this one clears on its own — wait and try again.
• An app that suddenly uses far more than normal is paused by the emergency stop; bring it back from the workspace.
• Code editing, source downloads, GitHub connections, custom domains and mobile apps are on every paid plan, on every project (Limits) and are not available on Free. Reading your code, and connecting Figma, are free on every plan.
• Scheduled jobs per environment: Free 2 (at most hourly) · Starter 10 · Builder, Professional and Enterprise 20 (down to every minute).
• One prompt works for up to about 40 minutes, then wraps up and saves; most take a few minutes.
• Largest file an app can upload: Free 50 MB · Starter, Builder and Professional 500 MB · Enterprise 1 GB. Code files over 1 MB cannot be opened in the browser editor.
• Export: 5 an hour per project.

#12 · API, MCP and building your own builder

Everything above is available programmatically.

• API key: the API page in the platform. Keys start with tlm_sk_ and must stay on your own server.
• An app builder of your own: when your first prompt asks for an app that builds apps, the platform gives that project an API key of its own (listed on the API page as For your app builder; revoke it there). It may send 600 requests a minute and 300 prompts an hour; it creates projects at your plan's rate. Deleting the project revokes it.
• REST API: API overview and the Quickstart.
• MCP (Claude Code, Cursor, Codex…): MCP setup — same key.
• White-label app builder: the platform is one client of a public API, so you can build your own branded builder on it. See Build your own AI app builder and the open reference implementation at github.com/totalumlabs/ai-app-builder-open.

#13 · Support

The Need help? button in the workspace, or the Support page. Attach a screenshot or a file if it helps. Replies arrive in the same chat, and — if you allowed browser notifications — as a desktop notification.