# backend.fast > Public documentation for the development platform. Install the bfast CLI, manage apps over HTTPS, and use the supported V1 language. Start with /agents/ and /quickstart/. Platform agent keys manage apps. App user tokens authenticate business requests. The feature matrix defines current support; this is not a claim of full V1 implementation. ## Guides - [Build with an agent](https://docs.backend.fast/markdown/agents.md): Markdown for https://docs.backend.fast/agents/ - [App lifecycle](https://docs.backend.fast/markdown/app-lifecycle.md): Markdown for https://docs.backend.fast/app-lifecycle/ - [App authentication](https://docs.backend.fast/markdown/authentication.md): Markdown for https://docs.backend.fast/authentication/ - [SDK and OpenAPI](https://docs.backend.fast/markdown/clients.md): Markdown for https://docs.backend.fast/clients/ - [CLI and dashboard together](https://docs.backend.fast/markdown/dashboard.md): Markdown for https://docs.backend.fast/dashboard/ - [Email and SMTP](https://docs.backend.fast/markdown/email.md): Markdown for https://docs.backend.fast/email/ - [Events and jobs](https://docs.backend.fast/markdown/events-and-jobs.md): Markdown for https://docs.backend.fast/events-and-jobs/ - [Complete source examples](https://docs.backend.fast/markdown/examples.md): Markdown for https://docs.backend.fast/examples/ - [Files and account storage](https://docs.backend.fast/markdown/files.md): Markdown for https://docs.backend.fast/files/ - [Build a backend. Keep the control.](https://docs.backend.fast/markdown/index.md): Markdown for https://docs.backend.fast/ - [Install and sign in](https://docs.backend.fast/markdown/installation.md): Markdown for https://docs.backend.fast/installation/ - [The backend.fast language](https://docs.backend.fast/markdown/language.md): Markdown for https://docs.backend.fast/language/ - [Tiers and current limits](https://docs.backend.fast/markdown/limits.md): Markdown for https://docs.backend.fast/limits/ - [Models, queries and caching](https://docs.backend.fast/markdown/models-and-queries.md): Markdown for https://docs.backend.fast/models-and-queries/ - [Deploy your first app](https://docs.backend.fast/markdown/quickstart.md): Markdown for https://docs.backend.fast/quickstart/ - [CLI command map](https://docs.backend.fast/markdown/reference/cli.md): Markdown for https://docs.backend.fast/reference/cli/ - [Current feature status](https://docs.backend.fast/markdown/reference/status.md): Markdown for https://docs.backend.fast/reference/status/ - [Troubleshooting](https://docs.backend.fast/markdown/troubleshooting.md): Markdown for https://docs.backend.fast/troubleshooting/ - [Manage app users](https://docs.backend.fast/markdown/users.md): Markdown for https://docs.backend.fast/users/ ## Downloads - [CLI installer](https://dash.backend.fast/install.sh) - [Complete Markdown](https://docs.backend.fast/llms-full.txt) - [Source revision and checksums](https://docs.backend.fast/source.json) - [Counter DSL](https://docs.backend.fast/examples/simple-counter/backend.fast) - [Shortener DSL](https://docs.backend.fast/examples/url-shortener/backend.fast) - [Minidesk DSL](https://docs.backend.fast/examples/minidesk/backend.fast) --- # Build with an agent Canonical page: https://docs.backend.fast/agents/ ## Read these public sources Start with [llms.txt](https://docs.backend.fast/llms.txt). Fetch [the current feature status](https://docs.backend.fast/reference/status/) before writing DSL. It defines the implemented subset and explicit limitations. Every page has a matching `/markdown/.md` URL. The complete text is [llms-full.txt](https://docs.backend.fast/llms-full.txt). No page needs a dashboard session. ## Bootstrap The human creates a verified platform account and issues a scoped agent key. Use the [installer](https://docs.backend.fast/installation/) and `bfast login --token-stdin` with a secret manager pipe. Never place the key in a tool argument, app source or URL. ```bash curl -fsS https://dash.backend.fast/install.sh | sh bfast version bfast whoami --json ``` Backend operations use public HTTPS. No SSH access, node filesystem or repository checkout is required. Download the source examples directly from this site: ```bash mkdir -p agent-counter curl -fsS https://docs.backend.fast/examples/simple-counter/backend.fast \ -o agent-counter/backend.fast bfast deploy --name agent-counter --tier small ./agent-counter bfast inspect --json agent-counter ``` Use a fresh name if `agent-counter` already exists. Read the complete [quickstart](https://docs.backend.fast/quickstart/) for test users, protected requests, update and cleanup. ## Execution rules - Put flags before positional arguments. Use `--json` for machine-readable output. - Read the stored app URL from `inspect`. Never derive it from the display name. - Keep the declared DSL app name unchanged during update. - Preserve model/private schemas during normal update. Do not assume arbitrary migrations. - Record operation IDs. A lost reply does not prove failure. Inspect the accepted operation before submitting another mutation. - Use a platform key for app management. Use an app-user token for business routes. - `--verified` is an owner attestation for test users. Real public signup needs verification mail. - Treat app deletion as retained data. Do not promise a permanent purge or refund. - Reject unsupported features explicitly. Do not invent API commands, DSL syntax, OAuth providers or CORS behavior. ## Feature choices Use [models and queries](https://docs.backend.fast/models-and-queries/), [auth](https://docs.backend.fast/authentication/), [events/jobs](https://docs.backend.fast/events-and-jobs/), and [files](https://docs.backend.fast/files/) when their current subset matches the requirement. [Limits](https://docs.backend.fast/limits/) lists current resources and payload bounds. [Troubleshooting](https://docs.backend.fast/troubleshooting/) describes expected failure responses. Small is 130m CPU and 256 MiB. Medium is 250m and 512 MiB. Fresh native apps have no commercial stored-user count or small global session count. Resource and operation guards still apply. Accounts initially share 10,000,000,000 object bytes. The platform remains in development. High availability, arbitrary packages, general external network access, Apple login, managed cross-origin browser SDK policy and automatic customer restore are not supported promises. ## Definition of done Check the operation result and public health. Create or use a scoped app user. Verify an authenticated write/read. After update, verify the same app ID, URL and acknowledged data. Confirm dashboard visibility. Report unsupported features and retained data clearly. Keep credentials out of generated reports. ## Source provenance [source.json](https://docs.backend.fast/source.json) records the committed source revision and SHA256 values for the feature matrix and downloads. The public projection excludes operator runbooks and private node state. Documentation releases update that snapshot; they do not make this site a live control API. --- # App lifecycle Canonical page: https://docs.backend.fast/app-lifecycle/ ## Create and inspect A project directory contains one `backend.fast` source file. The CLI sends its source over HTTPS for a bounded remote build. ```bash bfast deploy --name my-counter --tier small ./my-counter bfast apps list --json bfast inspect --json my-counter ``` The platform assigns your account as owner. Creation returns a stable app ID and a hostname such as `amber-apex-a1b2c3.tr1.edge.backend.fast`. The display name stays separate. Creation waits for public health by default. ## Track operations ```bash bfast deploy --wait=false --name another-counter --tier medium ./my-counter bfast operations --json '' bfast operations --wait '' ``` Mutations print an operation ID. The default wait bound is fifteen minutes. A command interrupted after admission can still complete. Repeat the same command to reuse its pending request ID. Inspect that operation before using `--new-request`. A changed body with the same request ID fails. The service bounds build admission and worker capacity. Overload can reject admission explicitly. A failed build does not silently select another runtime. ## Update ```bash bfast update --app my-counter ./my-counter bfast inspect --json my-counter ``` Normal update preserves the app ID, URL, tier, retained volume and acknowledged data. Keep the original DSL `app` name and compatible model/private schemas. Unsupported schema changes fail explicitly; this is not a general migration tool. Validate an authenticated read after the update. ## Delete ```bash bfast delete my-counter ``` Completed deletion removes the app from the active catalog and closes its URL with HTTP 410. The result reports `retained_data: true`. The data volume remains. Saved R2 objects remain charged. Deleted deployment names are not reusable. There is no public permanent purge or automatic restore workflow yet. ## Recovery boundary The current runtime keeps one writable pod and retained volume per app. K3s owns pod recovery. The platform preserves stop/delete intent and does not create extra writable replicas. High availability and replacement-node recovery remain separate work. A Ready pod alone does not prove public routing; the CLI also checks public HTTPS health. --- # App authentication Canonical page: https://docs.backend.fast/authentication/ ## Two identities | Identity | What it controls | How you use it | | --- | --- | --- | | Platform account and agent key | Owned apps, deployment, user administration and dashboard | `bfast login` and management commands | | App user and app session | Protected routes and records inside one app | App login, then `Authorization: Bearer ` | The same email address can identify different users in different apps. Your platform login does not create an app user. Never send a platform key to an app's business or auth endpoints. Fresh apps use native auth in their own SQLite database. Password checks, session checks, current roles and business authorization stay local to that app. Platform accounts use the platform's separate auth service. Existing shared-auth apps retain their selected backend. ## Test without SMTP ```bash bfast users create --app my-counter --email tester@example.invalid \ --name "Test User" --verified bfast request --app my-counter --email tester@example.invalid --path /counters ``` Both commands prompt for the app password as needed. The owner verification flag is an explicit attestation. It does not prove inbox ownership. See [user commands](https://docs.backend.fast/users/). ## Public signup Configure [app SMTP](https://docs.backend.fast/email/) first. Use the exact stored app origin for all paths. The supported callback is `/__bf/auth/complete`. ```http POST /__bf/auth/sign-up/email Content-Type: application/json Origin: https://amber-apex-a1b2c3.tr1.edge.backend.fast {"name":"App user","email":"you@example.com","password":"","callbackURL":"https://amber-apex-a1b2c3.tr1.edge.backend.fast/__bf/auth/complete"} ``` Open the verification link from the user's inbox. It returns a completion page. Missing mail configuration does not bypass verification. The platform sender does not automatically configure every customer's app sender. ## Log in ```http POST /__bf/auth/login Content-Type: application/json Origin: https://amber-apex-a1b2c3.tr1.edge.backend.fast {"email":"you@example.com","password":""} ``` The response includes `access_token`, `token_type: "Bearer"` and user details. Treat the token as an **opaque** value. Native login does not return the legacy `expires_in` field. Do not decode a token as a JWT or infer its format. ```http GET /counters Authorization: Bearer ``` Cookie clients must send the exact app Origin on mutations. Native login sets a Secure, HttpOnly, host-only refresh cookie. General browser access from unrelated origins is not enabled. Use a server client or the registered app origin. ## Refresh, logout and reset | Action | Request | | --- | --- | | Refresh | `POST /__bf/auth/refresh`, JSON `{}`, current app bearer and session cookie | | Logout | `POST /__bf/auth/logout`, JSON `{}`, current app bearer and session cookie | | Request reset | `POST /__bf/auth/request-password-reset`, JSON `email` and the exact `callbackURL` | Native refresh replaces the token and preserves its absolute one-hour deadline. It does not extend the session indefinitely. Log in again after expiry. Logout revokes that session. Password reset and owner account changes revoke applicable sessions. Store cookies securely; do not put tokens into URLs or persistent browser storage. Use the [Counter Python client](https://docs.backend.fast/examples/simple-counter/client.py) for a complete prompt-based example, or let `bfast request` handle one login/request/logout cycle. Reusing app sessions is appropriate for real clients. Repeated CLI logins are not a throughput benchmark. ## Roles and ownership `@auth none`, `@auth user`, `@auth admin` and `@auth user owns Model.field` control routes. Caller-supplied user/role headers grant no authority. The app checks the current user and role in the business transaction. An app administrator receives no platform or other-app privilege. Fresh native apps have no commercial user-count cap or small global session cap. Separate operation budgets, one password task, bounded cleanup and disk headroom remain. Optional per-user controls can restrict sessions. These limits bound work; they do not promise unlimited capacity. See [current limits](https://docs.backend.fast/limits/). --- # SDK and OpenAPI Canonical page: https://docs.backend.fast/clients/ ## Download the selected contract ```bash bfast sdk --app my-counter --out client.ts bfast openapi --app my-counter --out openapi.json ``` These commands require a platform key with read scope. The platform verifies the contract hash against the selected deployment. A candidate build cannot replace its selected contract. Older deployments without hashes need an update. The generated TypeScript client has no package dependencies. Use it from a server client or the app's registered origin. Managed browser CORS for unrelated frontend origins remains separate work. ## Authenticate requests ```typescript import { Client, APIError } from './client'; const client = new Client({ baseUrl: appURL, accessToken: () => currentAppSessionToken, }); const counters = await client.listCounters(); console.log(counters[0].value.toString()); ``` The token callback can return a promise. The client treats tokens as opaque, sends a bearer header, omits ambient cookies and refuses redirects. It performs no automatic request retries. Use `signal` for cancellation and `fetch` for a custom server transport. See [app login](https://docs.backend.fast/authentication/). ## Types and arguments The first method argument holds path/query parameters. The second holds the JSON body. A body without path/query parameters uses `{}` as its first argument. A single body parameter uses its value directly, such as a string. Multiple body parameters use an object with the declared names. Request types preserve optional/defaulted fields. Responses have required fields and explicit nullable values. IDs, times, dates and durations use strings. V1 `int` maps to `bigint`. The client preserves exact signed 64-bit integers during JSON encoding/decoding. Use `toString()` for display. OpenAPI separates input and output schemas. It includes defaults, enums, opaque bearer security, error envelopes and managed File routes. ## Files and failures Use standard `File` objects and the methods described in [File storage](https://docs.backend.fast/files/). `APIError` exposes `status`, `code` and `message` for application HTTP failures. Malformed response JSON uses `invalid_response`. Transport and cancellation errors come from the chosen fetch implementation. ```typescript try { await client.listCounters(); } catch (error) { if (error instanceof APIError) console.log(error.status, error.code); else throw error; } ``` --- # CLI and dashboard together Canonical page: https://docs.backend.fast/dashboard/ The [dashboard](https://dash.backend.fast) and CLI share the owned app catalog. An app created with your agent key appears under the same platform account. The display name, immutable ID and stored URL describe the same app in both tools. ## What you can inspect - App state, tier, deployment and operation results. - App users and authentication settings. - Supported model data and owner controls. - Event deliveries, attempts and job history. - File metadata and the account object allowance. - Scoped metrics, logs and traces when their sources are available. Access follows current ownership and explicit grants. App-user/admin credentials do not become platform credentials. Internal operator access has a separate grant; ordinary customer or agent roles do not receive it. ## Credentials and actions The dashboard uses a native platform browser session. The CLI uses an expiring agent key created under [Agent credentials](https://dash.backend.fast/__bf/account/agents). Revoking a key affects that key; it does not automatically delete apps or users. Browser state-changing requests retain same-origin checks. Protected account responses must not become shared cache entries. Keep agent keys and app tokens out of URLs and screenshots. ## Telemetry limits The dashboard uses the current scoped telemetry API. Cached metrics are the default; the realtime option has separate behavior. Some sources can be delayed or unavailable. Missing counters mean unavailable, not zero usage. The platform's remaining telemetry qualification includes resource overhead, failure behavior and a native trace queue fsync issue. The dashboard is useful for development, but complete telemetry reliability and production HA are not current release claims. Read [status](https://docs.backend.fast/reference/status/) and [limits](https://docs.backend.fast/limits/). --- # Email and SMTP Canonical page: https://docs.backend.fast/email/ ## What email covers App auth supports verification and password recovery. Each app can use its own SMTP provider and verified sender domain. A shared sender processes bounded mail work; apps do not run a separate mail process or hold SMTP credentials. Platform account email and customer app email have separate configuration. General transactional email, marketing, custom arbitrary templates and a public mail-sending primitive are not current V1 promises. ## Set app SMTP Your platform agent key needs `write` scope: ```bash bfast smtp set --app my-counter \ --host smtp.resend.com --port 587 \ --username resend --from noreply@your-verified-domain.example bfast smtp status --app my-counter --json ``` Enter the provider's SMTP password or sending key at the hidden prompt. There is no password command argument. Automation can pipe a secret manager's output with `--password-stdin`. The dashboard Authentication page supplies the same settings. The Resend example requires an account, a verified sender domain and a sending key. Other supported SMTP providers can use their own host, port and credentials. Use the provider's TLS connection settings. The platform rejects unsafe internal destinations; app SMTP is not arbitrary outbound network access. Setting replaces the whole profile. Status returns configuration presence and mail counters, never the secret. Saving settings does not send a test email. ```bash bfast smtp clear --app my-counter ``` Clearing blocks new app email. Existing eligible users can still use password login and ordinary app requests during delivery failure. ## Test the flow Use a real inbox for public signup. Follow the verification link before login. For an owner-only test without email, use `bfast users create --verified` as described in the [quickstart](https://docs.backend.fast/quickstart/). The development sender is restricted to an authorized test inbox. Do not rely on it for your customers. Configure your own app SMTP for real registration and reset. SMTP acceptance means the provider accepted a message; it does not prove inbox delivery. --- # Events and jobs Canonical page: https://docs.backend.fast/events-and-jobs/ Use [Minidesk](https://docs.backend.fast/examples/) for complete executable declarations and functions. Events, schedules, receipts and business rows persist in the app database. One worker in the app process handles this work. There is no per-app broker. ## Events An emitting transaction writes the event and its handler deliveries together. A handler executes business writes in its own transaction. A failure rolls back those writes and records a bounded failed attempt. ```go // @on TicketCreated // @once key=e.ticket func NotifyTicketCreated(e TicketCreated) { database.notifications.create(Notification{ user: e.owner, title: "Ticket created", body: "Your ticket was created: " + e.title, }) } ``` This excerpt uses models and events from the complete Minidesk source. `@once` commits a receipt with successful local SQLite effects. Duplicate delivery skips those effects. It is not exactly-once delivery to an external service. The worker tries five times with delays of 1, 2, 4 and 8 seconds. Exhausted work stays failed. Restart recovers interrupted claims and retains attempt history. ```bash bfast events list --app my-desk bfast events get --app my-desk --id '' bfast events replay --app my-desk --id '' bfast events skip --app my-desk --id '' ``` Fix and update the app before replaying failed work. Replay preserves successful deliveries and once receipts. Owner changes do not retry automatically after a lost response; inspect history before another change. ## Jobs ```go // @job every 1d func CleanupOldReadNotifications() { database.notifications. where(read == true). where(createdAt < now() - 30d). delete() } ``` Hourly/daily schedules use UTC. Every-duration schedules retain phase in SQLite. Missed intervals produce one catch-up run. The same job cannot overlap itself. An interrupted invocation becomes explicit history; restart does not silently repeat that invocation. ```bash bfast jobs list --app my-desk bfast jobs run --app my-desk --name CleanupOldReadNotifications ``` A manual run preserves the next automatic schedule. A failed manual run returns a nonzero exit code. The dashboard also exposes work history and owner actions. ## Bounds | Work | Current bound | | --- | --- | | Pending/failed events | 1,000 | | Event payload | 64 KiB | | Completed events retained | 1,000 | | Finished delivery attempts retained | 5,000 | | Finished job runs retained | 1,000 | | Once receipts | 10,000; no automatic eviction | | Owner list/detail rows | 100 per list | The once ledger rejects additional distinct keys at capacity. These resource bounds need explicit retention design for larger workloads. An app administrator does not receive the platform owner's work-control authority. --- # Complete source examples Canonical page: https://docs.backend.fast/examples/ Each project needs one `backend.fast` file. These downloads derive from the committed example sources, with checksums in [source.json](https://docs.backend.fast/source.json). The examples use the supported compiler subset. Do not treat a short excerpt elsewhere as a complete project. ## Counter Models, authenticated writes, ownership, GET caching and event emission. ```bash mkdir -p my-counter curl -fsS https://docs.backend.fast/examples/simple-counter/backend.fast \ -o my-counter/backend.fast bfast deploy --name my-counter --tier small ./my-counter ``` [Read Counter source](https://docs.backend.fast/examples/simple-counter/backend.fast). The [quickstart](https://docs.backend.fast/quickstart/) supplies users, protected requests, update and deletion. The optional [Python client](https://docs.backend.fast/examples/simple-counter/client.py) prompts for the app password and keeps credentials in memory. ## URL Shortener Typed inputs, validated strings, query filters, update paths and app auth. ```bash mkdir -p my-links curl -fsS https://docs.backend.fast/examples/url-shortener/backend.fast \ -o my-links/backend.fast bfast deploy --name my-links --tier medium ./my-links ``` [Read Shortener source](https://docs.backend.fast/examples/url-shortener/backend.fast). After creating an app user, use `POST /links` with a slug, target URL and title. The `/r/:slug` route returns target data as JSON; it does not follow an HTTP redirect. ## Minidesk Tickets, comments, private attachments, event handlers, once receipts and a daily job. ```bash mkdir -p my-desk curl -fsS https://docs.backend.fast/examples/minidesk/backend.fast \ -o my-desk/backend.fast bfast deploy --name my-desk --tier small ./my-desk ``` [Read Minidesk source](https://docs.backend.fast/examples/minidesk/backend.fast). Use the generated [TypeScript client](https://docs.backend.fast/clients/) for File transfer. Inspect work through [events and jobs](https://docs.backend.fast/events-and-jobs/). Choose fresh deployment names. Keep each source's declared DSL app name unchanged when updating an existing app. Your display name and random hostname are separate. --- # Files and account storage Canonical page: https://docs.backend.fast/files/ ## Current storage model Fresh native apps use the `account-r2-v1` File backend. File bytes live in private object storage. App SQLite holds metadata, upload intent and business references. Apps and clients receive no bucket credential. Each platform account initially shares **10,000,000,000 bytes** across its apps. This is 10 GB in decimal units. Creating another app does not increase it. The allowance is separate from the app's database volume and from backup storage. ```bash bfast storage --json bfast files list --app my-desk ``` The dashboard shows the same account allowance and File metadata. The usage response distinguishes charged, ready and reserved bytes. Missing data is unavailable; it does not mean zero usage. ## Upload and save Use the generated client with a current app token. Minidesk accepts a File when creating a ticket: ```typescript const ticket = await client.createTicket({}, { title: 'A small attachment', description: 'Uploaded with the SDK', attachment: new File(['Hello'], 'note.txt', { type: 'text/plain' }), }); if (ticket.attachment) { const response = await client.downloadFile(ticket.attachment); console.log(await response.text()); } ``` `uploadFile(file)` returns a reusable File reference. `uploadFile(file, requestKey)` accepts an explicit retry key of 16–128 ASCII letters, digits, hyphens or underscores. After a lost response, reuse the same key, user, filename and bytes. The same upload preserves its File ID. Changed content with that key returns 409. An input can supply an existing File ID. The app reads canonical metadata and checks ownership; it does not trust caller-supplied size, hash or owner fields. An app administrator can access other users' files in that app. Another app or account gains no access from sharing the object allowance. ## Limits | Bound | Current value | | --- | --- | | One file | 2 MiB | | Account object bytes | 10,000,000,000 | | Concurrent transfer per app | 1 | | Unattached upload lifetime | 1 hour | An upload stays temporary until a business transaction or `storage.save` retains it. The worker cleans expired unattached files in bounded batches. An uncertain provider write remains charged until exact reconciliation; uncertainty does not produce a refund. Older apps can retain SQLite File storage. That profile has a 64 MiB aggregate limit and 1,000 files per app. Do not apply those aggregate limits to a fresh R2 app or silently migrate an existing profile. ## Retention Stopping or deleting an app retains saved files and their byte charge. Customer app deletion is not permanent object purge. There is no public automatic purge, old-generation cleanup or customer restore workflow yet. Running version-3 backups include independent File bytes and verify hashes. Isolated recovery preserves logical File IDs and writes into a fresh physical generation. Bucket durability alone is not a backup. Full-account capture duration and replacement-host recovery remain unqualified. An app database alone does not contain a complete R2 backup. --- # Build a backend. Keep the control. Canonical page: https://docs.backend.fast/ ## Start with a working example backend.fast generates a Go app from a `backend.fast` source file. Each new app runs inside a Kata VM. Its SQLite database persists on a dedicated volume. You manage the app through the `bfast` CLI and the [dashboard](https://dash.backend.fast). ```bash curl -fsS https://dash.backend.fast/install.sh | sh bfast version ``` Follow [installation](https://docs.backend.fast/installation/) to sign in. The [quickstart](https://docs.backend.fast/quickstart/) downloads a complete Counter example, creates an app user, and calls its API. You need no repository checkout. | You want to… | Start here | | --- | --- | | Let an agent create and update apps | [Agent guide](https://docs.backend.fast/agents/) | | Write models, routes and queries | [Language guide](https://docs.backend.fast/language/) | | Add app users and authentication | [App authentication](https://docs.backend.fast/authentication/) | | Upload private files | [Files and account storage](https://docs.backend.fast/files/) | | Use typed clients | [SDK and OpenAPI](https://docs.backend.fast/clients/) | | Check what works today | [Current feature status](https://docs.backend.fast/reference/status/) | ## Current release backend.fast is a development platform. The supported V1 subset includes checked models and routes, native app auth, events, jobs, private files and generated clients. The compiler rejects unsupported constructs. Read the feature status before designing a feature. This site does not promise full V1 support or high availability. Fresh apps use native auth and share a **10 GB object allowance per account**. Small and Medium are the currently qualified app tiers. Existing apps can retain older auth and File profiles. See [limits](https://docs.backend.fast/limits/). ## Read without a browser Agents can fetch [llms.txt](https://docs.backend.fast/llms.txt), [the complete Markdown](https://docs.backend.fast/llms-full.txt), or [AGENTS.md](https://docs.backend.fast/AGENTS.md). Every guide also has a raw Markdown URL. [Source metadata](https://docs.backend.fast/source.json) pins the feature matrix and example checksums. --- # Install and sign in Canonical page: https://docs.backend.fast/installation/ ## Install or update The same command installs the current CLI and updates an existing installation: ```bash curl -fsS https://dash.backend.fast/install.sh | sh bfast version ``` Supported machines are Linux x64, Mac Apple silicon and Mac Intel. The installer checks SHA256, checks that the binary runs, and replaces it atomically. It needs no sudo. It preserves your saved login. It updates a writable regular `bfast` on your PATH. Otherwise, it uses `$HOME/.local/bin`. Follow its printed PATH instruction if needed. ```bash curl -fsS https://dash.backend.fast/install.sh | sh -s -- --bin-dir "$HOME/.local/bin" export PATH="$HOME/.local/bin:$PATH" ``` To update a local `./bfast`, run this from its directory: ```bash curl -fsS https://dash.backend.fast/install.sh | sh -s -- --bin-dir "$PWD" ./bfast version ``` You can inspect the installer first: ```bash curl -fsS https://dash.backend.fast/install.sh -o install-bfast.sh less install-bfast.sh sh install-bfast.sh ``` The installer requires `curl` and `sha256sum` or `shasum`. Automatic update checks inside the CLI are not implemented. Run the installer again to update. ## Connect your platform account 1. Open the [dashboard](https://dash.backend.fast) and sign in with your verified account. 2. Open [Agent credentials](https://dash.backend.fast/__bf/account/agents). 3. Create a key with `read`, `write` and, when needed, `delete` permissions. Select an expiry. 4. Run `bfast login`. Enter the key at its hidden prompt. 5. Check the connection: ```bash bfast whoami --json bfast apps list --json ``` The dashboard shows a new key once. Give an agent the minimum scope it needs. Keep the key in a secret manager or the CLI's private configuration file. Do not put it in source, URLs or command arguments. For automation, pipe your secret manager's output to `bfast login --token-stdin`. Use `--config /absolute/private/path/cli.json` to select another private profile. An agent still needs the owner to create its initial account/key. ## Direct downloads | Machine | Binary | | --- | --- | | Linux x64 | [bfast-linux-amd64](https://dash.backend.fast/downloads/bfast-linux-amd64) | | Mac Apple silicon | [bfast-darwin-arm64](https://dash.backend.fast/downloads/bfast-darwin-arm64) | | Mac Intel | [bfast-darwin-amd64](https://dash.backend.fast/downloads/bfast-darwin-amd64) | | Checksums | [SHA256SUMS](https://dash.backend.fast/downloads/SHA256SUMS) | Continue with the [quickstart](https://docs.backend.fast/quickstart/). If login fails, read [troubleshooting](https://docs.backend.fast/troubleshooting/). --- # The backend.fast language Canonical page: https://docs.backend.fast/language/ ## One source file A project contains `backend.fast`. It declares one app, its models, input/output types, events and annotated functions. The compiler generates a Go HTTP server and a deployment image. It compiles checked bodies; it does not infer behavior from route names. Download a [complete checked example](https://docs.backend.fast/examples/) before writing a new project. The [feature matrix](https://docs.backend.fast/reference/status/) is the exact support record. A partial feature supports only the boundary in its notes. ## Models and inputs ```go app "simple-counter" model Counter { id ID name string @unique value int = 0 owner UserID @index updatedAt Time = now() } type CreateCounterInput struct { name string @min(1) @max(80) } ``` Every model needs an immutable, non-optional `ID`. Model `@unique` and `@index` create SQLite indexes. String/text `@min`, `@max` and `@enum` validate supported records. Lengths count Unicode code points. Numeric and array constraints remain unsupported. The compiler rejects invalid, duplicate and contradictory constraints. Supported shapes include selected scalar types, IDs, time/date/duration values, optional `T?` values, arrays, defaults and record literals. Broader expression and response lowering remains partial. Use the matrix for the exact boundary. ## Routes and functions ```go // @api POST /counters // @auth user // @cache invalidate ListCounters func CreateCounter(input CreateCounterInput) Counter { return database.counters.create(Counter{ name: input.name, owner: auth.user.id, value: 0, }) } ``` Annotations live in comments above a function. HTTP methods and paths must be unambiguous. System-reserved routes cannot be overridden. A function that reads `auth.user` needs a user-bearing auth rule. | Annotation | Purpose | | --- | --- | | `@api METHOD /path` | Expose a checked HTTP handler | | `@auth none`, `user`, `admin` | Select access rules | | `@auth user owns Model.field` | Enforce ownership | | `@cache 30s key=user,params` | Cache a supported GET response | | `@cache invalidate FunctionName` | Invalidate a declared GET cache after success | | `@on EventName` | Handle a durable event | | `@once key=e.field` | Deduplicate supported local event effects | | `@job hourly`, `daily`, `every 1d` | Schedule persisted app work | Only include `params` when applicable; the semantic checker requires it for cached routes that take API parameters. User-auth caches require `user`. Ownership routes reject TTL caching. ## Safety and unsupported work This language is not unrestricted Go. Arbitrary imports, package calls, filesystem/network access, goroutines, channels, `defer`, panic/recover, pointers, interfaces and reflection are outside the approved surface. Unsupported bodies fail before deployment. A Go-compatible shape alone does not make code supported. Use the supplied model, query, auth, File and background-work primitives. Do not embed a second web server or database driver. General external integrations and Apple login require additional product work. The portable CLI deploys through the remote compiler. The local development watcher is not implemented. Follow [models and queries](https://docs.backend.fast/models-and-queries/) and [the examples](https://docs.backend.fast/examples/) for currently executable programs. --- # Tiers and current limits Canonical page: https://docs.backend.fast/limits/ ## App resources | Tier | App CPU | App RAM | | --- | --- | --- | | Small | 130m, approximately 1/8 vCPU | 256 MiB | | Medium | 250m, 1/4 vCPU | 512 MiB | These are the currently qualified tiers. Kata/VM overhead stays separate. Each app uses one writable pod, Service and retained data volume. Additional writable replicas and high availability need a replication/fencing design. The current default app volume is 1 GiB. That physical capacity differs from usable payload. A prior snapshot fixture qualifies 896 MiB; it is not a blanket native-auth or full-workload capacity promise. Large native datasets and recovery still need separate qualification. ## Storage and auth | Resource | Current contract | | --- | --- | | Account object allowance | 10,000,000,000 bytes shared across apps | | One File | 2 MiB | | File transfer per app | 1 at a time | | Unattached File | 1-hour lifetime, then bounded cleanup | | Fresh native user count | No commercial app/owner count cap | | Fresh native global sessions | No small fixed count cap | | Native session lifetime | One hour absolute; refresh does not extend it | | Password work | One task per app with a bounded memory profile | | Auth operations | Separate budgets; retry 429 responses with delay | Removing count caps does not mean unlimited users or throughput. Database size, CPU, memory, cleanup, password concurrency and operation budgets still apply. Older explicit auth and SQLite File profiles retain their stored limits. Platform account registration also has a separate development quota. ## Build and operation bounds DSL input is limited to 256 KiB. Generated project output is bounded before writes. The platform admits a finite number of builds and operations; overloaded requests can fail explicitly. The default CLI mutation wait is fifteen minutes. Inspect the accepted operation after a timeout instead of assuming failure. Business requests and work histories also have payload/row bounds. Read [events/jobs](https://docs.backend.fast/events-and-jobs/) and the selected [OpenAPI contract](https://docs.backend.fast/clients/). ## Features that need more work Full V1 implementation, arbitrary packages/network access, general schema migration, Apple login, cross-app account linking, a managed CORS policy for unrelated browser origins, automatic product restore, permanent purge and replacement-host recovery are not current promises. The platform runs on a development node. A route working today does not establish a production uptime SLA, 100-app capacity, per-app disk fairness or full-account backup duration. Read the exact [feature matrix](https://docs.backend.fast/reference/status/). --- # Models, queries and caching Canonical page: https://docs.backend.fast/models-and-queries/ ## Model storage Each app has a private SQLite database on a retained volume. Generated model tables store checked JSON records and selected field indexes. User/session state shares this database in fresh native apps. File bytes use the separate account object backend; references stay with model data. New apps use the qualified WAL configuration and one writer. Normal update preserves compatible schemas. Arbitrary schema migration and writable replicas are not current promises. ## Create and read The Counter example creates a record with the current app user: ```go return database.counters.create(Counter{ name: input.name, owner: auth.user.id, value: 0, }) ``` Its list scopes rows to that same user: ```go return database.counters. where(owner == auth.user.id). order(updatedAt, desc). all() ``` The supported query layer includes checked scalar filters, ordering, limits, terminal reads and selected mutations. It normalizes selected time, date and duration values and preserves signed 64-bit integers. Read the full [status matrix](https://docs.backend.fast/reference/status/) before using broader query expressions. Unique conflicts return HTTP 409. Generated input validation rejects unsupported fields, invalid types, enums and constrained string lengths. Model and index names must not collide with system or generated schema names. ## Update with ownership ```go // @api POST /counters/:id/increment // @auth user owns Counter.owner // @cache invalidate ListCounters func IncrementCounter(id ID) Counter { counter := database.counters.get(id) counter.value = counter.value + 1 counter.updatedAt = now() updated := database.counters.update(counter) emit(CounterIncremented{ counter: updated.id, owner: updated.owner, value: updated.value, }) return updated } ``` This excerpt uses the `CounterIncremented` event declared in the [complete Counter source](https://docs.backend.fast/examples/simple-counter/backend.fast). The lowered function uses one SQLite transaction. Auth checks use the current user and role in that transaction. A client-selected owner header grants no access. ## Response caching The Counter list declares `@cache 30s key=user`. Cache keys stay inside the app. A successful mutation invalidates the declared target. Concurrent stale fills cannot replace the new generation. Restart clears the memory cache. Cache behavior is app-local. Distributed invalidation is not supported. Ownership routes reject TTL caching. Generated caches have memory limits; missing resource metrics do not prove zero usage. --- # Deploy your first app Canonical page: https://docs.backend.fast/quickstart/ Complete [installation and platform login](https://docs.backend.fast/installation/) first. This guide uses a test user with an owner verification attestation. It sends no email. ## 1. Download the source ```bash mkdir -p my-counter curl -fsS https://docs.backend.fast/examples/simple-counter/backend.fast \ -o my-counter/backend.fast ``` This is the complete checked Counter example. It defines a model, protected create/list/increment routes, caching and an event. [Read the source](https://docs.backend.fast/examples/simple-counter/backend.fast). ## 2. Deploy Choose a fresh display name. Deleted names cannot be reused. ```bash BF_APP="counter-$(date +%s)" bfast deploy --name "$BF_APP" --tier small ./my-counter bfast apps list bfast inspect --json "$BF_APP" ``` Creation waits for public HTTPS health. The CLI prints an operation ID. The same owned app appears in the [dashboard](https://dash.backend.fast). Its hostname uses two random words and six hex characters. Read its URL from `inspect`; the display name does not determine the URL. ## 3. Create an app user ```bash bfast users create --app "$BF_APP" \ --email tester@example.invalid --name "Test User" --verified bfast users list --app "$BF_APP" ``` Enter a new app password at the hidden prompt. Remember it for the next step. `--verified` records an owner attestation. Public signup instead requires email verification and app SMTP. Your platform login does not create an app user. ## 4. Call protected routes ```bash bfast request --app "$BF_APP" --email tester@example.invalid \ --method POST --path /counters --data '{"name":"visits"}' bfast request --app "$BF_APP" --email tester@example.invalid --path /counters ``` Each command prompts for the app password. It logs in, sends an app bearer token, performs the request and attempts logout. It keeps the session in memory. Copy the **counter record ID** from the response: ```bash BF_COUNTER_ID='' bfast request --app "$BF_APP" --email tester@example.invalid \ --method POST --path "/counters/$BF_COUNTER_ID/increment" ``` The value becomes `1`. An app ID, a user ID and a counter ID identify different things. ## 5. Update and check data Keep the DSL `app "simple-counter"` declaration unchanged. You can add a comment to exercise update without changing the model schema: ```bash printf '\n// Updated through the public CLI.\n' >> my-counter/backend.fast bfast update --app "$BF_APP" ./my-counter bfast request --app "$BF_APP" --email tester@example.invalid --path /counters ``` The app retains its ID, URL, user and counter value. Schema-changing migrations are not implied by normal update. Read [app lifecycle](https://docs.backend.fast/app-lifecycle/). ## 6. Download the client contract ```bash bfast sdk --app "$BF_APP" --out client.ts bfast openapi --app "$BF_APP" --out openapi.json bfast storage --json ``` The generated SDK uses app tokens. The account storage command uses the platform key. See [clients](https://docs.backend.fast/clients/) and [files](https://docs.backend.fast/files/). ## 7. Delete the test app ```bash bfast delete "$BF_APP" bfast apps list ``` Deletion removes the app from the active catalog. The result reports `retained_data: true`. Its volume and saved objects remain retained. This is not a permanent purge or a storage refund. See [retention](https://docs.backend.fast/files/#retention). --- # CLI command map Canonical page: https://docs.backend.fast/reference/cli/ Run `bfast help` for the installed command syntax. Put flags before positional arguments. Most reads support `--json`. The portable CLI uses HTTPS; operator-only node commands are not customer commands. | Purpose | Commands | | --- | --- | | Install/update | Run the public installer again | | Identity | `bfast version`, `bfast login`, `bfast whoami --json` | | Catalog | `bfast apps list`, `bfast inspect --json ` | | Create | `bfast deploy --name --tier small ` | | Update | `bfast update --app ` | | Delete | `bfast delete ` | | Operation | `bfast operations --json `, `bfast operations --wait ` | | Users | `bfast users create/list/get/verify/role/revoke-sessions/disable/enable/delete` | | Protected request | `bfast request --app --email --path ` | | SMTP | `bfast smtp set/status/clear --app ` | | Account object usage | `bfast storage --json` | | Files | `bfast files list --app ` | | Event work | `bfast events list/get/replay/skip --app ` | | Jobs | `bfast jobs list/run --app ` | | TypeScript client | `bfast sdk --app --out client.ts` | | API contract | `bfast openapi --app --out openapi.json` | Read scope controls inspection. Write scope controls deployment, update, users, SMTP and supported work changes. Delete permission controls app deletion. These permissions are distinct. The platform checks current ownership on every request. `bfast request` prompts for the app password and uses a separate app session. It does not forward the platform key to business routes. SMTP and user password commands use hidden prompts or bounded secret-manager pipes. Use [the lifecycle guide](https://docs.backend.fast/app-lifecycle/), [user guide](https://docs.backend.fast/users/) and [quickstart](https://docs.backend.fast/quickstart/) for complete commands. The portable CLI currently does not expose the operator's app restart or permanent volume-purge tools. --- # Current feature status Canonical page: https://docs.backend.fast/reference/status/ This release snapshot uses source commit `747f4289840955f8df4981fb00ec7765501c02aa`. Download [source metadata](https://docs.backend.fast/source.json). Runtime target: K3s/Kata on the development node; Kraft compatibility via Kraftplane Status: maintained with compiler and generated-runtime changes ## Summary backend.fast V1 is not fully implemented yet. The current implementation is a beta subset with checked compilation, generated Go/OCI builds for Kata, bounded runtime behavior and app observability. Kraft remains a compatibility path. Generated behavior includes compiled Go functions, model declarations, cache, transactional events, job schedules, bounded files, native auth, and telemetry. Requests call generated functions rather than interpreting body operations. The compiler uses checked SQL helpers and source declarations. It does not infer behavior from route names. Vercel serves the dashboard; Kraftplane owns its scoped APIs and app control. `validate`, `generate`, `build`, `sdk`, and `deploy` require executable runtime support. They reject unsupported bodies and helper functions before writing artifacts. Checked handlers, jobs, and File values execute in Minidesk through normal CLI/Kata/browser tooling. The milestones 4–5 report records public SDK, owner controls, recovery, backup, and Small workload acceptance. `kraftplane bfast dev` reports that its watch/run workflow is not implemented. The local compiler `sdk` command writes the client file. Portable `bfast sdk` and `bfast openapi` download contracts from the selected owned deployment. November 16 BF-160 activates `local-v1` for fresh native app auth. This profile removes commercial stored-user and global session caps. Separate operation budgets, password concurrency, disk headroom and bounded cleanup remain. Public checks pass with 21 users and more than 32 sessions; source recovery tests cover 1,500 users and 65 sessions. Existing profiles remain explicit. Read the live deployment report. Legend: - Done: supported in parser/semantic/codegen/runtime. - Partial: represented or checked, but runtime/codegen behavior is incomplete. - Missing: not implemented beyond possibly being documented. M1 permits a feature to reject compilation with a repair-oriented diagnostic. A `Partial` row therefore needs its supported/rejected boundary; it does not automatically require complete V1 implementation before M1. The M1 review does not change language behavior or promote partial rows without evidence. ## DSL Surface | Feature | Status | Notes | | --- | --- | --- | | `app "name"` | Done | Exactly one app is required. | | `model Name { ... }` | Partial | Parsed and generates a SQLite table. Each model requires an immutable non-optional ID. Generated runtime still uses JSON-backed rows. | | `type Name struct { ... }` | Partial | Parsed and emitted as Go struct; selected CRUD routes validate JSON body fields, types, optional values, and defaults, but full response lowering is incomplete. | | `event Name { ... }` | Partial | Typed emission and generated handlers execute transactionally. General body expressions remain limited below. | | Annotated `func` | Partial | Parsed and checked; full body lowering is missing. | | Basic types | Partial | Parser and semantic support exists for V1 basic types. Selected query storage normalizes `Time`, `Date`, and `Duration`; broader runtime storage remains incomplete. | | Optional `T?` | Partial | Type/default validation and selected guarded CRUD writes exist; broader runtime behavior remains limited. | | Arrays `[]T` | Partial | Parsed and checked; selected CRUD array literals and typed JSON body arrays run, but broader array behavior remains limited. | | Defaults | Partial | Selected scalar, empty-array, `nil`, and `now()` defaults are type-checked and applied to JSON body records and model creates. | | Field annotations | Partial | `@index` and `@unique` generate model indexes. String/text `@min` and `@max` enforce inclusive Unicode code-point lengths; `@enum` enforces exact string membership. Checks apply to nested records, defaults, CRUD, events, and responses. Unsupported constraint types, duplicate constraints, contradictory bounds, and invalid defaults reject compilation. Numeric and array constraints remain unsupported. | ## Function Annotations | Feature | Status | Notes | | --- | --- | --- | | `@api METHOD /path` | Partial | Method/path validation rejects malformed, overlapping, system-reserved routes. Checked CRUD/query bodies compile into direct Go functions. Other bodies reject compilation with a repair diagnostic. | | `@auth none/user/admin` | Partial | Caller user/role headers grant no authority. Protected routes fail closed without trust configuration. Fresh owned apps select embedded auth after BF-151 public CLI and dashboard checks. Authboss/SCS use the app SQLite database; the business transaction checks current local users and roles. The gateway signs a separate routing proof and verifies app TLS. Existing shared apps retain current-session gateway checks. Owner-scoped user administration and authenticated CLI requests pass for public Counter and URL Shortener apps. BF-152 adds complete offline native recovery, public verification/reset pages, and measured Counter/Shortener qualification on both Small and Medium at 40 mixed requests/s. Independent R2 download and isolated native recovery now pass under BF-154/BF-155. Physical reboot, replacement-host recovery, larger native payloads and broader V1 acceptance remain open. This does not close the remaining BF-133 or BF-145 gates. A body that reads `auth.user` requires a user-bearing auth rule. | | `@auth user owns Model.field` | Partial | Ownership field validation exists. The new runtime scopes same-model reads and writes to verified user context inside the transaction. Counter, URL Shortener, and query/ownership fixtures pass. BF-151 adds public native checks for same-app ownership, role changes, revocation, and data isolation. Broader V1 acceptance remains open. | | `@cache 30s` | Partial | GET-only semantic validation and generated bounded in-memory response cache; `BACKEND_FAST_CACHE_MAX_BYTES` or `BACKEND_FAST_CACHE_MAX_MIB` sets its per-app capacity (64 MiB default), and `d` and `w` V1 duration suffixes are normalized at runtime. | | `@cache 30s key=user,params` | Partial | GET-only validation requires `params` for any API parameter and `user` for user-auth routes. Ownership routes reject TTL caching. Deterministic keys run in the app microVM, and cache contents clear on app restart. | | `@cache invalidate ...` | Partial | Strict target syntax and successful-mutation generation replacement discard stale concurrent fills. One token per declared target stays outside the evictable response store. | | `@on EventName` | Partial | Checked handlers compile into Go. The generated Minidesk race fixture verifies transactional delivery and failure behavior. Minidesk passes public requests and owner CLI/dashboard checks. | | `@once key=...` | Partial | A scalar event field supplies the key. Business effects and the durable receipt commit together. Duplicate and replay tests pass; the ledger stops at 10,000 keys rather than evicting receipts. | | `@job hourly/daily/every Duration` | Partial | Generated jobs persist schedules and run history. UTC hourly/daily and duration schedules pass due, concurrent-claim, restart, and missed-interval tests. Bounded history, normal restart/redeploy, automatic runs, and owner CLI/dashboard controls pass live Minidesk checks. | ## Function Body Safety | Feature | Status | Notes | | --- | --- | --- | | Go-compatible block extraction | Done | Bodies are parsed with Go parser after duration literal normalization. | | Restricted AST validation | Partial | Goroutines, channels, defer, pointers, interfaces, arbitrary package calls, and unsupported stdlib roots are rejected. | | `storage.save(...)` type check | Partial | Checked File values compile. `storage.save` verifies an uploaded reference and canonicalizes its metadata in the business transaction. Ownership and SQLite backup/restore tests pass. Strict SDK checks, public file transfers, restart/redeploy readback, and verified snapshot coverage pass. | | `emit(Event{...})` validation | Partial | Selected lowered routes check event fields and write typed pending outbox rows; general event expressions remain incomplete. | | Database collection validation | Partial | `database.` must map to a declared model collection; selected query fields, comparisons, order, limits, terminals, return shapes, create values, field writes, and direct CRUD calls are checked. | | Full body lowering | Partial | Checked CRUD/query, event, job, and storage bodies compile into Go statements. The request path no longer interprets body plans. General branches, helpers, loops, and other expressions remain explicitly rejected. Minidesk passes generated race tests and normal CLI/Kata/dashboard acceptance. | ## Generated Runtime | Feature | Status | Notes | | --- | --- | --- | | Go HTTP server | Partial | Generated and compiled for beta examples. | | Kraft packaging | Partial | Kraftfile/Dockerfile/rootfs are generated and deployable. | | SQLite model storage | Partial | JSON-backed model tables and selected field indexes. Generated schema names reject system, keyword, case-folded, table, and index collisions. Unique conflicts return `409`. Startup validates model rows and normalizes legacy typed values in one transaction. New configured Kata apps persist WAL/FULL/NORMAL. Legacy explicit profiles retain their settings. MEMORY journaling does not provide crash-safe transactions. | | Running database backup | Partial | New Kata apps persist WAL/FULL/NORMAL and backup enabled. The installed schedule uses private `--bf-backup-reserve` with an owned LVM snapshot and host WAL preparation. Small/Medium checks pass with 896 MiB of payload at 40 mixed requests/s. Actual scheduling, encrypted restore, interrupted-worker retry, deletion cleanup, and paired activation pass. Explicit logical export remains qualified at 64 MiB and 2 MiB/s. Unsupported images fail without fallback. Verified R2 app/control copies and isolated downloaded-app readback pass under BF-154/BF-155. Replacement-host recovery and automatic product restore remain open in BF-132. No public endpoint or sidecar is added. | | Typed database/query layer | Partial | Generated CRUD/query plans support scalar filters, order, limit, terminals, filtered delete, source-position filter snapshots, stable guarded writes, exact 64-bit integers, arrays, string joins, fixed-width UTC times, and normalized signed duration values. Each lowered function uses one SQLite transaction. Storage remains JSON-backed. | | Event outbox | Done | Declared emission atomically writes the event and its handler deliveries. Generated Go handlers use bounded retries and atomic once receipts. Generated race and live checks cover duplicates, rollback, exhaustion, replay/skip, owner controls, and retained state. Interrupted-claim tests also pass. | | Jobs | Done | Persisted app-local schedules and transactional execution pass generated Minidesk race tests. One worker coalesces missed intervals. Normal restart/redeploy, bounded history, automatic runs, and owner controls pass live acceptance. | | Cache | Partial | GET TTL response caching, declared mutation invalidation, generated configurable in-memory LRU capacity (64 MiB default), Prometheus-compatible cache metrics, bounded JSON diagnostics, and tenant-scoped retained dashboard counters are generated; distributed/shared invalidation is missing. | | File storage | Done | Authenticated multipart upload and app-local SQLite BLOB persistence pass generated ownership, size, canonical metadata, cleanup, and backup/restore tests. Limits are 2 MiB/file, 64 MiB and 1,000 files/app. Strict SDK checks, public file transfers, restart/redeploy readback, and verified snapshot coverage pass. | | Account object storage | Partial | Fresh native Kata apps now use private R2 File routes, canonical SQLite metadata, durable upload keys, verified expired-upload cleanup and a shared 10,000,000,000-byte account allowance. The 2 MiB transfer bound remains. Public CLI and Vercel dashboard usage views pass. A version-3 scheduled archive restores exact object bytes after source deletion. Existing apps retain their SQLite backend. Full-account backup duration, automatic customer restore and permanent purge remain open. See the operator procedure. | | OpenAPI | Done | Checked routes now distinguish input/output records, constant/dynamic defaults, optional fields, enums, int64, opaque app bearer tokens, error envelopes, void responses, and managed File endpoints. Contract fixtures and paired public SDK/browser download checks pass. Hashes pin downloads to the selected deployment. | | TypeScript SDK | Done | Strict TypeScript checks pass for Counter, Shortener, and Minidesk. Input shapes preserve omission/default rules; output fields remain present. The client supports enums, exact bigint JSON, typed HTTP errors, opaque bearer tokens, standard File uploads, references, and downloads. Shared record descriptors stay linear. Node execution and downloaded-client public HTTPS acceptance pass on Kata. Native cross-origin browser policy remains unchanged. See the SDK contract. | | Cross-origin browser SDK | Missing | Node SDK use and the registered app origin are qualified. Browser frontends on other origins need a separate registered-origin/CORS design; no wildcard policy is implied. | | `/healthz` | Done | Generated apps expose health. | | `/__bf/metrics.json` | Partial | App-level route metrics plus bounded in-memory cache snapshots exist. | | `/__bf/metrics.prometheus` | Partial | Native request/status counters, classic duration histograms, admission, process/guest cgroup, SQLite transaction, cache counters, and cache gauges are generated. Missing source fields stay absent. BF-116 adds verified Kata host/PVC measurements and the authenticated default UI. Pressure and overhead qualification remain open. | | Native telemetry delivery | Partial | Generated apps emit bounded structured stdout and optional sampled OTLP traces. Request handlers no longer emit duplicate blocking text logs. The private receiver checks pod credentials and assigns identity. New generated apps omit the duplicate trace buffer and the retired records endpoint. Full failure, cost, and scale qualification remain open in BF-116. | | `/__bf/metrics/current.json` | Partial | Bounded current diagnostic snapshot includes safe cache definitions, counters, and bounds without cache keys, values, responses, or local history. | | `/__bf/test` | Partial | Kraftplane redirects this path to the authenticated telemetry dashboard. The November 8 paired release denies public raw snapshots and requires a separate platform-reader assertion at their generated handlers. The scoped Data API retains model snapshots after a current `data:read` grant check. Native owner work controls now cover event deliveries, job history/actions, and file metadata. They use separate current-owner authority rather than Data API grants. | ## Status Use Operational input limits apply before compilation: `backend.fast` files must be regular files of at most 256 KiB. Project generation rejects output above 2 MiB or 64 files before writing generated files. These limits do not change supported V1 semantics. Configured Kata deploy/redeploy runs parsing and generation inside the bounded compiler Job. The generated-source compatibility archive retains a separate 512 KiB/64-file limit; see bounded builds. New configured DSL images preserve the exact submitted `backend.fast` alongside generated files. Its separate 256 KiB allowance does not increase generated output limits. Build acceptance checks byte equality. Existing backups remain readable without this file; the change does not add DSL language support. This matrix records feature support; it does not prioritize work. The M1 release order is in `docs/roadmap/m1.md`, and the implementation details for the current slice belong in its linked ExecPlan. --- # Troubleshooting Canonical page: https://docs.backend.fast/troubleshooting/ ## First checks ```bash bfast version bfast whoami --json bfast apps list --json bfast inspect --json '' ``` Update with the [installer](https://docs.backend.fast/installation/) before testing a newer API contract. Put flags before positional arguments. Record the operation ID and error body. Keep credentials out of reports. | Result | Next check | | --- | --- | | Platform request returns 401 | Check the selected CLI profile, key expiry and revocation. | | Management returns 403/404 | Check ownership and `read`/`write`/`delete` scope. | | App request returns 401 | Use an app token, not a platform key; check login and expiry. | | App login returns 401/403 | Check the app user, password, enabled state and verification. | | App route returns 403 | Check current role and model/File ownership. | | Signup cannot send mail | Check app SMTP, verified sender and delivery counters. | | Auth returns 429 | Wait before retry. Do not weaken the operation budget. | | File upload returns 409 | Reuse a request key only with identical user, filename and bytes. | | File upload rejects size/capacity | Check the 2 MiB transfer bound and account charged bytes. | | Deleted URL returns 410 | Deletion completed. Retained data does not imply a running route. | | App is starting or stopped | Inspect lifecycle state and the accepted operation. | | Native browser fetch fails cross-origin | Use a server client or registered app origin; wildcard CORS is not supplied. | | SDK integer fails JSON conversion | Use the generated client's bigint encoder and `toString()` for display. | | Missing metric | Treat it as unavailable. It is not proof of zero usage. | ## Lost operation response ```bash bfast operations --json '' bfast operations --wait '' ``` A lost client reply can leave accepted work running. Reuse the pending request instead of creating a second mutation. Use `--new-request` only after reconciling the earlier operation. Work actions have their own retry rules; inspect their history. ## Compilation and update Read source-position diagnostics. The language supports a checked subset; Go-shaped code can still be unsupported. Compare your source with a complete [downloadable example](https://docs.backend.fast/examples/) and the [feature matrix](https://docs.backend.fast/reference/status/). Do not rename the DSL app or assume a schema migration during ordinary update. ## Report an issue Include CLI version, app ID, operation ID, approximate UTC time, expected behavior, HTTP status and safe error text. Include the smallest source example that reproduces the problem. Exclude keys, tokens, passwords, cookies, email links and private data. --- # Manage app users Canonical page: https://docs.backend.fast/users/ These commands manage users inside an owned app. They use your platform key. Protected business requests use a separate app session. User roles apply only to the selected app. ## Create and list ```bash bfast users create --app my-counter --email tester@example.invalid \ --name "Test User" --verified bfast users list --app my-counter --limit 10 --offset 0 bfast users get --app my-counter --user '' ``` Creation prompts for an app password of 12 to 128 bytes. The `--verified` flag records your owner attestation and sends no mail. Without that flag, the user is unverified and cannot log in until verification succeeds. ```bash bfast users verify --app my-counter --user '' ``` Use immutable IDs in later commands. Equal emails in different apps do not share an identity. Paginate long lists; inspect truncation indicators instead of assuming one response contains every user. ## Roles and session revocation ```bash bfast users role --app my-counter --user '' --role admin bfast users revoke-sessions --app my-counter --user '' ``` Role changes revoke applicable sessions. The `admin` role applies inside the app; it grants no platform, operator-console or other-app access. ## Disable or delete ```bash bfast users disable --app my-counter --user '' bfast users enable --app my-counter --user '' bfast users delete --app my-counter --user '' ``` These actions change access and revoke sessions as applicable. User deletion does not imply a cascade through every business model row or saved File. Design your application's data retention explicitly. Read scope permits inspection. Write scope permits changes, including user deletion. App-delete permission alone does not grant user or SMTP changes. Run `bfast help` for the current command list.