openframe-oss-frontend README

The project's README from github.com/flamingo-stack/openframe-oss-frontend. As one markdown file: README.md.

OpenFrame

License

OpenFrame OSS Frontend

OpenFrame OSS Frontend is the primary web application for the OpenFrame platform — a unified, AI-driven interface for Managed Service Providers (MSPs). It replaces expensive proprietary MSP software with intelligent open-source alternatives, bringing device management, ticketing, monitoring, scripts, and AI assistance into a single cohesive operational interface.

Built and maintained by Flamingo, this project is the human-facing layer of the OpenFrame ecosystem — connecting backend services into an AI-first MSP experience.

Features

Feature Description
Device Management Unified device model, remote shell, file manager, remote desktop via MeshCentral
Customer Management Per-organization AI configuration, guardrails templates, aggregated device counts
Ticketing Kanban boards, AI-assisted replies, approval workflows, assignment management
Knowledge Base Article management, folder organization, attachment handling
Mingo AI (Technician) Streaming AI assistant with tool execution, context awareness, and approval flows
Customer AI (Fae) Embeddable AI for client-facing portals
Monitoring Fleet MDM policies, osquery live query campaigns, query execution
Scripts Script library, scheduling, execution history
Audit Logs Organization and device-level log viewer with cursor-based pagination
Settings & Billing Tenant config, SSO, API keys, subscription management
Onboarding Step-by-step guided setup for new tenants
Feature Flags Runtime-configurable feature toggles via Zustand

Technology Stack

flowchart TD
    FE["Next.js 16 App Router (React 19)"]
    FE --> TS["TypeScript 5.8"]
    FE --> GQL["GraphQL — graphql + Relay v20"]
    FE --> RQ["TanStack Query v5"]
    FE --> ZS["Zustand v5"]
    FE --> TW["Tailwind CSS v3"]
    FE --> FC["openframe-frontend-core"]
    FE --> API["API Service Core"]
    FE --> Chat["AI / Chat Service"]
    FE --> Auth["Authorization Service"]
    FE --> Fleet["Fleet MDM"]
    FE --> Mesh["MeshCentral"]

Core Dependencies

Package Version Purpose
next ^16.2.4 SSR + App Router framework
react ^19.2.0 UI library
react-relay ^20.1.1 GraphQL fragment system
@tanstack/react-query ^5.90.16 Server-state caching and pagination
zustand ^5.0.8 Client-side state management
tailwindcss ^3.4.17 Utility-first CSS
@xterm/xterm ^6.0.0 Terminal emulator for remote shell
@monaco-editor/react ^4.7.0 Script editor
zod ^4.3.6 Runtime schema validation
@flamingo-stack/openframe-frontend-core ^0.0.480 Shared UI component library

Architecture

OpenFrame OSS Frontend acts as the presentation and orchestration layer on top of OpenFrame backend services.

flowchart LR
    Browser["User Browser"] --> Frontend["OpenFrame OSS Frontend"]
    Frontend -->|"GraphQL /api/graphql"| ApiService["API Service Core"]
    Frontend -->|"REST /chat/api"| ChatService["AI / Chat Service"]
    Frontend -->|"OAuth 2.0"| AuthService["Authorization Service"]
    Frontend -->|"/tools/fleetmdm-server"| Fleet["Fleet MDM"]
    Frontend -->|"/tools/meshcentral"| Mesh["MeshCentral"]
    ApiService --> DataLayer["MongoDB / Cassandra / Apache Pinot"]
    ChatService --> StreamLayer["Kafka / NATS"]

Application Domain Structure

The application is organized by feature domain under src/app:

flowchart TD
    App["src/app"]
    App --> Customers["customers/"]
    App --> Devices["devices/"]
    App --> Tickets["tickets/"]
    App --> KnowledgeBase["knowledge-base/"]
    App --> Logs["logs-page/"]
    App --> Monitoring["monitoring/"]
    App --> Scripts["scripts/"]
    App --> Settings["settings/"]
    App --> Mingo["mingo/"]
    App --> Onboarding["onboarding/"]
    App --> Lib["src/lib/ — API, Auth, Relay, MeshCentral"]
    App --> Stores["src/stores/ — Zustand global state"]

State Management

The application uses three complementary state management approaches:

Pattern Technology Used For
Server state TanStack Query v5 REST API calls, optimistic mutations, cursor pagination
GraphQL fragments Relay v20 Logs, scripts, notifications (streaming + pagination)
Client UI state Zustand v5 Feature flags, onboarding, Mingo chat, device filters

