Skip to main content

Overview

What is Facilio Vibe?#

Facilio Vibe is Facilio's app platform for shipping fully custom web apps to a managed subdomain like https://<linkName>.vibe.facilio.com. You author a static web app in any language or framework (React, Vue, Svelte, Solid, plain HTML — your choice), integrate Facilio APIs via the @facilio/vibe-sdk, and ship it to a live URL with the @facilio/cli — the unified Facilio CLI whose Vibe commands live under the facilio vibe … namespace.

Unlike Connected Apps, which embed widgets inside the Facilio UI through an iframe/webview, Vibe apps are standalone web apps hosted on their own subdomain. They use browser-cookie auth gated by the SDK and call Facilio data through schema-discoverable actions exposed by the Facilio MCP server.

When to use Vibe vs Connected Apps#

Use Vibe when…Use Connected Apps when…
You need a standalone tool on its own URL (dashboards, portals, public-facing apps)You need a widget embedded inside Facilio (record summary tab, custom form, dialer)
You want full control over the framework, bundler, and routingYou want platform-managed UI lifecycle (events, navigation, dialog placement)
The audience is broader than Facilio users (vendors, tenants, public links)The audience is signed-in Facilio users working inside a module
AI agents need to build and ship the app end-to-end with no manual UI registrationThe app needs to read Facilio context (current record, current form, current user) directly

Use cases#

  • Custom dashboards — KPI views, asset summaries, vendor scorecards on a sharable URL
  • Internal tools — one-off forms, bulk editors, data-quality utilities for ops teams
  • Customer / tenant portals — branded micro-sites that talk to Facilio data through the SDK
  • AI-generated apps — point an agent at a goal ("build me a workorder triage screen") and let it scaffold, build, and deploy without human intervention beyond a single OAuth approval
  • Rapid prototypes — ship a working URL in minutes without provisioning hosting or worrying about CORS, auth, or session cookies

How it works#

┌──────────────────────────────────────────────┐│        https://<linkName>.vibe.facilio.com   ││                                              ││  ┌──────────────┐    ┌────────────────────┐  ││  │ Your static  │◄──►│  @facilio/vibe-sdk │  ││  │     app      │    │  (browser cookie)  │  ││  └──────────────┘    └─────────┬──────────┘  ││                                │             ││                       executeAction(         ││                         connectionSlug,      ││                         actionSlug, payload) ││                                │             │└────────────────────────────────┼─────────────┘                                 ▼                ┌────────────────────────────────┐                │  Facilio Connections / MCP     │                │  (https://mcp.facilio.com/mcp) │                │  — connection + action catalog │                └────────────────────────────────┘
  1. Author your app in any framework. The only constraint is that the build output folder contains an index.html at its root.
  2. Authenticate once on your machine with facilio login (OAuth device flow — one click in the browser).
  3. Create the app with facilio vibe app create — prompts for a name, then writes vibe.json with the assigned linkName.
  4. Build and deploy with your normal build command, then facilio vibe deploy. The CLI zips the publish folder, uploads it, and prints the live URL.
  5. At runtime, the SDK handles browser-cookie auth and exposes executeAction(connectionSlug, actionSlug, payload) as the only sanctioned way to talk to Facilio data. Slugs and payload shapes come from the MCP catalog.

The agent-friendly workflow#

Vibe is designed so an AI agent can take a fresh machine from zero to a live URL with exactly one human action: clicking "Approve" in the browser during facilio login. Everything else — installing Node, scaffolding the project, writing the source, building, creating the app, deploying, iterating — is fully automatic.

# Agent-driven sequence (no further user input needed after facilio login)facilio login                       # one-time; user clicks "Approve" oncefacilio vibe app create             # one-time; prompts for a namenpm run build                       # or any build command for your frameworkfacilio vibe deploy                 # zips, uploads, publishes, prints live URL

See Building with AI Agents for the full agent recipe and the llms.txt reference you can hand to Claude, ChatGPT, or Cursor.

CLI quick reference#

CommandPurpose
facilio loginOAuth device-flow login. Run once per machine.
facilio vibe app createCreate a new app (prompts for a name). Writes vibe.json with the assigned linkName. Run once per app.
facilio vibe app listList all apps in the org (linkName, name, URL, status, last-published timestamp).
facilio vibe deployZip the build.publish folder, upload, publish. Prints the live URL and the immutable versioned URL.
facilio whoamiPrint the email and server of the active session.
facilio logoutRemove the stored token.
facilio vibe db create / import / tables / describeProvision and manage the app's own database (schema, tables from CSV).
facilio vibe function create / build / run / list / …Author, build, and run app-scoped server-side functions.

See the CLI Reference for flags, env vars, and the full command surface — including databases and functions.

SDK quick reference#

import { createVibe } from '@facilio/vibe-sdk';
const vibe = createVibe();   // serverURL defaults to window.location.origin
// Authawait vibe.getCurrentUser();      // { user: { uid, email, name, username }, org: { orgId } } or nullawait vibe.isAuthenticated();     // booleanvibe.login();                     // redirect to identity-servicevibe.logout();                    // sign out
// Dataconst { response } = await vibe.executeAction(  'facilio-cmms',  'list-assets',  { /* payload — shape from MCP catalog */ });const assets = response?.data ?? [];
// Escape hatchawait vibe.fetch('/api/runtime/...');   // thin wrapper around fetch() with credentials and 401 handling
MethodPurpose
createVibe()Create the SDK client. Defaults to window.location.origin.
getCurrentUser()Returns { user, org } or null. Use as the single source of truth for "is the user signed in?".
isAuthenticated()Boolean check for signed-in state.
login()Redirect to identity-service login. Wire this when getCurrentUser() returns null.
logout()Sign out the current session.
executeAction(connectionSlug, actionSlug, payload)The only sanctioned way to call Facilio data. Slugs come from the MCP catalog.
executeFunction(name, handler, args)Execute a handler of one of your app's built functions (server-side, can query the app's DB).
fetch(path, init)Raw HTTP escape hatch with credentials: 'include' and auto-redirect to login on 401. Prefer executeAction.

See the SDK Reference for full method signatures, response shapes, and error handling.

Build with AI#

AI agents can develop and ship a Vibe app end-to-end. Point the agent at the full Vibe build-and-deploy guide:

https://facilio.com/developers/docs/vibe/llms.txt

See Building with AI Agents for prompt patterns and the agent-autonomy recipe.

Hard constraints#

  1. The build output folder must contain index.html at its root — this is a constraint on the build output, not your source layout. Bundlers like Vite, webpack, and Next export produce this automatically.
  2. The site is static — no server-side rendering, no Node runtime on the server. Anything dynamic happens client-side through the SDK.
  3. Auth is browser-cookie based — gated by @facilio/vibe-sdk. Don't roll your own login.
  4. All Facilio data access goes through vibe.executeAction() — never call arbitrary /api/... URLs you guessed at. Slugs and payloads come from the MCP catalog.
On This Topic