Skip to content

How to Develop Extensions

Extensions are installable packages built with the Zelos SDK. They connect devices, decode protocols, and add custom UI to Zelos. Users install an extension from the marketplace instead of writing integration code, then stream, visualize, and control their systems right away.

This page is the starting point. It explains what an extension can contribute, how identity works, and the workflow from a new project to a marketplace release. Each step links to a page with the details.

Choose What the Extension Contributes

An extension contributes an agent runtime, a tab, panels, or any combination. One extension.toml declares all of them.

Agent runtime Tab Panel
Runs As a Python process under the Zelos Agent As a sandboxed web page in a desktop app tab As a sandboxed web page in a layout panel
Built with Python and zelos-sdk TypeScript, React, Vite, and @zeloscloud/app-extension-sdk The same web project as a tab
Good for Device drivers, protocol decoders, data streaming, actions Custom dashboards and workflow UI inside Zelos A view of your data beside plots and tables
Declared as [agent] [app] with tab [[app.panels]]
Guide Develop Agent Extensions Develop App Extensions Develop Panel Extensions

What Extensions Can Do

Acquire data:

  • Decode bus protocols such as CAN and CAN FD, Modbus, MQTT, OPC UA, Ethernet with Protobuf, and serial.
  • Talk to test equipment such as HIL systems, data acquisition hardware, and oscilloscopes.
  • Stream from custom hardware and sensors.
  • Parse proprietary file formats and logs.

Control devices:

  • Run commands on hardware through actions.
  • Automate test sequences.
  • Change parameters while the system runs.

Process data:

  • Transform and filter data streams.
  • Compute derived signals.
  • Combine signals from several sources.

Extend the app:

  • Add a custom tab with its own UI that reads signals, runs actions, and writes .trz files through the app bridge.
  • Add panels that users drop signals on and arrange in a layout.

Create Your First Extension

In the Zelos App:

  1. Open the Extensions view.
  2. Open the Marketplace section menu and select Create Extension.
  3. Pick what the extension adds: Agent, Tab, Panel, or any combination.
  4. Enter an Extension Name in kebab-case, for example sensor-monitor, and an optional Description.
  5. Click Create Extension, then pick the folder to create the project in.

The app generates the project from the official templates and installs it locally as local.<name>.

From the CLI:

zelos extensions create my-agent-extension --with agent
zelos extensions create my-dashboard --with tab
zelos extensions create probe --with agent,panel

--with is required. It names the parts: agent, tab and panel, comma-separated. The CLI also installs the new project locally. See each guide for the options.

Development Workflow

  1. Create a project, as above. Run just install in it to install the dependencies.
  2. Develop it. just run runs the agent runtime. just dev serves tabs and panels in a browser.
  3. Run it inside Zelos. create already installed it locally. After a web change, run just build and reload. After any change to extension.toml, such as a new panel, run zelos extensions install-local . again.
  4. Configure the agent runtime through a JSON Schema form. See Configuration.
  5. Package it with just package. See Package and Publish Extensions.
  6. Release it with just release <version> and git push --follow-tags. The generated workflow builds the archive and creates the GitHub release.
  7. Publish the repository on marketplace.zeloscloud.io.

Reference

Page Covers
Manifest Reference Every extension.toml field, defaults, and validation errors
Extension Configuration config.schema.json, form widgets, load_config()
Package and Publish Extensions Archives, size limits, platform-specific builds, releases, the marketplace, updates
Extension Runtime and Lifecycle Install, Python environment, environment variables, logs, shutdown, crashes, security
Develop Agent Extensions The Python project, entry point, local testing
Develop App Extensions The web project, the tab, the bridge SDK, the sandbox
Develop Panel Extensions Panels: the manifest entry, the panel hooks, data and options

Extension Identity

Zelos derives every extension ID. Do not set an id field in the manifest.

Marketplace extensions use owner.repo, from the GitHub repository. For example, acme/canbus-decoder becomes acme.canbus-decoder.

Local extensions use local.<slug>, from the manifest name. For example, name = "Sensor Monitor" becomes local.sensor-monitor. Zelos uses the project directory name only when the name produces an empty slug.

ID Rules

An extension ID has exactly two parts separated by a dot. Each part:

  • Uses only lowercase letters, digits, and hyphens.
  • Does not start or end with a hyphen.
  • Is not empty.
ID Valid
acme.canbus-decoder Yes
john-doe.mqtt-bridge Yes
local.sensor-01 Yes
Acme.CANBus No: uppercase letters
acme.-canbus No: leading hyphen
acme..canbus No: empty part

The marketplace does not rewrite repository names. Name the repository with lowercase letters, digits, and hyphens so its ID is valid.

Local ID Slugs

For a local install, Zelos builds the slug from the manifest name:

  1. Convert to lowercase.
  2. Replace each run of characters other than ASCII letters and digits with one hyphen.
  3. Trim hyphens from the ends.
  4. Prefix with local..
name = "Sensor Monitor"   -> local.sensor-monitor
name = "My Extension v2"  -> local.my-extension-v2
name = "CAN__BUS___Tool"  -> local.can-bus-tool

Two local projects with the same name get the same ID, and the second install replaces the first. Give each project a distinct name.

Configuration

The agent runtime takes user configuration through a JSON Schema file, config.schema.json. The Zelos App renders it as a form, and your code reads the saved values with load_config(). Only the agent reads configuration, so [config] needs an [agent]. See Extension Configuration for the schema format, every widget, and how validation works.

Where Extensions Run

The agent runtime runs as a separate Python process under the Zelos Agent, in its own uv-managed virtual environment with Python 3.10 through 3.14. It runs as the agent's OS user and starts from a minimal environment. See Extension Runtime and Lifecycle.

Tabs and panels run as sandboxed web pages in the desktop app. A packaged tab or panel can't fetch or connect to anything outside its own package, and it can navigate its frame only to zelos-app:// pages and https:// pages on zeloscloud.io. It talks to Zelos only through the bridge SDK. See Sandbox and network restrictions.

Troubleshooting

Problem Where to look
The manifest is rejected Common Validation Errors
Packaging fails, or the release does not appear in the marketplace Package and Publish: Troubleshooting
The extension does not start, or crashes Runtime: Troubleshooting
A configuration form field is wrong Configuration: Troubleshooting
A tab or panel does not connect App Extensions: Troubleshooting