LightBase Studio — User Guide

A local-first, multi-protocol API development platform powered by a native C-Core engine.

Getting Started
Dashboard
API Studio
- REST Requests
- GraphQL
- WebSocket
- gRPC
- MQTT
Pre-Request Scripts
Test Scripts
Response Visualizer
SQL Console
Visual Flows
Monitors
Request History
Collections & Local Storage
Environments & Variables
Mock Servers
API Documentation Generator
AI Companion
Crypto Vault
Git Sync
Cookie Jar
Stress Testing
Security Hardening
Enterprise Engine
Code Snippet Generator
Webhook Alerts

Getting Started

Prerequisites

System packages: cmake build-essential libssl-dev libsqlite3-dev libgit2-dev
Build: make (installs Python deps and builds C-Core)
Run: make run (starts the bridge server and opens the UI)
Test: make test (runs 75 tests across 24 categories)
Clean: make clean (removes build artifacts, caches, logs)

Architecture

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│   Browser UI    │ ←→  │  Python Bridge   │ ←→  │  C-Core Engine  │
│  (HTML/CSS/JS)  │     │  (port 8000)     │     │  (libcore.so)   │
└─────────────────┘     └──────────────────┘     └─────────────────┘
                              │
                        ┌─────┴──────┐
                        │ workspace/ │  ← 100% local JSON files
                        │  (Git-able)│
                        └────────────┘

100% Local-First Storage

All your data is stored as plain JSON files in workspace/:

workspace/
├── collections/    # Saved API requests
├── environments/   # Variable sets (dev, staging, prod)
├── history/        # Auto-logged request/response pairs
├── monitors/       # Scheduled run configs & results
├── mocks/          # Mock server definitions
├── flows/          # Visual workflow definitions
└── docs/           # Generated OpenAPI specs

Every file is a plain JSON file you can commit to Git. No cloud sync needed — just git push.

Dashboard

The Dashboard tab shows real-time system telemetry from the native C-Core:

CPU Utilization: Live percentage with gradient area chart (30-point history)
Memory Usage: Used/Total with animated progress bar
Ring Buffer Slot: Current telemetry log write position
Telemetry History: Click "Load" to read stored binary telemetry snapshots from the C mmap'd ring buffer

API Studio

The API Studio supports 5 protocols via the protocol selector bar at the top.

REST Requests

Select HTTP method: GET, POST, PUT, DELETE, PATCH
Enter URL — supports {{variable}} interpolation from your active environment
Add Headers and Form Data using the ＋ buttons
Enter JSON Body for POST/PUT/PATCH
Click Send

The response appears below with:

Status badge (color-coded)
Latency (µs from C-Core)
Size (bytes)
Hex dump (expandable)
Filter box (regex-capable with /pattern/flags syntax)

GraphQL

Switch to the GraphQL protocol tab
Enter the GraphQL endpoint hostname and path
Write your query in the Query editor
Add variables in the Variables panel (JSON)
Click Query

query GetUser($id: ID!) {
  user(id: $id) {
    name
    email
    posts { title }
  }
}

Variables:

{"id": "123"}

WebSocket

