Developer Documentation

Getting Started

Gridlight apps are web applications that run inside the Gridlight desktop shell. They can be as simple as a single HTML file or as complex as a full-stack app with a backend server. The Gridlight platform gives your app instant access to local AI capabilities — LLMs, image generation, RAG, and memory — without any cloud dependencies.

You have three ways to build apps:

• App Builder — A visual, no-code builder for creating apps by dragging and dropping components
• New Dev App — Scaffold a new app from templates directly inside Gridlight
• Manual — Write your app from scratch using HTML, CSS, and JavaScript

Architecture Overview

Here's how the pieces fit together:

• Gridlight Desktop (Tauri) — The native shell that loads and displays your apps
• Gateway (Rust/Axum) — REST API on port 8080 that orchestrates all AI requests
• Agents — Specialized workers for inference, embeddings, reranking, and verification
• Your App — A web app (HTML/CSS/JS) rendered in a Tauri webview, calling the Gateway API

Prerequisites

• Gridlight desktop app installed and running
• At least one AI model downloaded (for testing AI features)

# Check Node.js
node --version

# Check that Gridlight Gateway is running
curl http://localhost:8080/health

App Builder (No-Code)

The fastest way to build a Gridlight app is with the visual App Builder. Open it in your browser, choose a layout, drag components onto the canvas, configure their properties, and export a ready-to-run app — no code required.

1. 1

   Open App Builder

   Launch App Builder from within Gridlight — find it in your apps library and click to open.

2. 2

   Choose a layout

   Pick a layout that matches your app's purpose:

   • Chat — Messages panel, input area, sidebar
   • Dashboard — Metrics, charts, data tables
   • Sidebar — Navigation sidebar with main content area
   • Split — Two-panel side-by-side layout
   • Full Canvas — Freeform, flexible layout
3. 3

   Add components

   Browse the component panel on the left. Drag components into the canvas zones. There are 56+ components across categories: forms, display, data visualization, AI-powered, navigation, and more.

4. 4

   Configure properties

   Click any component to open its configuration panel on the right. Set labels, placeholder text, colors, data sources, and AI settings.

5. 5

   Preview and export

   Preview your app in real time, then export it as a standalone HTML file or a .glapp package for distribution.

AI-Powered Building

The App Builder includes an AI assistant. Click "Build with AI" and describe what you want in plain language:

"Create a customer feedback form with a star rating,
comment box, email field, and a submit button that
saves responses to Gridlight."

The AI generates the full page layout with configured components. You can accept it as-is, regenerate, or fine-tune individual components.

Creating a New Dev App

The quickest way to scaffold a new app is right inside Gridlight. Click the "New Dev App" button in the Apps tab and Gridlight will generate a complete project template for you — ready to customize.

1. 1

   Open the Apps tab

   In the Gridlight desktop app, navigate to the Apps tab.

2. 2

   Click "New Dev App"

   You'll see a button to create a new developer app. Click it and give your app a name.

3. 3

   Choose a template

   Pick a starting template that matches your app's purpose:

   • Default — Basic starter with a heading and text
   • Chat — Chat interface with messages panel and input
   • Dashboard — Metrics, cards, and data display
4. 4

   Select a theme and layout

   Customize the look and structure:

   Option	Choices
   Theme	Gridlight (dark), Midnight (deep purple), Modern (light), Minimal (B&W)
   Layout	Chat, Dashboard, Sidebar, Split, Full Canvas

5. 5

   Start building

   Gridlight creates the project with the right file structure and opens it for you. You'll get a gridlight.json manifest, an app.json configuration, and an HTML entry point — everything you need to start customizing.

Your new app will have this structure:

my-app/
├── gridlight.json       # App manifest (name, version, entry point)
├── src/
│   ├── app.json         # App configuration (layout, components, zones)
│   └── index.html       # Entry point
└── README.md

Building Apps with Code

For maximum control, build your app from scratch. You just need two files: agridlight.json manifest and an HTML entry point.

