Choose your tools — PexarBolt Docs

Bolt Plugin ToolsRead Connect Codex or Claude Code to Studio for setup, the local engine and model data flow, account and billing ownership, and the applicable provider conditions. Official local integration support is distinct from certification or permission for a commercial/hosted deployment.Choose your workspace

Tool

Best for

Get it

PexarBolt Plugin Studio (desktop app)

Desktop creation, previews, simulator, real Dock testing and export

Desktop download

Standalone CLI / MCP / JavaScript

Terminal workflows and your own assistant or automation

Tools archive below

PexarBolt consumer app

Installing, configuring and running finished plugins

Installation guide

The desktop app and standalone tooling have separate downloads. Exported .boltplugin files work with the consumer app.Platform publishing: export a source-bearing .boltplugin with bolt-plugin package DIRECTORY OUTPUT.boltplugin or MCP plugin_package. Include editable implementation files, original source/build files for compiled projects and license notices. Sign in to the website and upload the exported package in My plugins; Account Settings does not require developer tokens for this workflow. The website accepts only .boltplugin; complete MIT consent and independent review there. Legacy submission exports are private archive workflows. See publishing.Create, edit, test, preview and export PexarBolt Dock plugins in your own editor or AI tool. No PexarBolt App, account, source checkout, device or API key is required for the development workflow.Requires Node.js 22 LTS. Installation downloads Electron for the real isolated browser sandbox. Checks, screenshots and preview windows require a graphical desktop (Linux CI can use Xvfb). Electron is a runtime dependency, not the PexarBolt App. The pinned Electron installer's ZIP extraction fails under Node 26 in our clean-install check; use Node 22 for installation and commands.Device-direct HTTP/WebSocket sources support pathConfig for a saved request path and queryConfig for up to 16 query names mapped to ordinary scalar settings. The App resolves and saves them on the Dock for requests after USB disconnection and restart. Referenced setting changes require renewed device consent and synchronization. Use the updated SDK and tools; existing data-source firmware is sufficient. See Connect to data for declaration examples, encoding and limits.DocumentationThe distribution carries its own documentation in dist/context: contract.md (the normative plugin contract), this README, agent-service.md (App Agent service connection and debugging), plugin-optimization.md (resource rules, live verification, Dock reconnection and cameras), plugin-filesystem-watch.md (external storage), plugin-media.md (photos, video, frames and HID) and device-data-sources.md (device-direct HTTP/WebSocket cards). dist/skill/pexarbolt-plugin contains the authoring skill and dist/context/sdk the SDK source. MCP plugin_read returns the SDK, contract and skill as context.Install From A Distributionnpm install /absolute/path/pexarbolt-plugin-tools-0.1.0.tgz npm rebuild electron npx bolt-plugin scaffold ./my-plugin npx bolt-plugin check ./my-plugin npx bolt-plugin preview ./my-plugin npx bolt-plugin screenshot ./my-plugin ./preview.png npx bolt-plugin package ./my-plugin ./my-plugin.boltpluginThe npm registry package has not been published. Use the generated tarball. Keep the plugin in a dedicated source directory; install tooling in its parent workspace. Do not put node_modules, editor configuration, build scripts or archives in the plugin source. Edit source with any editor, then reload the preview. validate is an alias for check. Scaffolding and export refuse existing destinations.npm rebuild electron completes the runtime download when the package manager blocks dependency install scripts. Follow your package manager's local script policy when using pnpm or another installer.App Agent ServiceFor creation through installation in an already-running PexarBolt Plugin Studio, enable Agent service in the Studio workspace and choose generic HTTP or stdio MCP configuration. The page exposes the endpoint and bearer authentication, and displays an Example prompt after enabling. Copy prompt includes the selected configuration and actual access token, plus instructions for your Agent to connect, learn the SDK and develop the plugin. The on-screen token is masked by default. Client-specific examples such as dsh are in the connection guide. The App bundles its own stdio relay, requiring no separate CLI installation. Its 18 tools cover multiple persistent projects, SDK/Skill/CLI guidance, editing, fixture checks, screenshots, packaging, App import and authorized runtime/device operations. Start with plugin_context, then read its sdk and skill sections. This tool also supports clients that do not bridge MCP resources or prompts. The connection and debugging guide is included at dist/context/agent-service.md. When the App window is closed it hides to the system tray and keeps the App MCP endpoint and enabled plugins available; Quit PexarBolt Plugin Studio in the tray menu stops services. Standalone CLI and stdio MCP processes keep their own lifecycle.Use plugin_create or plugin_edit_installed, then plugin_read; pass projectId and expectedRevision to source/check/preview/export/import tools. plugin_install imports the checked version into the App. plugin_runtime reports permissions/configuration/device next steps and can start/stop already-authorized plugins or install/open them on a compatible Dock. start enables the plugin (runtime: 'standby', available on the Dock); the host runtime itself starts when the Dock or simulator opens the plugin and stops after 60 seconds hidden. New permissions, secrets and photo-folder access remain in App Settings/Permissions. Release unused previews with plugin_release_preview. The service defaults off, binds to localhost and requires the bearer token from the copied configuration.The CLI can also bridge to the App: configure your MCP client to run bolt-plugin connect --url http://127.0.0.1:PORT/mcp with PEXARBOLT_MCP_TOKEN in its environment. This command needs the running App service. The standalone commands below retain their independent sandbox.Standalone MCPAdd this standard stdio MCP server configuration to an MCP-capable tool, using absolute paths to your Node executable, installed CLI and plugin directory. The directory may be absent initially; plugin_scaffold creates it.{ "mcpServers": { "pexarbolt": { "command": "/absolute/path/to/node", "args": [ "/absolute/path/to/workspace/node_modules/@pexarbolt/plugin-tools/dist/cli.mjs", "mcp", "--directory", "/absolute/path/to/workspace/my-plugin" ] } } }The server uses the official MCP TypeScript SDK and stdio transport. Each server is scoped to one editable plugin directory. Tools: plugin_scaffold, plugin_read, plugin_write, plugin_check, plugin_event, plugin_screenshot, plugin_preview, plugin_package, plugin_submission. plugin_read includes SDK source, the full current contract, instructions, the plugin development skill in context.skill, and a source revision. Supply that revision to plugin_write. bolt-plugin://context is also an MCP resource after scaffolding.The shared skill includes Design Defaults for short prompts: infer an appropriate visual composition, hierarchy, palette and controls from the task, preserve explicit style preferences, and inspect actual screenshots before export. It covers Dock geometry, readable typography, stable changing values, meaningful states and subject-specific composition cues. MCP clients receive these instructions on connection and through plugin_read; tools using the JavaScript API should supply read().context.skill with the SDK and contract to their model. Visual quality is reviewed from rendered output, separately from package validation.Authoring sequence: read the current contract, edit the source, check, exercise representative events, inspect the PNG screenshot, then export. Source changes invalidate prior checks. Export always checks again and finalizes hashes in a private snapshot. The editable source keeps its BUILD markers. Standalone MCP tools do not install plugins or grant live permissions.JavaScript APIimport { scaffold, PluginSession } from '@pexarbolt/plugin-tools'; await scaffold('./my-plugin'); const plugin = new PluginSession('./my-plugin'); try { const source = await plugin.read(); await plugin.write([ { path: 'host.mjs', encoding: 'utf8', content: source.files['host.mjs'].content } ], source.revision); await plugin.check(); await plugin.event('increase', null); const png = await plugin.screenshot(); // {data: base64, mimeType: 'image/png'} await plugin.package('./my-plugin.boltplugin'); } finally { await plugin.close(); }The separate @pexarbolt/plugin-sdk distribution provides the public runtime types and browser-safe validators. Plugin host modules still export activate(ctx) and use the injected SDK; package output must be self-contained browser ESM with relative imports. Bundled SDK source and contract are in dist/context for tools without MCP support.The distribution also contains dist/skill/pexarbolt-plugin for tools that load agent skills, plus source examples in dist/examples: sdk-showcase, control-gallery, music-lyrics, video-player, device-data-card (HTTP and immediate WebSocket JSON) and stock-monitor (device-direct HTTPS quotes). Copy an example to an editable plugin directory and check it using the same CLI. Example BUILD hashes are finalized on export.Image AssetsUse local file paths for every image, including PNG. The tooling reads, resizes and compresses the image, then writes an actual PNG asset into the plugin. Agents do not need to encode or transmit base64.bolt-plugin image ./my-plugin ./cover.jpg assets/cover.pngawait plugin.importImage('./cover.jpg', 'assets/cover.png', source.revision); // Equivalent API/MCP file edit (MCP also requires expectedRevision): await plugin.write([{ path: 'assets/cover.png', source: '/absolute/cover.jpg' }]); const { files, assets } = await plugin.read(); // text files and image metadataSupported inputs: PNG, JPEG, WebP, GIF, BMP, AVIF and SVG. They become static PNG; animated inputs become a single static frame. Use the runtime frame API for animation. Sources must be local to the machine running the tools, up to 10 MiB, 8192 pixels per side and 16 megapixels per image; a write allows up to 10 MiB and 32 megapixels combined. Unsupported or invalid images return a conversion diagnostic and leave the source unchanged.Include image projection bounds and the manifest icon in the same write for sizing. Images preserve aspect ratio, never upscale and fit the referenced bounds up to 854x480; icons are transparently padded to a square up to 256x256. Lossless PNG compression and further downscaling keep all declared assets within 1 MiB compressed and 4 MiB decoded. Remove unused existing declarations when they leave no room. Output images lists final PNG paths, dimensions and bytes; non-PNG names and their projection/icon references are updated automatically, together with assetHashes.read() / plugin_read omit binary contents by default and expose their metadata in assets. Existing images remain in the project during text edits. Explicit read({includeBinary:true}) / plugin_read({includeBinary:true}) and base64/Data URL writes remain compatibility options. Standard MCP screenshot image responses still use the protocol's binary encoding. Images placed directly in the source directory are also normalized by standalone check/package in a private snapshot; editable originals are preserved. Exported archives contain optimized PNG bytes and finalized hashes, with no dependency on the original source path.Checks And Simulated CapabilitiesCLI check/package and MCP plugin_check return verification: {mode:'fixture',liveVerified:false,optimizationReview:'required',policyVersion:2,requiredLiveChecks:[...]}. Passing startup and sample controls does not verify live performance or cleanup: read plugin_read.context.optimizationPolicy (or PluginSession.read().context), review the policy and report pending live checks. Inspect runtime status and logs in the App before changing plugin code for unavailable/runtime_fault.Previews never touch the developer's hardware or storage:

