Extensions¶

Extensions are how you connect your devices and systems to Zelos. Built with the Zelos SDK, they turn an integration into a one-click install, so you can stream, visualize, and control hardware without writing code.

For example

Install the CAN extension and you can view and send data on the bus right away, with no integration code of your own.

What Are Extensions?¶

An extension adds one or more of these to Zelos:

An agent runtime runs on the Zelos Agent and provides data acquisition, actions, and device integrations.
A tab is a sandboxed web UI that opens in its own tab in the app.
Panels are views that you put in a layout, next to plots and tables. An extension can add several.

One extension can add all three. An extension can, for example, capture data on the agent and add a panel to view it.

This page focuses mostly on marketplace usage and agent runtime management. For authoring, see Develop Extensions.

Extensions provide:

Data Acquisition

Decode bus protocols (CAN/CAN-FD, Modbus, MQTT, OPC-UA, Ethernet/Protobuf, Serial)
Interface with test equipment (National Instruments, Opal-RT HIL boxes, oscilloscopes)
Stream from custom hardware and sensors
Parse proprietary file formats and logs

Device Control

Execute commands on hardware via actions
Automate test sequences
Control parameters in real-time
Trigger hardware events from the app

App Workflows

Build custom dashboards and workflow UIs inside Zelos
Open an extension's tab from the sidebar rail or its ⌄ menu
Add panels that show your data in a layout, beside the built-in ones
Match Zelos theme and workspace context through the bridge SDK

Panels From Extensions¶

An installed extension can add layout panels. They appear in Add Panel like any other panel, and you can drop signals on them, resize them, and save them in a layout.

A saved layout can hold a panel from an extension you have not installed. That panel shows a placeholder that names the extension, with a button that opens the extension's page, where you can install it.

Finding Extensions¶

Marketplace¶

The Extensions marketplace contains integrations for common hardware, protocols, and use cases. Open it from the Extensions view in the sidebar.

Click Extensions in the sidebar rail.
Browse the MARKETPLACE section for available extensions.
See your own extensions in the INSTALLED section. Each row shows the agent it is installed on.

Click any extension to open its details in a tab. The details tab shows the README, version, author, and categories, plus the Install, Update, and Uninstall buttons.

Click the ⋮ menu in the MARKETPLACE header to access marketplace actions:

Marketplace Menu — Marketplace actions menu.

Create Extension: Generate a new extension project from a template.
Install Local Extension: Install an extension from a folder on this computer.
Publish Extension: Open the marketplace website to submit your extension.

Type in the search box at the top of the Extensions view. It filters both the INSTALLED and MARKETPLACE sections. The search matches:

Extension name, repository, and description
Author name
Categories (for example, Automotive or Industrial)
Keywords (for example, CAN or Modbus)

Installing Extensions¶

From MarketplaceLocal Installation

Install published extensions with a few clicks:

Click the extension in the MARKETPLACE section to open its details tab.
Click Install.
Configure the extension if it needs settings, then start it. See Managing Agent Extensions.

Requirements:

An extension with an agent runtime installs on the agent you pick. It needs a live workspace connected to that single Zelos Agent. An install without the agent runtime goes to the agent on this computer.
The extension must support your platform (Windows, macOS, or Linux on x86_64 or ARM64).
The app needs an internet connection to download from the marketplace.

Install extensions from your local filesystem for development and testing:

Open the Extensions view.
In the MARKETPLACE header, click ⋮ and choose Install Local Extension.
Select the extension folder that contains extension.toml.
The extension installs on the agent on this computer, with the ID local.<name>. <name> is a slug of the name in the manifest. Zelos uses the folder name only when the manifest name gives an empty slug.

The details tab marks a local extension with a Local badge. Two local extensions with the same manifest name get the same ID, so give each one a distinct name.

Development workflow:

