Plugin SDK · build for QuoxCORE

Quox Plugin SDK.

Build, test and distribute third-party plugins for QuoxCORE. Four packages on npm (@quoxai scope, version 0.4.1), source on GitHub under the Apache 2.0 licence. No marketplace listing flow yet.

Read the docs Developer path View on GitHub

Packages 4Permissions 7Signing Ed25519Status On npm, Apache 2.0

In plain words

What it is, where it lives, when to reach for it

What is it: A software development kit for building plugins that install into the QuoxCORE dashboard.
Where do I use it: On your own development machine, in any Node.js project, with your usual editor.
When would I use it: When QuoxCORE needs a view or capability it does not ship with, and you can build it.
How do I use it: Run npx @quoxai/create-quox-plugin my-plugin, then build, sign and install it with quox plugin install or the dashboard.

QuoxCORE is the free, self-hosted platform underneath this. What is QuoxCORE

How it works

Four steps from idea to installed plugin.

Scaffold, build, package, install. No manual wiring required.

Scaffoldnpx @quoxai/create-quox-plugin my-plugin generates a project from one of 8 templates, with manifest, entry point and a dev preview.

BuildWrite standard React components. npm run build writes dist/plugin.esm.js and dist/plugin.css; npm run validate checks them.

Signnpx quox-plugin keygen --out .keys once, then npm run sign writes dist/signature.json.

InstallInstall from the dashboard or quox plugin install. An org admin trusts your public key with quox plugin trusted-keys add.

What you can build

Extend QuoxCORE in six directions.

Plugins can add UI, storage, notifications and an agent sidebar today. Backends run on managed Quox instances; self-hosted installs do not run them yet.

Sidebar views

Add navigation items and full-page views to the QuoxCORE dashboard. Routes are namespaced under /plugins/ automatically.

sidebar

Your own backend

Ship a container image with your plugin and the frame reaches it through quox.fetch under your plugin namespace. On managed Quox instances it runs on its own network with a per-plugin credential (never the instance key): every request carries a signed ticket for the caller's organisation, and the backend can reach the gateway and the public internet but not your LAN, the host or other plugins. Self-hosted installs from the public release do not run plugin backends yet.', perm: 'network

Your own agent

Declare an agent in your manifest (name, role, color, systemPrompt, suggestions) and Quox renders the agent sidebar next to your plugin, the same component its own agents like NotesQ use. A community agent has no tools: its persona is untrusted text and cannot grant tools, data access or delegation.

sidebar

Memory and evidence (not yet)

window.quox.memory and window.quox.aee exist but are refused with not_available for community plugins, because there is no plugin memory or evidence route yet. Agent tools are for official plugins only.

memory

Notifications

Show toast notifications to users from plugin actions. Success, warning, error and info variants.

notifications

Plugin storage

Server-backed key/value storage namespaced to your plugin, enforced fail-closed in the sandbox like notifications and network.

storage

Four packages

Everything you need, nothing you do not.

Each package has a single responsibility. Use them together or individually.

@quoxai/create-quox-plugin

Scaffolder

Project generator with 8 templates (basic, monitoring-dashboard, fleet-management, service-bridge, ui-feature, enterprise-extension, specialist-agent, agentic-team). Can also scaffold a specialist-agent plugin from an MCP server.

npm, 0.4.1

@quoxai/quox-plugin-sdk

Runtime and types

TypeScript types, registerPlugin and getQuox() for window.quox, plus a mock window.quox for tests.

npm, 0.4.1

@quoxai/quox-plugin-vite

Build tooling and CLI

Vite plugin that externalises shared deps, bundles the qx CSS, runs the sandbox dev preview, and ships the quox-plugin CLI (validate, keygen, sign).

npm, 0.4.1

@quoxai/eslint-plugin

Lint rules

Flags code the sandbox will not allow: host-only globals and browser storage used as the primary store.

npm, 0.4.1

