Plugin Author Handbook

A plugin is a signed, immutable package of plain JavaScript that Arvexa OS executes in an isolated runtime on your organization's behalf. It declares up front exactly what it wants to observe and call; anything it did not declare is denied, and anything absent from the published catalogs is denied even if it was declared.

This handbook is the authoring path end to end. Each following guide covers one stage, and they are meant to be read in order the first time.

• Plugin Project Structure — the five things a package may contain and nothing else
• Plugin Manifest — every field of plugin-package-1.0
• Permissions, Roles & Audiences — scopes, actor roles, and who sees a plugin
• API & Hook Catalogs — what a handler may call and what may trigger it
• Plugin Runtime & Limits — what exists inside the sandbox, and the budgets
• Testing Plugins — the host harness, its determinism replay, and local preflight
• Plugin Security — the scan gate, secrets, and webhook verification
• Upload, Install & Publish — the lifecycle and the gates between each step
• Plugin Troubleshooting — exit codes and the failures authors actually hit

Toolchain. Two workspace packages: @arvexa/sdk (contract types, validators, a typed Developer client, webhook verification) and @arvexa/cli (the arvexa command). Both are distributed with the monorepo in V1 — publication to public npm is explicitly out of scope, so install them as workspace dependencies rather than from a registry.

OpenAPI remains the source of truth for every HTTP schema. The SDK generates nothing from it and hand-maintains no copy of a request or response shape; arvexa openapi pull fetches GET /api/docs-json for your own tooling, and the API Reference in this portal is rendered from the same document.

Both Developer Platform flags default to false. DEVELOPER_PLATFORM_ENABLED gates every Developer/Plugin write and every developer.* event; DEVELOPER_PLATFORM_LIVE_EGRESS gates LIVE sandbox behavior. Only the exact string "true" enables either. On a host where the first flag is off, every write fails closed and nothing is recorded — that is the intended state, not a misconfiguration.

The first commands need no credential. arvexa plugin validate, arvexa plugin pack, and arvexa plugin test --preflight-only are fully offline. Start there; a Developer API key is only needed once you have a package worth uploading.