Agent runtime: A local agent runtime runs from its source folder. Code changes take effect the next time you start or restart it.
Tabs: Run just build, then reopen the extension's tab.
Panels: Run just build, then choose Reload from the panel's ⋮ menu. Only local installs show it.
After any change to extension.toml, such as a new panel, run zelos extensions install-local . again, or choose Install Local Extension on the same folder. Do the same after a dependency change. If the manifest version is unchanged, Zelos replaces the installed copy and keeps its saved configuration. A new version installs as a separate copy without it.

Choosing What to Install¶

An extension can ship up to three parts: an agent runtime (Python, prepared and run by a Zelos Agent), a tab, and panels. Install installs every part. That is the default, and most installs need nothing else.

When an extension ships more than one part, or its agent runtime offers extras, the Install button has an arrow. The arrow opens a menu; its Choose what to install… item opens a dialog with one checkbox per part, all ticked. Untick what you do not want, then click Install.

An install without the agent runtime always goes to the agent on this computer, because that is where the app runs. This holds even when the workspace is connected to a remote agent.
A headless zelos-agent (installed on a device, with no app) only takes the agent runtime. When the dialog is aimed at one, the tab and panel rows are disabled and read "Not on a headless agent. Install it where the app runs." Zelos refuses to install an extension with no agent runtime on a headless agent.
Each agent gets exactly what you install on it. Installing on a lab machine's agent changes nothing on your own computer, so install its panels here too if you want them in your own app.
Outside a live workspace, as in trace mode, or with several agents connected, Install is disabled for an extension with an agent runtime. When the extension also ships a tab or panels, the arrow stays open: Choose what to install… lists them without the agent runtime and installs them on this computer.
An extension installed only on another agent keeps the arrow on its page: Choose what to install… lists its tab and panels without the agent runtime and installs them on this computer.

The CLI takes the same choice as a comma list of agent, tab, and panel:

zelos extensions install acme/sensor-monitor --with agent,panel
zelos extensions reinstall acme.sensor-monitor --with agent

Without --with, install installs everything and reinstall keeps the current parts. Updates keep your choice: an install that has everything also gets any part a new version adds, and an install you narrowed keeps its set. To change what an installed extension has in the app, see Reinstall and Uninstall.

Extras¶

Some extensions offer extras. An extra is an optional add-on for the agent runtime, such as support for one kind of hardware adapter. Each one installs a few more Python packages. Zelos installs no extras unless you choose them.

Choose what to install… lists the extras under Agent runtime, one checkbox each, with a line on what each one enables. They start unticked. Tick the ones you need, then click Install. The extras show only while Agent runtime is ticked.
When the agent runtime is the extension's only part, the dialog shows it as a heading with no checkbox, and the extras under it.
To add or remove extras later, choose Change what's installed… from the Uninstall menu. The extras you installed start ticked.
Reinstall and Update keep the extras you installed.
An update keeps an extra only while the new version still offers it. When the new version no longer offers one, Zelos removes it, and a notice says so: "Removed extra from name. Version version no longer offers it."
An update does not add an extra that a new version offers for the first time. Add it with Change what's installed….
Zelos AI also installs no extras unless you ask. It knows what each extra enables, so it can offer to add one when an extension needs it.

The CLI takes extras as a comma list:

zelos extensions install acme/sensor-monitor --extras usb,serial
zelos extensions reinstall acme.sensor-monitor --no-extras

--extras a,b installs exactly those extras.
--no-extras removes every extra.
With neither flag, the command keeps the installed extras. A first install gets none.

install, install-local, reinstall and update all take these flags. When an update, or an install over another version, removes an extra that version no longer offers, the command prints a warning. A local install has no Change what's installed…, so choose its extras with zelos extensions install-local <folder> --extras …. zelos extensions info lists each extra the extension offers, what it enables, and whether it is installed.

Managing Agent Extensions¶

Start, stop, and configure agent runtimes from the EXTENSIONS section of the Explorer view. The section appears in live workspaces and lists every extension with an agent runtime on the connected agents. With more than one agent connected, the list groups extensions by agent and shows how many are running in each group.