Source: github.com/quoxai/quox-plugin-sdk, Apache 2.0 licence. The packages are unscoped on npm, not under @quoxai or @quox.

Architecture

What you build and install.

The build writes a bundle and a stylesheet; your manifest stays at the project root. QuoxCORE runs the bundle in a sandboxed frame and registers its routes and sidebar entries.

manifest.json: plugin metadata, permissions, sidebar config
dist/plugin.esm.js: compiled ESM bundle, React externalised
dist/plugin.css: your styles plus the bundled qx design-system CSS
dist/signature.json: Ed25519 signature over plugin.esm.js

my-plugin

my-plugin/
├── manifest.json
└── dist/
    ├── plugin.esm.js
    ├── plugin.css
    └── signature.json

Shared dependencies

// QuoxCORE provides these globally:
window.__quoxSharedDeps = {
  React,
  ReactDOM,
  ReactRouter
};

// Your plugin imports work normally.
// The Vite plugin rewrites them
// at build time.

Where your plugin fits

Four kinds of add-on, clearly labelled.

Quox has four kinds of add-on, and no one should have to guess which is which. Plugins you build with this SDK are Community plugins, credited to you and labelled unverified unless the installing org trusts your key.

Core

bundled · always on

Ships inside every QuoxCORE install. Always present, no purchase, and it cannot be removed. QuoxCORE itself is the platform runtime these run on, not a plugin.

e.g. QuoxMemory, governance

Installable

marketplace · free or licence key

Added from the marketplace when you want it. Some are free, some unlock with a licence key. Non-core, toggle on and off.

e.g. Wazuh SIEM, Prometheus, GitHub

Quox-installable

install · a real deploy

Quox-made, but a genuine install: a daemon, service or desktop app you set up, not a one-click key unlock.

e.g. QuoxAgent, QuoxBastion

built with this SDK

Community

marketplace · third-party

Built by an outside developer and credited to its author. Runs in an isolated sandbox. The marketplace catalogue is not open yet, so today you install it on your own instance.

build, sign and install today

Listing and selling are not open yet. There is no marketplace submission flow for community plugins today. Developer path

Security

Signed, scoped and sandboxed.

Community plugins run in an isolated frame with explicit permissions.

Ed25519 signing

An org admin registers the Ed25519 public keys of the authors it trusts. Once an org has a trusted key, QuoxCORE accepts only bundles carrying a valid signature from one of them.

Generate a key pair with npx quox-plugin keygen
Sign with npm run sign after every build
The signature covers plugin.esm.js only
A modified bundle fails with digest_mismatch

Permission model and sandbox

The plugin runs in an iframe with sandbox="allow-scripts", an opaque origin and connect-src 'none'. It cannot make network requests, read the host page or touch other plugins. Everything goes through window.quox.

Seven permissions, declared in the manifest and reviewed at install
No host components, contexts or stylesheets inside the frame
Storage is namespaced to your plugin
Backend calls are confined to your plugin namespace; absolute URLs and traversal are refused
Storage, network and notifications are enforced fail-closed; memory and aee are refused as not available
quox.fetch reaches your backend only on instances that run plugin backends (managed Quox today)

sidebar

Add items to the sidebar navigation.

storage

Server-backed key/value storage scoped to your plugin.

network

Enforced. Call your plugin backend through quox.fetch, where the instance runs plugin backends.

memory

Not available. Refused with not_available for community plugins.

notifications

Show toast notifications.

aee

Not available. Refused with not_available for community plugins.

tools

Official plugins only. Community plugins cannot register tools.

Plugin API

One object, a small surface.

Plugins reach QuoxCORE through window.quox, a promise-based API bridged to the host over postMessage. Get it with getQuox(). If an API is not on the list, it does not exist for a community plugin.

Every call can fail, so render the error. The host refuses a call the manifest does not have permission for.

storage: server-backed, namespaced to your plugin ID
fetch: relative paths to your own backend namespace
memory and aee: present, refused with not_available for community plugins
navigate, notify, getUser and onEvent