{
  "name": "My Custom App",
  "version": "1.0.0",
  "short_description": "A custom AI-powered application",
  "detailed_description": "A full description of what this app does and its features.",
  "usage_instructions": "Describe how to use the app here.",
  "author": "Your Name",
  "icon": "src/assets/icon.webp",
  "entry": "src/index.html",
  "runtime": "1.0",
  "type": "standalone",
  "gridlight_version_required": "0.6.0",
  "permissions": ["network", "storage"],
  "dependencies": {
    "components": [],
    "themes": []
  },
  "build": {
    "target": "single-html",
    "minify": true
  },
  "window": {
    "width": 1200,
    "height": 800
  }
}

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>My Custom App</title>
  <style>
    body { font-family: system-ui; background: #0f0f23; color: #fff; }
  </style>
</head>
<body>
  <h1>Hello, Gridlight!</h1>
  <button onclick="askAI()">Ask AI</button>
  <div id="response"></div>

  <script>
    async function askAI() {
      const res = await fetch('http://localhost:8080/neon', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'Authorization': 'Bearer dev-token'
        },
        body: JSON.stringify({
          question: 'What is Gridlight?',
          stream: false
        })
      });
      const data = await res.json();
      document.getElementById('response').textContent = data.answer;
    }
  </script>
</body>
</html>

For hybrid apps with a backend server, add a backend section to your manifest:

{
  "name": "My Hybrid App",
  "version": "1.0.0",
  "short_description": "An app with a backend server",
  "author": "Your Name",
  "icon": "frontend/assets/icon.webp",
  "entry": "frontend/index.html",
  "runtime": "1.0",
  "type": "hybrid",
  "gridlight_version_required": "0.6.0",
  "backend": {
    "entry": "backend/server.js",
    "port": 3002,
    "install": "npm install",
    "healthCheck": "/api/health"
  },
  "permissions": ["network", "storage"],
  "dependencies": {
    "components": [],
    "themes": []
  },
  "build": {
    "target": "hybrid-app",
    "minify": true
  },
  "window": {
    "width": 1200,
    "height": 800
  }
}

Manifest Field Reference

Recommended Project Structure

Follow these conventions to keep your project clean and ready for marketplace publishing.

Standalone App

my-app/
├── gridlight.json          # App manifest
├── src/
│   ├── index.html          # Entry point
│   ├── app.json            # App config (settings, theme, layout)
│   ├── assets/
│   │   ├── icon.svg        # App icon (SVG recommended)
│   │   └── logo.webp        # Logo or branding assets
│   ├── css/
│   │   └── styles.css      # Stylesheets
│   └── js/
│       └── app.js          # Application logic
├── scripts/
│   └── package-glapp.js    # Build script for .glapp export
├── dist/                   # Build output
│   └── my-app-1.0.0.glapp  # Packaged app for marketplace
└── tests/                  # Test files

• Keep gridlight.json at the project root — Gridlight looks for it there.
• Use src/ for all source files to keep the root directory clean.
• Use SVG for your app icon — it scales to any size in the marketplace and app launcher.
• Build output goes to dist/. Your .glapp package is generated there.

Hybrid App (with Backend)

my-hybrid-app/
├── gridlight.json          # App manifest (type: "hybrid")
├── frontend/
│   ├── index.html          # Frontend entry point
│   ├── assets/
│   │   └── icon.svg
│   ├── css/
│   │   └── theme.css
│   └── js/
│       └── app.js
├── backend/
│   ├── server.js           # Backend entry point (Express, etc.)
│   ├── package.json        # Backend dependencies
│   ├── routes/             # API route handlers
│   │   ├── health.js
│   │   └── api.js
│   ├── services/           # Business logic
│   │   └── myService.js
│   └── db/                 # Database files (if using SQLite)
│       ├── schema.sql
│       └── init.js
├── dist/                   # Build output
│   └── my-hybrid-app-1.0.0.glapp
└── tests/

• Separate frontend/ and backend/ directories clearly.
• Your backend server.js should listen on the port specified in gridlight.json.
• Always provide a health check endpoint (e.g. /api/health) so Gridlight can verify the backend is running.
• Put package.json in the backend directory and set "install": "npm install" in the manifest so dependencies are installed automatically.
• Use routes/ for API endpoints and services/ for business logic.
• For SQLite databases, store files in backend/db/.