The Extensions rail item opens the marketplace view, where you install, update, and uninstall extensions.

Starting & Stopping¶

Each row in the EXTENSIONS section has a start or stop button and a Configure extension button (gear icon). Click the extension name to open its details tab.

Start an extension:

Click the green play icon on a stopped extension.
The icon changes to a red square while the extension runs.
The extension's signals and actions appear in the SIGNALS and ACTIONS sections.

Stop an extension:

Click the red square icon on a running extension.
The extension process stops.
Its actions leave the ACTIONS section.

Restart an extension:

Open the configuration dialog and click Save & Restart, or
Open the command palette, choose Manage Extension Runtime..., and pick the extension's Restart command. The same list has a Start or Stop command for each extension.

Extension States¶

Extensions show different indicators based on their state:

State	Icon	Description
Running	Red square	The extension is running. Click the square to stop it.
Stopped	Green play	The extension is installed but not running. Click play to start it.
Error	Amber warning and green play	The extension stopped with a nonzero exit code or a signal.
Processing	Spinner	The extension is starting, stopping, or restarting. A Restarting… line appears under the row during a restart.

Crash Detection¶

Zelos detects when a running extension stops without you stopping it. When that happens:

A toast says the extension stopped unexpectedly and shows the exit details.
An amber warning icon appears on the extension's row in the EXTENSIONS section.
The toast offers Ask AI, which opens the AI chat with the end of the extension's log attached and a question naming the extension. Without AI, the toast offers View log instead.

Exit details shown in the toast:

Exit code: for example, "Exited with code 1".
Signal: for example, "Killed by SIGKILL". Windows reports only the exit code.
Agent: for an extension on a remote agent, the toast also names the agent.

Click the amber warning icon to have the AI fix it. The chat opens with the end of the log attached as a text file and a message naming the extension and its exit that asks the AI to find out why and fix it, for you to read and send. The AI reads the log, README and configuration, applies the fix it can make, such as a corrected configuration or a restart, and asks you only for what it cannot do from your computer. If your organization has turned off attachments, the log is not attached, and the assistant reads it once you send. Without AI, the icon opens extension.log instead; for an extension on a remote agent that asks where to save a copy first. The log is always available from View log in the menu next to Uninstall in the details tab.

The Ask AI draft is only ever sent when you press Send. The assistant can read the full log, the README, and the current configuration through its extension tools once you do.

Crash State Clears on Restart

The error state automatically clears when you start the extension again. If the extension keeps crashing, check the logs to identify the root cause.

Extension Tabs¶

Some installed extensions add a tab. Each one appears as a launcher in the rail's ⌄ menu, with a NEW badge until you first open it. Pin a launcher to give it a rail icon. Click the launcher to open the extension's tab. You can also open one from the command palette with Apps....

To uninstall an extension with a tab, open the ⌄ menu, click ⋮ on its row, and choose Uninstall. The Uninstall button in its details tab works too.

Tabs suit dashboards and workflows that need more room than an action or a streamed signal. A tab is a sandboxed web page with no process of its own. An extension that also has an agent runtime starts, stops and appears in the Explorer's EXTENSIONS section. An extension with only a tab or panels does neither.

Configuration¶

Many agent-hosted extensions accept user configuration for API keys, settings, and preferences. The app generates this form from the extension's config.schema.json.

Configure an Extension:

In the Explorer's EXTENSIONS section, click the gear icon (Configure extension) on the extension.
The configuration dialog opens with the extension's settings.
Fill in the required settings. Each setting shows its label and help on the left and its control on the right. In a group with required settings, each setting you can leave empty shows Optional beside its label.
Click Save & Start if the extension is stopped, or Save & Restart if it is running.

Click Cancel, press Escape, or click outside the dialog to close it without saving. If you changed a setting, Zelos asks first. Click Discard to close, or Keep editing to go back.

Lists in the form:

