Skip to main content

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​

RequirementNotes
Docker Desktop with Compose v2Runs Postgres, the Hub, the Edge, the app containers and the stand-ins
Node 24 or newerNode runs the TypeScript sources directly; there is no build step
Free ports80 (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:

WhoWhy
ben.carter@contoso.comFP&A analyst in Finance; reports up a four-level manager chain
megan.bowen@contoso.com, diego.ramos@contoso.comMembers of "Support Leads"
alex.wilber@contoso.comA support agent in "Customer Support", not a lead
adele.vance@contoso.com, raj.patel@contoso.comMembers of "IT Admins", so Org Admin
priya.raman@contoso.comDelegated Admin for Finance (seeded on a fresh install)
grady.archie@contoso.comAuditor (seeded)
carl.jensen@contoso.comA 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-inWhat it simulatesWhere
Mock identity providerMicrosoft Entra ID sign-in with the fixture orghttp://localhost:8090
Mock GraphSharePoint files and Excel workbooks with per-file permissions, SharePoint lists, Sites.Selected, and a mailbox that catches mail sent by appsmailbox: http://localhost:8098/_dev/mailbox
Mock SalesforceOAuth consent with a user picker, SOQL queries over fixture accounts, cases, opportunities and contacts with per-user visibilityhttp://localhost:8096
Mock TeamsRecords the bot's messages and renders Adaptive Cards per recipient; card buttons call back to the Hubhttp://localhost:8097
ERP databaseA Postgres database standing in for an on-prem SQL Server, with an accounts-receivable schemainternal only
MailpitCatches sign-in link emails for organizations that use email linkshttp://localhost:8099
Mock WorkOSSSO "sign in as" page, the Admin Portal and a sample directoryhttp://localhost:8095
note

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.

Was this page helpful?