Enabling Dragging App Window

For app developers building Gridlight marketplace apps, the only thing needed is to add data-tauri-drag-region to your header element:

<header class="header" data-tauri-drag-region>
    <span>My App Name</span>
    <button>Settings</button>  <!-- buttons still work normally -->
</header>

That's it. Gridlight automatically detects:

• Any element with data-tauri-drag-region attribute
• Any <header> element
• Any element with class header

So if your app already has a <header> tag or a .header class on your top bar, dragging works automatically with no changes.

Interactive children (buttons, inputs, links, selects) are automatically excluded from the drag behavior.

Component Library

Gridlight provides 56 modular UI components you can use in your apps. Each component has configurable properties, built-in styling, and JavaScript logic. When using the App Builder or the app.json configuration, you reference these by type name.

Endpoint Components

These components connect directly to Gridlight's AI APIs:

Display Components

Components for rendering content and showing status:

Form Components

Input components for collecting user data. All form components support storageKey for persisting values across sessions.

AI-Powered Components

Specialized AI components that add intelligence to your apps with zero configuration:

Data & Visualization Components

Components for building dashboards and displaying structured data:

Layout & Container Components

Structural components for organizing your app's interface:

App Manifest Specification

Every Gridlight app needs a gridlight.json file at the project root. This is how Gridlight discovers and loads your app.

Required Fields

Optional Fields

Permissions

The permissions array declares what system capabilities your app needs.

Window Object

Controls the initial window size and behavior when the app launches.

Dependencies Object

"dependencies": {
  "components": [],
  "themes": ["gridlight"],
  "external": ["chart.js", "katex"]
}

Build Object

"build": {
  "target": "single-html",
  "minify": true
}

Backend Object (Hybrid Apps)

Required when type is "hybrid". Configures the backend server that Gridlight starts alongside your frontend.

Connections Array

Declare MCP (Model Context Protocol) connections your app can use.

"connections": [
  { "id": "filesystem", "required": true },
  { "id": "fetch-web", "required": false },
  { "id": "github", "required": false }
]

Data Binding & State

When building apps with the App Builder or app.json, you can connect components together using data bindings. Changes to one component automatically update any bound components.

{
  "bindings": [
    {
      "source": "search-input",
      "sourceProperty": "value",
      "target": "results-display",
      "targetProperty": "query"
    }
  ]
}

In exported apps, you can use the runtime API:

// Set a value
window.AppBindings.setValue('global.username', 'Jane');

// Get a value
const name = window.AppBindings.getValue('global.username');

// React to changes
window.AppBindings.onChange('global.username', (newValue) => {
  console.log('Username changed to:', newValue);
});

Workflows & Automation

Workflows let you automate multi-step processes in your apps — from simple "on form submit, show notification" to complex chains with conditional branching and API calls.

App Builder Workflows

In the App Builder, workflows are defined visually. Define triggers (what starts the workflow) and actions (what happens):

{
  "workflows": [
    {
      "name": "Submit Feedback",
      "trigger": { "type": "form_submitted", "source": "feedback-form" },
      "actions": [
        {
          "type": "api_call",
          "url": "http://localhost:8080/training/text",
          "method": "POST",
          "body": { "content": "{{feedback-form.value}}", "domain": "feedback" }
        },
        {
          "type": "show_notification",
          "message": "Thank you for your feedback!",
          "variant": "success"
        }
      ]
    }
  ]
}

Themes & Styling

Gridlight apps support built-in themes and fully custom styling. Themes control colors, fonts, spacing, and component appearance.

Built-in Themes

Custom Themes

Create your own theme by setting CSS custom properties:

{
  "theme": {
    "preset": "custom",
    "primary": "#e91e63",
    "secondary": "#2196f3",
    "background": "#0f0f23",
    "surface": "rgba(26, 26, 46, 0.8)",
    "text": "#ffffff",
    "textMuted": "#888888",
    "accent": "#a855f7",
    "fontFamily": "Inter",
    "customFontUrl": "https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700"
  }
}