context.networkAccess compares Desktop ctx.http with Dock-fetched sources, which reach LAN hosts (allowPrivateNetwork) and public HTTPS/WSS without the App but are read-only.

External storage (fs.watch) uses an isolated virtual volume with Documents, status.json and Documents/report.csv; context.filesystemWatch describes support. Transfers (fs.transfers) emit simulated progress and completion, reads (fs.read) return virtual contents, subscribeIo returns fixed simulated rates, and ejection (fs.eject) returns simulated:true, sends unmounted and invalidates the old mount. No command ejects a real disk.

HID (ctx.hid.consumer, ctx.hid.keyboard, ctx.hid.mouse) is simulated without sending input to the computer.

Dock port status returns a fixed 22-port sample; HTTP, media, Agent and photo operations use fixture adapters. Canvas rendering runs in the real sandbox.

Real behavior requires installation in a compatible App, granted permissions and, where relevant, a connected Dock with updated firmware. The contract's sections define the live requirements for each capability.Runtime BoundaryCLI check, API PluginSession.check() and MCP plugin_check report deviceExecution: 'native' | 'host'. Native projections (including packaged images, native image animations and fullscreen) run on the Dock after installation without the App. Declared HTTP/WebSocket sources also run directly on updated firmware when all bindings use sources.<id> and device access is authorized. Other bindings, events, widgets, streams and host permissions require the Desktop host runtime. Install on device persists the launcher entry independently of Enable. An enabled host plugin is available on the Dock; the App starts its runtime when the Dock or simulator opens it and stops it after RUNTIME_LIFECYCLE.idleStopMs (60 seconds) hidden, so persist resumable state with ctx.store and pause hidden work with ctx.view. Standalone previews are always visible (ctx.view.visible === true); test hidden behavior in the App. PluginSession.read().context.runtimeLifecycle and MCP plugin_read.context.runtimeLifecycle expose the interval. Disabled or unstartable host entries show a waiting dialog on the Dock until they become available. The toolkit still uses its sandbox for authoring checks and does not add JavaScript execution to firmware.The toolkit bundles the client's actual package validators, Electron sandbox, fixture adapters, control checks and Dock renderer from the same source revision. It does not launch the client, read its profile or need a firmware checkout. Browser preview includes touch, dial actions and reload. PNG screenshots use the same fonts, icons and renderer as the App. Sample HTTP, media, agent, photo and HID operations follow the existing fixture semantics; Canvas rendering runs in the sandbox.The runtime has no fixed concurrent-instance limit. Close unused preview sessions to release resources; sandbox isolation, per-plugin traffic limits, operation queues and watchdog timeouts remain in effect. LIMITS.instances and the App service's capacity.limit are null.A passing check verifies package acceptance and the exercised sample interactions. Live accounts, OS/media integrations, native SDL and physical device operation still require their compatible host and authorizations. This release separates plugin authoring from the App; it does not replace the device runtime. Import the exported .boltplugin into PexarBolt for installation and live device testing.Build In This Repositorypnpm install pnpm -C packages/plugin-sdk pack --pack-destination ../../.cache/plugin-distributions pnpm -C packages/plugin-tools pack --pack-destination ../../.cache/plugin-distributions pnpm --filter @pexarbolt/plugin-tools type-check pnpm --filter @pexarbolt/plugin-tools test pnpm --filter @pexarbolt/plugin-tools test:standaloneOnly maintainers need this monorepo to build distributions. The build bundles shared implementations and assets, with Electron as the only external runtime dependency. The distribution smoke test installs into a fresh directory outside this workspace, creates a plugin, tests CLI/API/MCP, edits and rechecks it, inspects a real PNG and exports an installable archive.AI Provider BoundaryThe standalone CLI and MCP server do not run an AI model. Use them from Codex, Claude Code or another MCP client with that client’s own authentication. For conversations inside Plugin Studio, Vibe can select the locally authenticated official Claude Code CLI; see "Local Claude Code" in the Plugin Studio repository's docs/vibe-plugin.md. This adds no standalone commands, tools, runtime permissions or API-key requirement. Both MCP distributions continue to carry the same bundled authoring skill and contract.Official capability examplesThe distribution includes 26 editable plugins under dist/examples/. Browse dist/context/example-catalog.json for a capability-to-example map, setup steps and live dependencies. Copy an example to a new source directory, then use bolt-plugin check and bolt-plugin preview. The examples cover every runtime permission, plus controls, media rendering, visibility and native Dock data. Live services and hardware still need independent verification.Photo and video workflowsdist/examples also includes Media Verify, Cut Desk, Cull Desk, Shoot Planner, Focus Pull and Frame Composer. They combine creator workflows with setup instructions, pure models, clear hardware/app boundaries and responsive Dock interfaces. Focus Pull uses an on-demand Canvas diagram; Frame Composer overlays framing guides on authorized local photos. The catalog's collection distinguishes creator tools, everyday tools and developer references. There are 26 development example projects; all original capability examples remain available. Coverage counts describe permission and feature groups, not an exhaustive API-branch or hardware-validation suite. See dist/context/official-plugin-examples.md for the audit boundaries.The Dock collection includes Link Lens (negotiated-link comparisons), Desk Ready (saved connection profiles), Dock Health and Transfer Watch. Browse /dock on the developer website or find the dock collection in dist/context/example-catalog.json. All hardware readouts require a connected Dock and the running Desktop App; samples are not hardware validation.Dock Backup adds App-owned, permission-scoped background copying and SHA-256 destination readback. It requires Desktop App 0.3.0 and separate native folder/automation authorization. See plugin-backup.md for supported storage, recovery and live-test boundaries.Plugin author attributionAdd optional author to plugin.json using the actual author's display name (up to 80 characters, non-empty, without control characters). Studio displays this name in project cards and details. Existing packages without the field stay compatible and show an unspecified author. Package attribution is separate from the verified website publisher. Existing source-write CLI/MCP tools preserve this metadata; no runtime permission or new tool argument is required.Navigate between pagesUse Projection.pages and root-node page tags for Dock-local left/right/up/down swipes in both Host-connected and independent native plugins. Optional read-only pageChange reports {from,to,direction} to Host. Requires pages.swipe.v1 firmware. See local page navigation, the page-deck example and SDK types.