Extension Manifest Reference

Every extension has an extension.toml file at the root of its project. The manifest names the extension, says how Zelos runs it, and says what goes into its release archive.

Zelos parses and validates the manifest when you install an extension, install it locally, or package it. The marketplace parses it again when it ingests a release. A manifest that fails validation stops each of these steps with an error that names the problem.

Minimal Manifests

An agent extension needs a name, a version, and an entry point:

name = "My Extension"
version = "1.0.0"

[host]
type = "agent"

[host.agent]
entry = "main.py"

An app extension needs a name, a version, and an HTML entry file:

name = "Device Dashboard"
version = "1.0.0"

[host]
type = "app"

[host.app]
entry = "dist/index.html"

These manifests install. To package a release archive, also add a [package] section.

Complete Examples

Agent ExtensionApp Extension

name = "CANbus Decoder Pro"
version = "2.1.0"
description = "Decode CAN messages with DBC files and stream to Zelos"
author = "Acme Corporation"
repository = "https://github.com/acme/canbus-decoder"
homepage = "https://acme.com/canbus"
icon = "assets/icon.png"
readme = "README.md"
keywords = ["can", "automotive", "dbc", "j1939"]
categories = ["Automotive", "IoT"]

[zelos]
version = ">=25.0.20"

[config]
schema = "config.schema.json"

[host]
type = "agent"

[host.agent]
entry = "main.py"
python_version = "3.11"
targets = ["linux-x86_64", "darwin-arm64", "windows-x86_64"]

[host.agent.env]
LOG_LEVEL = "info"

[host.agent.stop]
grace_seconds = 30

[package]
paths = ["main.py", "canbus_decoder"]

name = "Device Dashboard"
version = "1.0.0"
description = "Custom dashboard for device health monitoring"
author = "Acme Corporation"
icon = "assets/icon.svg"
readme = "README.md"

[zelos]
version = ">=26.0.3"

[host]
type = "app"

[host.app]
kind = "web_app"
entry = "dist/index.html"

[package]
paths = ["dist"]

Top-Level Fields

Field	Required	Default	Rules
name	Yes	-	Display name. Must not be empty or whitespace. At most 60 characters.
version	Yes	-	Strict SemVer, for example 1.2.3 or 2.0.0-beta.1.
[host] or [runtime]	Yes	-	How Zelos runs the extension. Use [host]; [runtime] is the legacy form. Give exactly one.
description	No	-	Summary shown in the marketplace and the app.
author	No	-	Author or organization.
repository	No	-	Project URL. Zelos accepts any value that parses as a URI.
homepage	No	-	Project website. Zelos accepts any value that parses as a URI.
icon	No	-	Relative path to an icon file.
readme	No	-	Relative path to a Markdown README.
keywords	No	[]	Search terms. At most 20. No empty strings.
categories	No	[]	Marketplace categories, for example "IoT". At most 10. No empty strings.
[zelos]	No	Host-aware	Zelos version requirement. See Version Compatibility.
[config]	No	-	Configuration schema. See [config].
[package]	For packaging	-	Release archive contents. See [package].

Do not set an id field. Zelos derives the extension ID from the GitHub repository for marketplace installs and from name for local installs. See Extension Identity.

Path Rules

Every path in the manifest (entry, icon, readme, config.schema, requirements, workdir, and each [package] path) must follow these rules:

• The path is relative to the project root.
• No absolute paths.
• No .. segments.
• No segment starts with ., so hidden files and directories are not allowed.

When you install or package, Zelos also checks that entry, icon, readme, config.schema, and requirements exist as files and that workdir exists as a directory. An app extension with source = "external" skips the entry check.

Version Compatibility

The [zelos] table sets the Zelos versions your extension supports:

[zelos]
version = ">=25.0.20"

The value is a SemVer range:

Range	Meaning
>=25.0.20	25.0.20 and later
>=25.0.0, <26.0.0	25.x only
~25.0.20	25.0.20 and later 25.0.x releases
*	Any version

When you omit [zelos], the default depends on the host type:

• Agent extensions: >=25.0.20
• App extensions: >=26.0.3

Zelos checks the range when you install the extension, from the marketplace or locally. An install on a Zelos version outside the range fails with Extension requires Zelos version matching '<range>', but current version is <version>. A pre-release Zelos build is compared as its release version, so 26.1.0-beta.2 counts as 26.1.0.

[host]

[host] declares where the extension runs:

• type = "agent" runs a Python process under the Zelos Agent. It needs a [host.agent] table and must not have [host.app].
• type = "app" loads a sandboxed web page in a desktop app tab. It needs a [host.app] table and must not have [host.agent].

[host.agent]

[host]
type = "agent"

[host.agent]
runtime = "python"
entry = "main.py"
python_version = "3.11"
requirements = "requirements.txt"
workdir = "."
targets = ["linux-x86_64", "darwin-arm64"]

[host.agent.env]
LOG_LEVEL = "info"

[host.agent.stop]
grace_seconds = 10

Field	Required	Default	Description
runtime	No	"python"	Runtime kind. "python" is the only value.
entry	Yes	-	Python entry point, for example "main.py".
python_version	No	"3.11"	Python version in major.minor form. The zelos-sdk package needs 3.10 or later. See Python Environment.
requirements	No	-	Dependency file override, for example "requirements.txt". Without it, Zelos installs from uv.lock when present, otherwise from pyproject.toml.
workdir	No	"."	Working directory for the process, relative to the project root.
targets	No	[]	Supported platforms. See Platform Targets.
env	No	{}	Environment variables for the process. See Environment Variables.
stop.grace_seconds	No	10	Seconds to wait after a stop request before Zelos force-kills the process. 1 to 300. See Stop and Shutdown.