Export & Publishing

Once your app is ready, export it in the format that fits your needs.

HTML Export

Export as a single HTML file — perfect for quick sharing or embedding. Everything (styles, scripts, components) is bundled into one file.

.glapp Package

The native Gridlight package format for desktop distribution. This is what you need to publish to the marketplace.

npm run build      # Compile your app
npm run package    # Create .glapp file

The .glapp file contains your manifest, compiled app, and runtime. Users install it by downloading and placing it in their ~/Gridlight/apps/ directory.

PWA Export

You can also export as a Progressive Web App with a manifest and service worker for installable, offline-capable deployments.

Publishing to Marketplace

1. 1

   Build your .glapp package

   Run npm run package to create the distributable file.

2. 2

   Create a marketplace listing

   Visit market.gridlight.ai, create an account, and submit your app with screenshots, description, pricing, and categories.

3. 3

   Set pricing

   Choose free or paid distribution. Paid apps use Stripe for secure payments. Bundle discounts are automatically applied for multi-app purchases from the same seller.

4. 4

   Publish

   Submit for review. Once approved, your app is live in the marketplace for all Gridlight users to discover.

API Reference

All API requests go to the Gridlight Gateway at http://localhost:8080. Every request requires an Authorization: Bearer <token> header.

RAG / Knowledge Query

The /neon endpoint is Gridlight's powerhouse. It combines vector search, keyword retrieval, entity recognition, reranking, and LLM generation into a single call.

{
  "question": "What is our vacation policy?",
  "domain": "HR",
  "stream": true,
  "limit": 10,
  "access_tier": "internal",
  "include_sources": true,
  "max_tokens": 4096
}

With stream: true, responses come as Server-Sent Events:

data: {"token": "Our"}
data: {"token": " vacation"}
data: {"token": " policy"}
data: [DONE]

Intelligent Chat

Multi-turn conversations with context awareness. The AI adapts to your expertise level and preferred response style.

{
  "message": "Explain how embeddings work",
  "conversation_id": "conv-123",
  "history": [
    { "role": "user", "content": "What is RAG?" },
    { "role": "assistant", "content": "RAG stands for..." }
  ]
}

Image Generation

Generate images from text, transform existing images, or inpaint specific regions.

{
  "prompt": "A cyberpunk cityscape at sunset, neon lights",
  "negative_prompt": "blurry, low quality",
  "width": 1024,
  "height": 1024,
  "steps": 30,
  "cfg_scale": 7.5,
  "seed": -1
}

Memory

Store and retrieve user-specific facts, preferences, and context.

{
  "content": "User prefers Python code examples",
  "memory_type": "preference",
  "expiration": "never"
}

// Response:
{
  "memories": [
    {
      "id": "mem-1",
      "content": "User prefers Python code examples",
      "type": "preference",
      "created_at": "2026-01-15T10:30:00Z"
    }
  ]
}

File Upload

Upload documents to the knowledge base for RAG indexing.

// Supported formats: .pdf, .docx, .txt, .md, .csv,
// .xlsx, .json, .xml, .py, .js, .ts, .rs, .go, .java

// Request: multipart/form-data
// - file: the document file
// - domain: "HR" (optional, for data isolation)
// - access_tier: "internal" (public/internal/restricted)

// Response:
{
  "status": "success",
  "chunks": 42,
  "message": "Document indexed successfully"
}

Best Practices

Building great Gridlight apps is about more than just wiring up components. These tips — drawn from our own apps like Gridlight Chat and the VS Code extension — will help you build apps that feel fast, responsive, and reliable.

Streaming Responses

Always use streaming when interacting with the LLM. Streaming lets your users see tokens appear in real-time instead of waiting for the full response. This single change has the biggest impact on perceived performance.