Quick Start

Prerequisites: Node.js 18+, npm 9+, Git. See the Prerequisites Guide for full details.

# 1. Clone the repository
git clone https://github.com/flamingo-stack/openframe-oss-frontend.git
cd openframe-oss-frontend

# 2. Install dependencies
npm install

# 3. Configure environment
cp .env.example .env.local
# Edit .env.local with your backend URLs

# 4. Start the development server
npm run dev

Open http://localhost:3000 in your browser.

Minimum Environment Variables

NEXT_PUBLIC_TENANT_HOST_URL=https://your-tenant.openframe.dev
NEXT_PUBLIC_SHARED_HOST_URL=https://api.openframe.dev
NEXT_PUBLIC_APP_MODE=oss-tenant
NEXT_PUBLIC_APP_URL=http://localhost:3000

Refer to your environment configuration for actual backend URLs.

Available Scripts

Script Description
npm run dev Start development server with hot reload
npm run build Generate schema enums + Relay artifacts + Next.js production build
npm run start Start production server (after build)
npm run lint Run ESLint (the fast pass; rules come from the core library's shared config)
npm run lint:fix ESLint autofix
npm run lint:types ESLint type-aware pass (slow — needs an 8 GB heap)
npm run format:fix Auto-fix formatting with Prettier
npm run type-check TypeScript type checking without emitting
npm run relay Compile Relay GraphQL fragments
npm run relay:watch Watch and recompile Relay fragments on change
npm run fetch-schema Fetch the latest GraphQL schema from the backend

Documentation

📚 See the Documentation for comprehensive guides including getting started tutorials, development workflows, architecture overviews, and API references.

Community & Support

OpenFrame OSS is supported through the OpenMSP Slack community — the primary channel for discussions, questions, and collaboration.

We do not use GitHub Issues or Discussions. All support and coordination happens in Slack.

Contributing

We welcome contributions! Please read the Contributing Guidelines before opening a pull request.

Key points:

Built with 💛 by the Flamingo team

openframe-oss-frontend (flamingo-stack/openframe-oss-frontend)

relay
Searching Database…

852 ·GitHub
Openframe-oss-frontend
What is this?It's the main web application of the OpenFrame platform — a unified, AI-driven control panel for Managed Service Providers (MSPs), positioned as an open-source replacement for expensive proprietary MSP software.
So is this the whole MSP platform, or just the UI on top of it?Just the UI — it's the presentation and orchestration layer that talks to separate OpenFrame backend services. Server and database logic live outside this repo.
How do I get it running locally?Install Node.js 18+, npm 9+ and Git, clone the repo, fill in the minimum environment variables with your backend URLs, then run npm run dev (or npm run build && npm run start for production).
Where does the AI come in?Two built-in assistants: Mingo for technicians — a streaming AI with tool execution, context awareness and approval flows — and Fae, an embeddable AI for client-facing portals. Each organization can also have its own AI configuration with guardrails templates.
Can it run standalone, or does it need the OpenFrame backends too?It needs the OpenFrame backend services: their URLs come from environment variables, and the GraphQL schema is pulled from the backend with npm run fetch-schema, so the UI alone won't do much.
Can I control customer machines directly from it?Yes — each device gets a remote shell in an in-browser terminal, a file manager and remote desktop via MeshCentral, plus fleet-wide osquery live query campaigns and script scheduling with execution history.
What's the tech stack under the hood?Next.js 16 on the App Router with React 19, Relay v20 for GraphQL fragments, TanStack Query v5 for server state, Zustand v5 for client UI state, and Tailwind CSS — plus xterm for the remote shell and Monaco as the script editor.
Does it ship its own component library?No — shared UI components come from the @flamingo-stack/openframe-frontend-core package, and even the ESLint rules are inherited from that core library's shared config.
Why did Flamingo build this in the open?The stated goal is replacing expensive proprietary MSP software with intelligent open-source alternatives — this app is the human-facing layer of the OpenFrame ecosystem, connecting its backend services into one AI-first MSP experience.
What are similar projects?CopilotKit, sim, herdr-web-ui, clevis, ant-design-pro, labtether, open-glean, NodePilot
Which topics is it in?monaco-editor, xterm, multi-tenancy, relay, tailwind, audit-log, remote-access, sso, ai-assistant, state-management, graphql, knowledge-base
Creator
flamingo-stack
Size
13.2 MB
Stars
852
Updated
CommitOct 16Release1.0.173Oct 16
Age
3mo
Commits · 90 Days