targets, env, stop, and workdir go inside [host.agent]

With [host], a top-level targets, env, [stop], or workdir is an error, not a fallback. Zelos rejects the manifest with Top-level fields [...] conflict with [host.agent]; move them inside [host.agent]. Write them as targets and workdir keys under [host.agent], and as [host.agent.env] and [host.agent.stop] tables.

[host.app]

[host]
type = "app"

[host.app]
kind = "web_app"
source = "package"
entry = "dist/index.html"

Field	Required	Default	Description
kind	No	"web_app"	App contribution kind. "web_app" is the only value.
entry	Yes	-	With source = "package", the HTML entry file inside the package. With source = "external", an https:// URL.
source	No	"package"	"package" loads entry from the installed package. "external" loads an https:// URL on zeloscloud.io or one of its subdomains. Other hosts are not allowed.

App extensions have no process, so targets, env, and stop do not apply to them.

Legacy [runtime]

Older agent extensions use [runtime] in place of [host]. Zelos still accepts it:

name = "My Extension"
version = "1.0.0"
workdir = "."
targets = []

[runtime]
type = "python"
entry = "main.py"
python_version = "3.11"

[env]
LOG_LEVEL = "info"

[stop]
grace_seconds = 10

Field	Required	Default	Description
type	Yes	-	Must be "python".
entry	Yes	-	Python entry point.
python_version	No	"3.11"	Python version in major.minor form.
requirements	No	-	Dependency file override.

With [runtime], workdir, targets, env, and [stop] are top-level. A manifest with both [host] and [runtime] is an error. Use [host] for new extensions.

Platform Targets

targets lists the platforms an agent extension supports. An empty list, or no targets key, means every platform.

Target	OS	Architecture
linux-x86_64	Linux	x86-64
linux-aarch64	Linux	ARM64, for example Raspberry Pi and embedded Linux
darwin-arm64	macOS	Apple Silicon
darwin-x86_64	macOS	Intel
windows-x86_64	Windows	x86-64

Zelos rejects any other value. The list is declarative: an install does not read it. Zelos picks the release archive for a machine from the archive's file name. To ship different archives per platform, see Platform-Specific Archives.

Environment Variables

env sets variables for the extension process. Values are strings.

[host.agent.env]
LOG_LEVEL = "debug"
DEVICE_PORT = "/dev/ttyUSB0"

Names that start with ZELOS_ are reserved. A manifest that sets one fails with Environment variable '<name>' uses reserved prefix 'ZELOS_'. For the variables Zelos sets and passes through, see Process Environment.

[config]

[config] points at the JSON Schema that defines the extension's configuration form:

[config]
schema = "config.schema.json"

Declare it whenever your extension has a configuration schema, even at the default path:

• The agent validates configuration against config.schema.json in the code directory when the file exists, with or without [config]. A schema path you declare must exist, or start fails.
• zelos extensions package adds the schema file to the archive only when [config] names it, or when it falls under a [package] path.
• The marketplace validates the schema only when [config] names it.

For the schema format and form widgets, see Extension Configuration.

[package]

[package] lists what goes into the release archive:

[package]
paths = ["main.py", "my_extension"]

Field	Required	Description
paths	Yes	Files and directories to include. A directory includes everything under it.

zelos extensions package refuses to run without this section: Packaging requires a [package] section in extension.toml. Add [package] with explicit paths to define the package boundary. Installing locally does not need it.

Rules for paths:

• The list must not be empty.
• No empty entries, no ".", and no glob characters (*, ?, [, {).
• Each entry follows the path rules.
• One entry must cover the entry file. App extensions with source = "external" are exempt.
• When workdir is not ".", one entry must cover it.

For what else goes into the archive and how to preview it, see Package and Publish Extensions.

Defaults

Field	Default
zelos.version	>=25.0.20 for agent extensions, >=26.0.3 for app extensions
host.agent.runtime	"python"
host.agent.python_version	"3.11"
host.agent.workdir	"."
host.agent.stop.grace_seconds	10
host.agent.targets	[] (all platforms)
host.agent.env	{}
host.app.kind	"web_app"
host.app.source	"package"
keywords, categories	[]

Common Validation Errors

Error	Fix
Manifest must specify either [host] or [runtime]	Add a [host] table.
Manifest must not specify both [host] and [runtime]	Remove [runtime] and move its fields to [host.agent].
[host] type = "agent" requires [host.agent]	Add [host.agent] with an entry.
Top-level fields [targets, env] conflict with [host.agent]; move them inside [host.agent]	Move the named fields under [host.agent].
Display name must be at most 60 characters	Shorten name.
Python version must be in major.minor format (e.g., '3.11')	Write python_version = "3.12", not "3.12.1".
Repository '<value>' must be a valid URI	Use a full URI, for example https://github.com/org/repo.
Environment variable '<name>' uses reserved prefix 'ZELOS_'	Rename the variable.
stop.grace_seconds must be between 1 and 300 seconds	Pick a value from 1 to 300.
Entry point '<entry>' is not covered by [package].paths	Add the entry file or its directory to [package].paths.
path contains hidden segments	Rename paths that start with ..
path contains parent directory references	Remove .. from the path.