Key concepts
This page defines the terms used across the docs. The glossary has a short alphabetical list.
The model at a glance
Organization (a tenant)
└── Project the unit people think in: "Q3 variance dashboard"
├── Services one web | api | static service, plus any number of cron and worker services
├── Deployments immutable; each has its own preview URL; one serves production
├── Database one Postgres database per project
├── Storage buckets of files
├── Access who can open the app, plus app roles
├── Grants integration scopes this project may use
├── Env & secrets variables injected at container start
└── Owner a person; also decides where the project sits in the org tree
Organization (tenant)
An organization, also called a tenant, is one company's space in vastframe. It has its own people and groups, sign-in method, projects, policies and audit log.
- On vastframe cloud (SaaS) many organizations share one installation. Each organization gets its own domain, for example
acme.vastframe.app, which givesconsole.acme…,auth.acme…and<app>.acme…. Isolation is enforced by Postgres row-level security; see Multi-tenancy and isolation. - A self-hosted installation in your own Azure has exactly one organization, the
defaulttenant, on your own domain such asapps.contoso.com.
Project
A project is what Vercel or Supabase call a project: a frontend, an API and a database together are one project, not three apps. Each project has:
- a name that becomes its address:
q3-variance.apps.contoso.com. Names are 3 to 40 characters: lowercase letters, digits and dashes, starting with a letter.--is not allowed because it separates preview and service names, and a few names (api,mcp,console,www,admin,auth,edge,hub) are reserved. - an owner, the person accountable for it. The owner's position in the org chart is the project's position in IT's views.
- an expiry: projects nobody opens for 60 days are nudged and then archived 30 days later. See Project settings.
Service
A project runs one primary service plus optional background services:
| Type | What it is |
|---|---|
static | Files served directly by the Edge. No container, no cold start. Most AI-built dashboards land here. |
web / api | A container listening on $PORT (8080 by default), fronted by the Edge. |
cron | A container started on a schedule (five-field cron, UTC), for syncs, snapshots and reports. |
worker | A long-running container with no inbound traffic. |
See Runtimes and detection and Cron and worker services.
Deployment
A deployment is one immutable build of a project's source. Every deployment gets its own preview URL (q3-variance--d7f3a2.apps.contoso.com). One deployment is production. Promoting a deployment switches production to it instantly; rolling back promotes an older one. See Preview URLs and rollback.
The Edge
The Edge sits in front of every app, preview and the console. It:
- signs people in once for all apps (single sign-on through your identity provider),
- checks that the person may open this project,
- forwards a short-lived signed identity token to the app in the
X-TC-Userheader, and - serves the platform endpoints under
/_tc/*on every app's own origin:/_tc/auth/*,/_tc/db/*(the Data API),/_tc/storage/*and/_tc/int/<integration>/*(the Integration Gateway).
Because the platform lives on the app's own origin, browser code needs no API keys and no URLs: it calls /_tc/... on the page it was served from.
The Hub
The Hub is the control plane: the API behind the console, CLI and MCP server (hub-api), the background workers that build, deploy and reconcile (hub-worker), and the Hub database holding projects, deployments, grants, requests, the org mirror, costs and the audit log. The API people reach has no cloud-resource permissions of its own; only the worker changes infrastructure.
Integrations
An integration is a business system that IT has connected once in Admin › Integrations, such as Microsoft 365 (Graph), Teams, Salesforce or an on-prem ERP database. Each has a connection mode:
| Mode | Example | Whose permissions apply |
|---|---|---|
| Delegated OAuth per user | Salesforce | The signed-in person's: they see what the vendor lets them see |
| Microsoft Graph | SharePoint, Excel, OneDrive, Outlook | The signed-in person's, or the project's own identity for jobs (per site or file) |
| Org credential | ERP / SQL Server | An admin-held read-only connection, granted per project by table |
| Platform bot | Teams | vastframe's bot, scoped to recipients |
Apps reach integrations only through the Integration Gateway, which checks grants, adds credentials and audits every call. See Integrations.
Grants and access requests
A grant says "project X may use these scopes of integration Y", for example Salesforce Case:read. Grants come from:
- policies that auto-approve common, low-risk needs (reading your own files in Microsoft 365, Salesforce read for the Sales department), or
- access requests that a person approves.
vastframe finds what an app needs from its tc.json and from a scan of its code at deploy time, and from the first ungranted call at runtime. Anything not covered by a policy becomes an access request with the requester, their manager, the purpose, the exact scopes and the code lines that use them. Approvers act in the console's Requests inbox or on a Teams card: Approve, Approve narrower, Deny with reason, or Ask a question. Approval takes effect immediately, with no redeploy. Until then the app is live and the ungranted calls answer ACCESS_PENDING.
Access and app roles
Separate from integrations, access decides who can open an app: Only me (the default), My team, My department, Specific people and groups, or Everyone in the org. App roles (such as viewer, editor, approver, developer, or your own) are assigned to people or groups and arrive in the identity token, in /_tc/auth/me and in SQL as tc.has_role('approver'). See Access & security.
Hub roles
Hub roles decide what someone can do in vastframe itself: Org Admin, Delegated Admin (scoped to a department or a manager's subtree), Auditor (read-only everything), Builder (may create projects) and Approver (reviews requests for an integration). Within a project, the owner and people with the developer app role manage it. See Access & security.