Switch to the WebSocket protocol tab
Enter a WebSocket URL (e.g., wss://echo.websocket.org)
Click Connect to establish connection
Type messages and click Send — responses appear in the live message log
All messages are timestamped and logged

gRPC

Switch to the gRPC protocol tab
Enter the target address (e.g., localhost:50051)
Specify the Service name (e.g., helloworld.Greeter)
Specify the Method name (e.g., SayHello)
Enter the message as JSON
Click Invoke

MQTT

Switch to the MQTT protocol tab
Enter broker address and port
Set the Topic (e.g., sensors/temperature)
Publish: Enter a payload and click Publish
Subscribe: Click Subscribe to listen for 3 seconds and display received messages

Pre-Request Scripts

Write JavaScript that executes before each REST request. Use the lb object:

// Set a dynamic timestamp
lb.setVariable('timestamp', Date.now().toString());

// Generate a random request ID
lb.setVariable('requestId', Math.random().toString(36).substr(2, 9));

// Read an existing variable
const token = lb.getVariable('authToken');

Variables set here are immediately available as {{variableName}} in your URL, headers, and body.

Test Scripts

Write test scripts using the lb.* API that runs after each response:

// Named test blocks
lb.test("Status is 200", () => {
    lb.expect(lb.response.status).toBe(200);
});

lb.test("Response has data", () => {
    const body = lb.response.json();
    lb.expect(body.url).toBeTruthy();
});

lb.test("Has correct header", () => {
    lb.expect(lb.response.status).toBeGreaterThan(199);
});

// Set variables for chaining across requests
lb.setVariable('userId', lb.response.json().id);

Available Assertions

Method	Description
`lb.expect(val).toBe(x)`	Strict equality check
`lb.expect(val).toContain(x)`	String/array contains
`lb.expect(val).toBeTruthy()`	Truthy check
`lb.expect(val).toBeGreaterThan(x)`	Numeric comparison

Available Objects

Object	Description
`lb.response.status`	HTTP status code
`lb.response.json()`	Parsed response body
`lb.response.headers`	Response headers object
`lb.setVariable(k, v)`	Store cross-request variable
`lb.getVariable(k)`	Retrieve stored variable

Response Visualizer

Create custom HTML/CSS/JS dashboards from API response data:

Expand the Visualizer section below the response
Write HTML/JS using the data variable (which contains the parsed response)
Click ▶ Render to display in the sandboxed iframe

// Example: Create a table from API data
const items = Array.isArray(data) ? data : [data];
let html = '<table border="1" style="border-collapse:collapse;font-family:sans-serif">';
html += '<tr><th>Key</th><th>Value</th></tr>';
Object.entries(items[0] || {}).forEach(([k,v]) => {
    html += `<tr><td>${k}</td><td>${v}</td></tr>`;
});
html += '</table>';
document.body.innerHTML = html;

SQL Console

Execute SQL queries directly against your active database through the C-Core arena allocator:

Switch to the SQL tab
Write one or more SQL statements
Click ⚡ Execute
Results appear as formatted JSON with C-Core latency displayed

CREATE TABLE IF NOT EXISTS users (
    id INTEGER PRIMARY KEY,
    name TEXT NOT NULL,
    email TEXT UNIQUE
);

INSERT INTO users (name, email) VALUES ('Aarav', 'aarav@lightbase.dev');
SELECT * FROM users;

Visual Flows

Build complex, multi-step API workflows visually:

Node Types

Node	Purpose
Request	Executes an HTTP request (method + URL)
Condition	Evaluates a JavaScript expression to branch logic
Transform	Transforms data between steps using JavaScript
AI Block	Processes data through the local AI inference engine

Usage

Switch to the Flows tab
Click ＋ Request, ＋ Condition, ＋ Transform, or ＋ AI Block to add nodes
Configure each node (URL, condition expression, transform code, or AI prompt)
Enter a flow name and click 💾 Save (saves to workspace/flows/)
Click ▶ Run to execute all nodes sequentially
Results appear in the output pane

Saved flows appear in the list below and can be reloaded by clicking them.

Monitors

Schedule automated collection runs to continuously verify API health:

Switch to the Monitors tab
Select a collection from the dropdown
Set the interval (seconds)
Run Once: Execute the collection immediately and see results
Schedule: Start a recurring background monitor
Active monitors appear in the list with a Stop button

Monitor results are saved to workspace/monitors/ as JSON files with timestamps.

Request History

Every request across all protocols is automatically logged:

Auto-saved to workspace/history/ as individual JSON files
Protocol badges: REST (blue), GraphQL (purple), WebSocket (cyan), MQTT (green), gRPC (yellow)
Search: Filter by URL or protocol
Click to restore: Click any history item to load it back into the API Studio
Clear: Remove all history with the 🗑 button

Collections & Local Storage

Saving a Collection

Enter a name in the Collections sidebar input
Click ＋ Save — this saves the current request configuration (URL, method, headers, body, test scripts, pre-request scripts)
Saved as workspace/collections/{name}.json

Loading a Collection

Click any collection name in the sidebar to restore all fields.

Git Collaboration

Since everything is plain JSON in workspace/, just add it to your .gitignore selectively or commit everything:

git add workspace/collections/ workspace/environments/
git commit -m "Add API test collections"
git push

Your teammates get identical collections, environments, and flows by pulling.

Environments & Variables

Built-in Environments

Environment	DB File	Description
🟢 Development	`test_lightbase.db`	Local development
🟡 Staging	`staging_lightbase.db`	Pre-production testing
🔴 Production	`prod_lightbase.sovereign.db`	Live system

Variable Interpolation

Use {{variableName}} anywhere in URLs, headers, or body:

https://{{baseUrl}}/api/v1/users
Authorization: {{authToken}}

Custom Variables

Click ✏️ Edit Variables in the sidebar
Add/modify key-value pairs
Click 💾 Save — persisted to workspace/environments/
Variables are available immediately as {{key}} tokens

Mock Servers

Create simulated API endpoints for frontend development:

Using mock:// Protocol

Register mocks by entering a path and response body in the Mock Engine sidebar
Use mock://server/path as your URL in API Studio
LightBase will intercept the request and return the mocked response locally

Persistent Mocks via Bridge

Mocks can also be registered via the bridge at POST /mock/register:

{
    "name": "user-service",
    "routes": [
        {"path": "/users", "method": "GET", "status": 200, "body": [{"id": 1, "name": "Test"}]},
        {"path": "/users", "method": "POST", "status": 201, "body": {"id": 2}}
    ]
}

API Documentation Generator

Schema Documentation

Click 🛠️ Schema Docs to auto-generate a Markdown specification of all database tables, columns, types, and constraints from the active database.

OpenAPI 3.0 Export

Click 📋 Export OpenAPI to auto-generate an OpenAPI 3.0 spec from all your saved collections. The spec is saved to workspace/docs/openapi_spec.json.

AI Companion

The built-in AI Companion uses local offline inference (llama.cpp) via the C-Core:

Switch to the AI tab
Enter any prompt — the AI automatically receives your current database schema as context
Click Infer

Use it for:

Writing SQL queries from natural language
Generating test scripts
Optimizing database schemas
Understanding code patterns

Crypto Vault

Store API keys with AES-256-GCM encryption at the C level:

Select a provider (OpenAI, Anthropic, Gemini)
Enter the plaintext API key
Click 🔒 Store — the key is encrypted by the C-Core and stored in the database
Keys can be decrypted via POST /retrieve_vault_key

Git Sync

Click ↻ next to Git Sync in the sidebar to inspect your repository status using the native libgit2 C binding. Shows current branch, uncommitted changes, and tracking status.

Stress Testing

Load-test your APIs with configurable burst patterns:

Set Count (number of requests) and Delay (milliseconds between)
Click 🔥 Ignite
Watch real-time latency measurements from the C-Core
Average latency is calculated at completion

Keyboard Shortcuts & Tips

Sidebar toggle: Click ☰ to collapse/expand the sidebar
Variable preview: Hover over {{tokens}} to see resolved values
Response filter: Use /regex/i syntax for regex filtering
History click: Click any history item to jump back to API Studio with that request loaded
Flow nodes: Click ✕ on any flow node to remove it

CI/CD Integration

Export your collections and run them headlessly:

# Run a collection via the bridge API
curl -X POST http://localhost:8000/run_monitor \
  -H "Content-Type: application/json" \
  -d '{"collection": "my_api_tests"}'

# Export OpenAPI spec
curl -X POST http://localhost:8000/export_openapi \
  -H "Content-Type: application/json" -o openapi.json

# Use in GitHub Actions, Jenkins, etc.

All collection files in workspace/collections/ can be version-controlled and executed in your CI pipeline.

Python Plugin System

Write Python scripts with full PyPI access to process API data:

Switch to the Plugins tab
Write a script with a run(context) function
Click 💾 Save then ▶ Run

import json

def run(context):
    """Process API response data"""
    data = context.get("response", {})
    return {
        "key_count": len(data),
        "keys": list(data.keys()),
        "has_errors": "error" in str(data).lower()
    }

Installing Packages

Use the 📦 Package Installer to install any PyPI package:

Enter package names (e.g., pandas, numpy, beautifulsoup4)
Click Install — runs pip install on the server

Plugin Context

The context dict contains:

Key	Description
`url`	Current request URL
`method`	HTTP method
`body`	Request body
`response`	Parsed response data

AI Agentic Workflows

Three AI-powered actions in the API Studio, all running 100% locally:

🤖 AI Generate Tests

Reads the current response and auto-generates lb.test() assertions. Click the button next to "Test Scripts" — generated tests populate the editor automatically.

🔗 Chain Next

AI analyzes the response and suggests the next logical API request. Automatically fills in the URL, method, and body fields. Perfect for API exploration.

💡 Explain

AI explains the current response in plain English, highlighting important fields, potential issues, and data patterns.

All processing is local — zero data leaves your machine.

Live Data Streamer

Stream high-volume WebSocket and SSE data in real-time:

In API Studio, switch to the Streams protocol tab
Select WebSocket or SSE from the dropdown
Enter the stream URL
Set Duration (seconds to listen)
Click ▶ Stream

The dashboard shows:

Message count and rate per second
Live data log with all received messages
Message inspector for detailed examination

Supports up to 200 messages per session without UI freezing.

Jupyter Notebook Export

One-click export to .ipynb or .py:

From History

Click 📓 Export .ipynb or 🐍 Export .py in the History tab toolbar. Exports the last 20 requests as executable code.

From Collections

Export saved collections as notebooks with proper requests library calls.

Generated files are saved to workspace/exports/ and can be opened in Jupyter Lab, VS Code, or any notebook environment.

Example Output (.py)

#!/usr/bin/env python3
"""Generated by LightBase Studio"""
import requests, json

# Request 1
r0 = requests.get('https://httpbin.org/get')
print(f'Status: {r0.status_code}')
print(json.dumps(r0.json(), indent=2))

Security Hardening

LightBase includes a comprehensive C-level security module accessible via the 🛡️ Security tab and API endpoints.

Security Status Dashboard

The Security tab provides a real-time overview of all active security modules:

POST /security/status
# Returns: HMAC state, rate limiter clients, IP rules, active sessions, etc.

HMAC-SHA256 Request Signing

Sign and verify API payloads to ensure request integrity:

# Sign a payload
POST /security/sign
{"payload": "sensitive_data"}
# → {"signature": "a3b1c9..."}

# Verify integrity
POST /security/verify
{"payload": "sensitive_data", "signature": "a3b1c9..."}
# → {"valid": true}

IP Allowlist / Blocklist

Block or allow specific IPs from the Security tab or API:

POST /security/ip/add     {"ip": "10.0.0.99", "action": "block"}
POST /security/ip/check   {"ip": "10.0.0.99"}
# → {"allowed": false}
POST /security/ip/list    {}
POST /security/ip/remove  {"ip": "10.0.0.99"}

Session Token Manager

Create, validate, and revoke session tokens with TTL:

POST /security/session/create   {"label": "admin", "ttl_seconds": 3600}
# → {"token": "a3b1c9...", "expires": 1779000000}
POST /security/session/validate {"token": "a3b1c9..."}
# → {"valid": true}
POST /security/session/revoke   {"token": "a3b1c9..."}
POST /security/session/list     {}

Audit Trail Logger

Track all API operations in a circular buffer (500 entries):

POST /security/audit/log   {"max_entries": 50}
POST /security/audit/clear {}

Additional C-Level Protections

Feature	Description
Rate Limiter	Token bucket (60 burst, 10/sec refill) with FNV-1a hashing
Path Guard	Blocks `..`, `~`, shell metacharacters, out-of-root paths
SQL Sanitizer	Blocks `ATTACH DATABASE`, `LOAD_EXTENSION`, injection patterns
Secure Wipe	Volatile zero-fill + memory barrier (compiler-proof)
Request Size Limiter	Configurable max payload size (default: 1MB)
AES-256-GCM Vault	Encrypted API key storage at the C level
`mlock()` Key Protection	Signing keys locked in RAM — never swapped to disk
`MADV_DONTDUMP`	All key material excluded from core dumps
`PR_SET_DUMPABLE(0)`	Core dumps disabled process-wide via `prctl()`
Machine-ID Key Derivation	Master encryption key derived from `/etc/machine-id` + salt via SHA-256

Enterprise Engine

The Enterprise Engine (bridge/enterprise.py) provides production-grade features matching platforms like Postman.

Collection Runner

Run entire collections with variable chaining and test execution:

POST /collection/run
{
    "collection": "my_api_tests",
    "environment": "staging",
    "iterations": 3,
    "webhook_url": "https://hooks.slack.com/...",
    "webhook_platform": "slack"
}

Supports {{variable}} interpolation, response chaining via extract, and automatic JUnit/HTML report generation.

Data-Driven Testing

Upload CSV or JSON iteration data:

POST /collection/run_data
{
    "collection": "user_crud",
    "format": "csv",
    "data": "name,email\nAlice,alice@test.io\nBob,bob@test.io"
}

CI/CD Reports

POST /report/junit  {"report": "20260520_120000"}
# → JUnit XML (for Jenkins, GitHub Actions)

POST /report/html   {"report": "20260520_120000"}
# → Styled HTML test report

JSON Schema Validation

POST /validate/schema
{
    "data": {"name": "Jio", "speed": 150},
    "schema": {"type": "object", "required": ["name"], "properties": {"speed": {"type": "integer", "minimum": 10}}}
}

Workspace Export / Import

POST /workspace/export  {}
# → SHA-256 checksummed package with all collections, environments, flows, plugins

POST /workspace/import  {"package": {...}, "merge": true}

Collection Comments & Forking

POST /collection/comment  {"collection": "api", "text": "LGTM", "author": "aarav"}
POST /collection/comments {"collection": "api"}
POST /collection/fork     {"source": "api", "fork_name": "api_v2"}

Code Snippet Generator

Generate client code from any request in 6 languages:

POST /codegen
{"method": "POST", "url": "https://api.example.com/v1/data", "headers": "Authorization: Bearer tok", "body": "{\"key\":\"val\"}", "language": "python"}

Supported: curl, python, javascript, java, go, php

Webhook Alerts

Send alerts to Slack, Microsoft Teams, or custom webhooks:

POST /webhook/send
{
    "webhook_url": "https://hooks.slack.com/services/...",
    "event": "test_failure",
    "platform": "slack",
    "details": {"collection": "prod_api", "passed": 9, "failed": 1}
}

Collection runs can auto-trigger webhooks by including webhook_url in the run request.

Auth Helpers

Apply authentication headers programmatically:

POST /auth/headers
{"headers": "Content-Type: application/json", "auth": {"type": "bearer", "token": "eyJ..."}}
# → {"headers": "Content-Type: application/json\r\nAuthorization: Bearer eyJ..."}

Supported types: bearer, basic, api_key, oauth2

Built with ⚡ by LightBase — 100% local, zero cloud dependencies.

FilesExpand file tree

user_guide.md

Latest commit

History