Run vastframe locally
The same Hub, Edge, console, SDK and integration code that runs in the cloud also runs on a laptop with local drivers: Docker for containers, Azurite for blob storage, Caddy and *.apps.localhost for DNS, and a mock identity provider with a fixture organization. You need no Azure account.
Prerequisites
| Requirement | Notes |
|---|---|
| Docker Desktop with Compose v2 | Runs Postgres, the Hub, the Edge, the app containers and the stand-ins |
| Node 24 or newer | Node runs the TypeScript sources directly; there is no build step |
| Free ports | 80 (Edge), 4780 (Hub API), 8090 (mock sign-in), and for the integration stand-ins 8096 (Salesforce consent page), 8097 (Teams), 8098 (Graph mailbox) |
Change the ports with TC_EDGE_PORT, TC_API_PORT, TC_IDP_PORT, TC_SF_PORT, TC_TEAMS_PORT and TC_GRAPH_PORT.
Start the stack
npm install
npm run stack:up # Postgres, hub-api, hub-worker, Edge + console, edge-auth, mock IdP, stand-ins
open http://console.apps.localhost # sign in by picking a fixture user
Chrome, Firefox and curl resolve *.localhost to 127.0.0.1. Elsewhere, send the host header yourself: curl -H "Host: x.apps.localhost" http://localhost.
Stop it with npm run stack:down (this also removes app containers). Add -- --volumes to wipe all data.
Deploy something
npm run tc -- login --dev # saves ~/.config/tc/config.json with the dev token
npm run tc -- deploy examples/vite-react
# Live: http://vite-react.apps.localhost
# Preview: http://vite-react--<id>.apps.localhost
npm run tc -- logs -p vite-react
npm run tc -- ls
npm run tc -- rollback -p vite-react
The fixture organization
Sign-in goes through a local stand-in for Microsoft Entra ID that shows a "Sign in to Contoso" page listing a fixture organization of 43 people and 12 groups with real reporting lines. Tokens carry Entra-style claims. Useful people:
| Who | Why |
|---|---|
ben.carter@contoso.com | FP&A analyst in Finance; reports up a four-level manager chain |
megan.bowen@contoso.com, diego.ramos@contoso.com | Members of "Support Leads" |
alex.wilber@contoso.com | A support agent in "Customer Support", not a lead |
adele.vance@contoso.com, raj.patel@contoso.com | Members of "IT Admins", so Org Admin |
priya.raman@contoso.com | Delegated Admin for Finance (seeded on a fresh install) |
grady.archie@contoso.com | Auditor (seeded) |
carl.jensen@contoso.com | A disabled account: denied everywhere |
Act as someone from the CLI with npm run tc -- login --dev --as ben.carter@contoso.com, or from the API with Authorization: Bearer dev-token:ben.carter@contoso.com.
Local stand-ins
These run only on the local stack, for testing; they are never shipped.
| Stand-in | What it simulates | Where |
|---|---|---|
| Mock identity provider | Microsoft Entra ID sign-in with the fixture org | http://localhost:8090 |
| Mock Graph | SharePoint files and Excel workbooks with per-file permissions, SharePoint lists, Sites.Selected, and a mailbox that catches mail sent by apps | mailbox: http://localhost:8098/_dev/mailbox |
| Mock Salesforce | OAuth consent with a user picker, SOQL queries over fixture accounts, cases, opportunities and contacts with per-user visibility | http://localhost:8096 |
| Mock Teams | Records the bot's messages and renders Adaptive Cards per recipient; card buttons call back to the Hub | http://localhost:8097 |
| ERP database | A Postgres database standing in for an on-prem SQL Server, with an accounts-receivable schema | internal only |
| Mailpit | Catches sign-in link emails for organizations that use email links | http://localhost:8099 |
| Mock WorkOS | SSO "sign in as" page, the Admin Portal and a sample directory | http://localhost:8095 |
The stand-ins keep their state in memory. A restart forgets Teams messages, mail and Graph permissions; approve a request again to re-provision it.
Connect Claude Code to the local MCP server
claude mcp add --transport http vastframe http://localhost:4780/mcp \
--header "Authorization: Bearer dev-token"
Then ask Claude to "deploy this folder to vastframe". The Edge also routes http://mcp.apps.localhost/mcp to the same endpoint.
Try a SaaS organization locally
The default tenant (Contoso) lives at *.apps.localhost. Additional tenants live at *.<slug>.vf.localhost. With a tenant such as acme created, open http://console.acme.vf.localhost, enter the admin's email, and click the sign-in link in Mailpit. Point the CLI at a tenant with TC_TENANT=acme. See Multi-tenancy and isolation.
Running several stacks side by side
Set COMPOSE_PROJECT_NAME, TC_APPS_NETWORK and the port variables, and pass the same environment to stack:down. All stacks on *.apps.localhost share the session cookie (cookies ignore ports), so signing in on one stack can sign you in or out on another.