const response = await fetch(`${gatewayUrl}/api/chat`, {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${apiToken}` },
  body: JSON.stringify({ question, stream: true })
});

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  const chunk = decoder.decode(value);
  // Parse SSE data fields
  for (const line of chunk.split('\n')) {
    if (line.startsWith('data: ')) {
      const data = JSON.parse(line.slice(6));
      appendToMessage(data.content);
    }
  }
}

Efficient DOM Updates

When streaming tokens, avoid re-rendering your entire message list on every chunk. Instead, target just the active message element.

• Batch updates with requestAnimationFrame — Instead of updating the DOM on every token, collect tokens and flush them at 60fps. This reduces DOM writes from 20+/sec to ~16/sec.
• Update only the streaming message — Find the specific message element and update its content directly. Don't rebuild all messages.
• Cache completed markdown — Once a message finishes streaming, cache its processed markdown. On re-renders, use the cached version instead of re-processing.

let pendingTokens = '';
let rafId = null;

function onToken(token) {
  pendingTokens += token;
  if (!rafId) {
    rafId = requestAnimationFrame(() => {
      messageEl.textContent += pendingTokens;
      pendingTokens = '';
      rafId = null;
    });
  }
}

Caching & Pre-fetching

Smart caching can dramatically reduce latency, especially for context-heavy operations. Use tiered TTLs based on how frequently data changes.

For multi-step workflows, speculatively pre-fetch context for the next step while the current one is executing. This overlap hides latency and can reduce end-to-end time by 30–50%.

Error Handling & Retries

Network hiccups happen. A good retry strategy keeps your app resilient without overwhelming the server.

• Exponential backoff with jitter — Start at 1 second, multiply by 2 on each retry, add ±10% random jitter to prevent thundering herd.
• Categorize errors — Network errors, rate limits (429), and server errors (5xx) are retryable. Auth errors (401/403) and client errors (400) are not.
• Cap retries — 3 retries with a 30-second maximum delay is a good default. For rate limits, respect the Retry-After header.
• Don't retry streaming requests — If a streaming connection drops, start fresh rather than retrying mid-stream.

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      const response = await fetch(url, options);
      if (response.ok) return response;

      // Don't retry client errors
      if (response.status >= 400 && response.status < 500) throw response;

      // Retry server errors
      if (attempt < maxRetries) {
        const delay = Math.min(1000 * Math.pow(2, attempt), 30000);
        const jitter = delay * (0.9 + Math.random() * 0.2);
        await new Promise(r => setTimeout(r, jitter));
      }
    } catch (err) {
      if (attempt === maxRetries) throw err;
    }
  }
}

Resource-Aware Design

Gridlight runs on everything from laptops to enterprise workstations. Your app should adapt to the available resources.

• Check TFLOP allocation — Use the gateway's system info to understand compute capacity and adjust batch sizes, concurrency, and timeouts accordingly.
• Scale batch operations dynamically — On low-end systems (under 4 CPU cores), use smaller batches with longer delays. On high-end systems (16+ cores), increase concurrency.
• Debounce file watchers — If your app watches files (for RAG indexing, auto-save, etc.), debounce updates by 2 seconds. Rapid changes like "save all" or git checkouts can trigger dozens of events.
• Bound your caches — Set a max entry count (e.g., 50 files) and a max total size (e.g., 10MB). Use LRU eviction when limits are reached.

UX Patterns

The best Gridlight apps feel responsive even when the AI is thinking. Here are patterns that create that perception:

• Show placeholder messages immediately — When a user sends a message, instantly create a placeholder response ("Looking into your documents...") before the API call even starts. Transition to "Thinking..." once the LLM begins processing.
• Provide a stop button — Use an AbortController to let users cancel in-flight requests. Release reader locks and clean up state on cancellation.
• Use fast-path checks — Before running expensive operations (like regex or markdown processing), do a quick check to see if it's needed. For example, skip stripThinkingTags() if the text doesn't contain <think>.
• Parallelize read-only operations — If your app fetches multiple pieces of context (files, documents, embeddings), run them concurrently with Promise.all(). Only serialize write operations.
• Handle large inputs gracefully — If user input exceeds your API's context limit, split it into conversation history chunks (~9K characters each) and pass them as prior turns. This preserves context without hitting limits.