A list of buses, connections, or other items shows one card per item. Click a card to open it. One card is open at a time.
A card's title is the item's name. An item without a name takes its first required text, such as its channel. Otherwise the card reads as its type and number, such as Bus 1.
A closed card's summary lists the item's main settings, such as RTU · /dev/ttyUSB0 · Parity: Even · 2 devices. A changed choice shows its setting's name and value.
Drag a card's grip to reorder the list. You can also focus the grip and press the Up and Down arrow keys.
Each card's ⋮ menu has Duplicate and Remove.
An add button names what it adds, such as Add bus. A new item opens with its first field ready to type in.
At the top level, a short list of simple items shows as a table, with one row per item. A list inside a card, such as a bus's CANopen nodes, sits beside its label like any other setting, one card per item.
A list of values, such as files, sits beside its label like any other setting, one row per value. Drag a row's grip, or press the arrow keys on it, to reorder it. Add file adds an empty file field: type a path, or click the folder button in it to choose a file.

What happens when you open and save the dialog:

Zelos loads the last saved configuration for that extension on that agent, when one exists.
With no saved configuration, the form shows the defaults from the extension's schema.
If the saved configuration can't be read, a warning says the form shows the defaults.
A successful save closes the dialog and refreshes the extension's state.
A save with invalid values keeps the dialog open. Each card with an error opens, turns red, and shows Needs attention. The message shows under the field.
A failed start or restart keeps the dialog open and shows an error toast, so you can correct the values and retry.
An extension without settings shows "This extension does not have configuration options."

Form helpers that extensions can add:

Auto-configure: Some extensions put an Auto-configure button at the top of the form. It runs the extension's own detection and fills in the fields it finds, such as a connected device. The other fields keep their values. A note beside the button reports what changed, such as "Added 2 buses, changed 1 setting", or "Nothing new found". A message from the extension follows the report. Click Undo to put the form back as it was before the run. Review the result, then save. If the run fails, the note says why.
Scanned values: Some fields have a Choose button inside the text box. It lists values the extension scanned for, such as available interfaces, and you can search the list. You can still type any value. If the scan fails, the field stays a plain text box with a hint that says why.
Collapsed groups: Some groups of rarely changed settings, such as Advanced, start collapsed behind their title. Click the title to expand the group. A collapsed group opens on its own when one of its fields has an error.
File paths: A file field has a folder button inside it. Click it to choose a file, or type the path.

Auto-configure and scanned values work before the extension has ever started. They can only run the configured extension's own actions.

Configuration Tips

Help text under a label shows its first sentence. Click More to read all of it, and Less to fold it again.
A setting marked Optional can stay empty.
A required field left empty shows Required below it when you save.
Invalid values show error messages below the field.
If a dropdown or other popup field is open, close it before you click outside the dialog.
An extension without an agent runtime has no configuration dialog.

Inspect Config from the CLI

Use zelos extensions config <id> to print the extension's schema and last saved configuration without opening the app. See the CLI reference.

Using Agent Extensions¶

Once running, extensions stream data and provide controls through the Zelos SDK.

How Extensions Work¶

Extensions use the Zelos SDK to:

Define event schemas - Specify signals with types and units (e.g., CAN messages decoded into engineering values)
Stream data - Push events to the agent in real-time (e.g., sensor readings at 1kHz)
Provide actions - Expose commands users can trigger from the app (e.g., send CAN message, reset device)

This data appears in your workspace just like data from your own SDK-instrumented applications.

Signals from Extensions¶

A running extension's signals appear in the SIGNALS section of the Explorer view. The tree groups them by agent, then source, then event, then field. The agent level appears when more than one agent is connected:

📁 Agent (e.g., "localhost")
  └── 📁 Source (e.g., "can_bus", "sensor_1")
      └── 📁 Event (e.g., "motor_status", "measurements")
          └── 📊 Field (e.g., "rpm", "temperature")

Add signals to panels using the same workflows as any other data:

