Plugin Development
Plugins provide instructions, tools, incoming messages, agent runtimes and Capsule views. Operational programs, credentials and file access stay on the selected Desktop / Runner; declared UI modules execute in the current client. The service manages accounts, installations, permissions and routing.
Where to Start
- To run your first simulated experiment, follow the OpenSDL desktop experiment quickstart.
- Create your first plugin: follow the Quickstart to create an independent project with
liyan plugin init, build, import, and callplugin.ping. - Check interfaces and limitations: read capability types below.
- Connect tools or diagnose execution: read development and debugging.
- Change the host: consult runtime and security and the data model.
Third-party local tools can be developed, validated, packed, and imported on the selected device through common configuration and execution. This flow requires no PR, host integration, official catalog entry, or official CI. Feishu provides a business-tool reference; science-data provides installed Capsule client modules. The Quickstart distinguishes package validation, activation confirmation, and actual calls. Public download publication, new platform message adapters, and new Agent Runtimes remain future work.
Basic Concepts
For a plugin that reads GitHub issues, the author declares a tool. The user installs a version, configures a GitHub identity on their Desktop, and permits reads. LiyanLabs checks these conditions and sends calls to that device.
Releases and capabilities are author declarations; permissions are user grants. Declaring a tool does not authorize its use. Local providers without external accounts still need a real empty profile saved natively; never invent an account, connection or configuration version.
A digest is a SHA-256 content checksum. A revision tracks state changes. A device generation rejects requests from old connections. A receipt records which operation the device completed. These checks are not additional categories of user permission.
Name, Identity, and Icon
Authors declare presentation in plugin.json. Import reads it from the project directory or package.tar.gz; users do not enter an identity or name, or upload a separate icon in the installation form.
Names and icons belong to a release. An omitted display name shows the identity; an omitted icon uses the builtin brand or generic mark. Increment the version and repack after changing them. See Quickstart for image and path limits.
Capability Types
Local providers have no language allowlist, but must implement private bootstrap, stdio MCP initialization, complete discovery and calls. Go is the supplied template. Bare Python/Node.js scripts have no automatic interpreter/dependency packaging; deliver a directly executable artifact. Names, input schemas and read-only classifications must match declarations. Provider labels may repeat across installations, but must be unique within a package.
Plugin chat currently uses the local-provider connector. A root mcp.json HTTP declaration can be parsed, but this does not establish working remote MCP calls. Channels support existing Feishu/GitHub contracts; External runtime declarations retain builtin Claude Agent, OpenClaw and Hermes adapters, but chat takeover is not connected. Codex exposes ordinary asynchronous coding tools through a local provider. New platforms still require host implementation.
Science-data ships its provider and Web/native Capsule entries as one plugin. UI executes directly in the client JavaScript realm, without an isolation sandbox. apply(ctx, config) registers views and shared resources; business calls use only the installation's authorized read-only tools. See plugins/science-data/client/.
OpenSDL also ships as one complete plugin: its native runtime, official icon,
Simulation, Laboratory devices and Experiment workflow Capsule views, with
separate Web/Desktop and native mobile entries. The closed nativeRuntime: "opensdl/2" declaration
retains its dedicated CLI/gRPC adapter; it does not fabricate a stdio provider
or open arbitrary runtime protocols to third-party authors. General third-party
tools use the ordinary local-provider contract. UI loads only for a confirmed,
enabled, authorized installation on its selected online device. Without it,
no Capsule view registers, polls devices or acquires scene assets.
General computers/sandboxes management remains in the host.
Modules read declared resources through ctx.files.read, using 256 KiB ranges
and a complete digest check. Each module allows at most 128 files, 8 MiB per
file and 32 MiB total. OpenSDL configuration, runtime, device and camera calls
use its exact installation's closed interface; writes follow permissions and
host confirmation. See plugins/opensdl/README.md for build and acceptance.
Third parties deliver a target-matched directory or package.tar.gz. Import registers a private release; installation, confirmation, configuration and a real call remain separate steps. First-party downloadable runtimes are build-pinned and acquired on demand, rather than preinstalled in Desktop. Public marketplaces, self-service remote publication and automatic device migration are unavailable and are not local-development prerequisites.
Inspect Tools Provided to AI
Open a plugin's details on Web, Desktop, or mobile and select Tools provided to AI → View tool list to expand or collapse the tools declared by that release. The badge counts individual tools, rather than provider processes or capabilities; one provider can supply several tools.
Each entry shows its original name, purpose, and either “Declared read-only” or “May make changes.” The unchanged CLI template, for example, declares plugin.ping. These fields come from the author's toolCatalog; a read-only declaration does not replace user permission or a real invocation check.
Published declarations can be previewed before installation and while the selected device is offline. Opening the list reads release metadata without starting a provider, contacting Runner, or granting permissions. Actual AI calls still require an enabled installation, completed configuration, the bound online device, and current permission.
Details load on demand and reuse the account-and-release query cache. A failed load offers Retry. An undeclared catalog shows “Count not declared” and an explanation; it must not be treated as one tool or zero tools. This preview is not a live list of tools authorized in the current conversation.
First-party Plugins
The catalog comes from service/pkg/core/plugin/builtin/catalog.json; OpenSDL has its release definition in service/pkg/core/plugin/packageartifact/opensdl.json. Downloadable first-party capabilities share the desktop/scripts/plugin-release-registry.mjs build path. Catalog visibility does not establish installation or device readiness. The selected Runner acquires the pinned Codex CLI and helpers on demand; the user explicitly authorizes its login directory. OpenClaw, Hermes and Zotero use existing services. Catalog installation and local package import share the same device authorization and execution boundary.
Install and Run
- Select an online Desktop and release. Desktop uses its own Runner; Web / Mobile select an online Desktop.
- Install. Runner verifies local files, the service saves its receipt, then confirms enablement.
- Save a real device profile for local providers, including empty configurations, and review permissions. A packaged setup Skill guides AI assistance; the user completes native confirmation. Initial install retains enable intent; choosing Later does not disable it.
- Check configuration completion and live device/provider health.
- Invoke. LiyanLabs rechecks version, permissions, and device status before the bound Runner executes.
Enabled means the package has execution permission. Setup complete means required configuration and permissions are saved. Healthy means the device or provider is available now. Check each separately. Update and repair require re-enabling.
An offline selected device makes the capability unavailable. There is no automatic device switch, server execution, or queue waiting for reconnection. See development and debugging for recovery.
Source Basis
Implementation checked on 2026-10-17, including OpenSDL 0.5.0's installed native runtime and client modules. This chapter describes current source contracts rather than availability in older installers; Quickstart checks CLI commands and generated template files first. The OpenSDL package pins its upstream source in service/pkg/core/plugin/packageartifact/opensdl.json.
- Author contracts and CLI:
runner/crates/liyanlabs-plugin/,runner/crates/liyanlabs-cli/src/plugin.rs. - Installation and model tools:
service/pkg/core/plugin/packagecommand/,service/pkg/worker/wire_toolprep_plugin.go,service/pkg/worker/chatdriver/pluginsurface/. - Tool previews:
service/pkg/web/views/plugins/projection.go,frontend/shared/src/hooks/usePluginToolDetails.ts, Web'sPluginToolsCard.tsx, and mobile'sPluginToolsNative.tsx. - Configuration and processes:
desktop/electron/src/plugins/device/,runner/crates/liyanlabs-runner/src/plugins/provider/. - Capsule:
service/pkg/core/plugin/clientmodule/,frontend/shared/src/core/pluginClientModules/. - First-party releases:
desktop/scripts/plugin-release-registry.mjs,.github/workflows/plugins.yaml. See the complete source map.