getQuox()

import { getQuox } from '@quoxai/quox-plugin-sdk';

async function runScan() {
    const quox = getQuox();

    // Storage
    await quox.storage.set('lastRun', Date.now());

    // Your backend (coming for community plugins)
    const res = await quox.fetch('status');
    if (!res.ok) return;

    // Notifications
    await quox.notify('Scan complete', 'success');
  }

Where it stands

What's proven, what's still beta.

The SDK is published at 0.4.1. This is what is solid, what is partial, and what does not exist yet.

Live and proven

Four packages are published to npm under the @quoxai scope, at version 0.4.1, each with npm provenance from GitHub Actions, and the repo is public under the Apache 2.0 licence
A clean install from the public registry scaffolds, builds, validates and signs all eight templates
The scaffold, build, validate, sign and install flow is the documented path, and npm run dev simulates the same sandbox locally
Community plugins run in an opaque-origin iframe with no direct network and talk to Quox only through window.quox
Ed25519 signing is real and binds the manifest, the bundle and the stylesheet: once an org has trusted keys, only packages with a valid signature from one of them install, and an org admin can revoke a key or a package

Beta and partial

The dev preview is an approximation, not a QuoxCORE instance: confirm storage and notifications by installing the built plugin
Community plugin backends run only on managed Quox instances, and only with a signature v2 from a trusted, unrevoked key and a digest-pinned image; self-hosted installs from the public release do not run plugin backends yet
A running backend is fenced to the gateway and the public internet; the fence is reapplied when the instance starts, but a full host reboot has not been tested, and plugin networks are IPv4 only
window.quox.memory and window.quox.aee are refused with not_available for community plugins; agent tools from a backend load for official plugins only

Known gaps

There is no marketplace submission or listing flow yet: the catalogue is not open to community plugins
Revocation is per organisation: there is no key expiry, rotation endpoint or revocation list shared between instances
Official, first-party Quox plugins are a separate path with a wider surface and are not built with this SDK
The SDK is version 0.4.1: expect the API surface to keep moving

Get started

From scaffold to installed.

Scaffold a new plugin, install dependencies and start the dev preview. Then build, validate, sign and install. These commands run from the public npm packages.

Create a new plugin

# Scaffold a new plugin project
npx @quoxai/create-quox-plugin my-plugin

# Install dependencies
cd my-plugin
npm install

# Start the dev server
npm run dev

Build, sign and install

# Build and check the bundle
npm run build
npm run validate

# Generate a signing key (once)
npx quox-plugin keygen --out .keys

# Sign the bundle
npm run sign

# Install (org admin)
quox plugin install \
  --manifest manifest.json \
  --bundle dist/plugin.esm.js \
  --css dist/plugin.css \
  --signature dist/signature.json

Or install from the dashboard plugins page. An org admin trusts your public key first with quox plugin trusted-keys add --label <l> --public-key <hex>. Source on GitHub, Apache 2.0.

packages4permissions7signingEd25519licenceApache 2.0version0.4.1

Start building

Your plugin, on every QuoxCORE.

The SDK is on npm and the source is public. Read the docs, then scaffold your first plugin.

Read the docs Developer path

Go deeper

What it is, where it lives, when to reach for it

Four steps from idea to installed plugin.

Extend QuoxCORE in six directions.

Sidebar views

Your own backend

Your own agent

Memory and evidence (not yet)

Notifications

Plugin storage

Everything you need, nothing you do not.

@quoxai/create-quox-plugin

@quoxai/quox-plugin-sdk

@quoxai/quox-plugin-vite

@quoxai/eslint-plugin

What you build and install.

Four kinds of add-on, clearly labelled.

Core

Installable

Quox-installable

Community

Signed, scoped and sandboxed.

Ed25519 signing

Permission model and sandbox

One object, a small surface.

What's proven, what's still beta.

From scaffold to installed.

Your plugin, on every QuoxCORE.

Related documentation.