Drag signals onto an existing panel or into empty layout space. Zelos picks each panel from the signal's type. An extension's own panel takes its event families when you drag a whole event, a source, or an agent.
Multi-select signals and drag them together.
Double-click a field to create the panel that fits its type.
Extension panels have no Change to menu item.

See The Explorer View for details.

Actions from Extensions¶

Extension actions appear in the ACTIONS section of the Explorer view in live workspaces. Drag an action into the layout or double-click it to open it in an Action panel. Actions let you:

Send commands to hardware (e.g., "Set motor speed", "Trigger capture")
Configure parameters in real-time (e.g., "Update PID gains")
Execute test sequences (e.g., "Run calibration routine")

Each action generates interactive parameters from the extension's schema, with proper types, validation, and help text.

Updating Extensions¶

Automatic Update Detection¶

The app checks for extension updates in the background. When an update is available:

The extension's row in the INSTALLED section shows an Update badge.
The Extensions rail item shows a NEW pill. Its tooltip reads "Extension updates available".
The details tab shows the new version, for example "v1.2.0 available".

Manual Update Check¶

Run an update check right away:

Open the Extensions view.
In the INSTALLED header, click ⋮ and choose Check for Updates. The menu appears only when at least one extension is installed.
A toast reports the result: "Extensions are up to date" or the number of updates available.

The command palette has the same check as Check Extension Updates.

Installing Updates¶

Update an Extension:

Stop the extension if it is running.
Click the extension in the INSTALLED section to open its details tab.
Click Update. The button appears only when an update is available.
Wait for the "name updated" toast, which names the new version.
The extension stays stopped. Start it to use the new version.

Extension Update — Updating an extension.

Stop Before Updating

Extensions must be stopped before you update them. While an extension runs, Update and Uninstall are disabled and the details tab reads "Stop the extension before updating or uninstalling".

Reinstall and Uninstall¶

The Uninstall button in the details tab removes the extension. It asks first, with the dialog "Uninstall name?" and the text "Its configuration and log are deleted with it. Reinstalling starts from the defaults." For an extension with an agent runtime, or a marketplace extension that ships more than one part, the arrow next to Uninstall opens a menu:

Change what's installed…: Open the same dialog with the installed parts ticked. It lists the parts of the installed version. Apply reinstalls the same version with the new set. With no change, Apply only closes the dialog. Zelos prepares a runtime you add and deletes one you remove. Stop the extension first. This item appears for marketplace extensions whose installed version ships more than one part, or whose agent runtime offers extras. On a headless agent, which takes only the agent runtime, it appears only when that runtime offers extras. Local installs always have every part and do not offer it. For an install without the agent runtime, outside a live workspace or with several agents connected, it lists only the tab and panels, as Install does.
Reinstall (with an agent runtime): Rebuild the extension's runtime environment. Stop the extension first.
View log (with an agent runtime): Open the extension's extension.log.

Multi-Agent Limitations¶

When more than one agent is connected, some agent-extension operations are disabled to prevent accidental changes. The details tab reads "Connect to a single agent to manage this extension".

Install: Disabled. For an extension that also ships a tab or panels, Choose what to install… still installs them on this computer, without the agent runtime.
Update: Disabled.
Uninstall and Reinstall: Disabled.

Operations that stay available with several agents connected:

Start and Stop: Control extensions on any connected agent.
Configure: View and change each agent's extension settings.
View log: Open the log of an extension on any connected agent.

Managing Extensions Across Agents

To install an agent runtime, or to update or uninstall extensions, connect to a single agent.

Troubleshooting¶

Extension Won't Start¶

Common causes:

Configuration required: Open the configuration dialog and fill in the required fields.
Platform incompatibility: Check that the extension supports your OS and architecture.

Steps to resolve:

Click the extension to open its details tab.
Read the README for configuration requirements.
Open the configuration dialog and check that every required field is filled in.
Check the extension log: choose View log from the menu next to Uninstall in the details tab. Or click Ask AI on the toast that follows an install: the chat opens with a question naming the extension and asking for help setting it up, ready to send.

Configuration Dialog Won't Close¶

If the configuration dialog feels stuck open:

Close any open dropdown or other popup field first. The dialog ignores outside clicks while those controls are open, so a stray click does not dismiss it.
Check for inline validation errors below the form fields. A card with an error shows Needs attention.
If you clicked Save & Start or Save & Restart, wait for the operation to finish. The dialog closes only after the extension starts or restarts successfully.
If the request fails, read the error toast, correct the configuration, and try again.
To leave without saving, click Cancel. If you changed a setting, click Discard in the prompt that follows.

To inspect the last saved configuration outside the UI, run:

zelos extensions config <extension-id>

Extension Keeps Crashing¶

If an extension repeatedly stops with an amber warning icon:

Ask AI: Click the amber warning icon, or Ask AI on the toast. The chat opens with the end of the log attached and a message asking the AI to find out why the extension stopped and fix it; read them, then send.
Read the log: View log in the menu next to Uninstall in the details tab opens extension.log.
Common exit details:
Exited with code 1: A general error. Check the log for details.
Killed by SIGKILL: The process was force killed, for example by the Linux out-of-memory killer or by hand.
Killed by SIGTERM: Something asked the process to terminate.
Verify the configuration: Invalid settings can make an extension exit at once.
Check dependencies: Look for missing or incompatible packages. Reinstall rebuilds the runtime environment.

Extension Logs Location

Logs are stored at <data>/extensions/<id>/<version>/extension.log on the agent's computer. Install Locations lists the path for each platform.

Cannot Install Extension¶

A failed install shows a "Couldn't install name" toast with one of these reasons.

"name doesn't support your system":

The extension has no package for your OS or architecture.
Check the details tab for supported platforms.

"Network error. Check connection and try again.":

Check your internet connection.
Check that your firewall allows marketplace access.
Try again in a few moments.

"name is already installed":

The extension is already in the INSTALLED section.
Use Update instead if you need a newer version.

"name needs Zelos version or later. Update Zelos, then install it again.":

The extension needs a newer Zelos than the agent you are installing on.
Update Zelos on that machine, then install the extension again.

Creating Extensions¶

Build your own extensions to share integrations with the Zelos community.

Why Build an Extension?¶

Package your integration work into a reusable extension:

Share protocol decoders - CAN, Modbus, custom binary formats
Distribute hardware drivers - Test equipment, sensors, actuators
Provide workflows - Automated test sequences, calibration routines
Build integrations - Cloud services, databases, external APIs

Extensions use the Zelos SDK's event streaming and action system, the same tools you use to instrument applications.

Getting Started¶

The fastest way to create an extension is the built-in creator in the app:

Open the Extensions view.
In the MARKETPLACE header, click ⋮ and choose Create Extension.
Pick what the extension adds, Agent, Tab, Panel, or any combination, and click Next.
Enter an Extension Name (lowercase letters, digits, and hyphens) and an optional Description.
Click Create Extension, then pick the folder for the new project.
Zelos generates the project and installs it locally, so its tab or panel opens right away. If the install fails, the result shows a warning and the project is still created.

The last step shows the project path. Click Open to open the folder, or Documentation or Marketplace for next steps.

Create Extension — Creating a new extension.

Follow the Extension development guide for more information. The generated projects include working examples, development tools, CI/CD workflows, and everything needed for production-ready extensions. The agent runtime is Python; tabs and panels use React, Vite, and @zeloscloud/app-extension-sdk.

Next Steps¶

Extension Development Guide

Shared guide, plus pages for the agent runtime and tabs
Panel Development Guide

Build a panel that users add to a layout
Zelos SDK Quickstart

Learn the SDK that powers all extensions
Marketplace

Browse all available extensions online
Extension Templates

The template parts that zelos extensions create combines
Sidebars

Access and manage extensions from the left sidebar