Adapter packages

An adapter package is a directory: an adapter.json manifest, your executable, and any files it needs. The manifest records every file's size and SHA-256, which is what the desktop reviews and re-checks.

Availability

Packages are produced by the shellcanvas-adapter CLI and installed through App Manager → Connection adapters on the Windows desktop. A package is built for one platform and refused on another.

Interface

Manifest

{
  "schemaVersion": 1,
  "id": "example.device",
  "name": "My device",
  "version": "0.1.0",
  "description": "Reads probes from an example device.",
  "platform": "windows-x86_64",
  "entrypoint": "bin/shellcanvas-device.exe",
  "arguments": [],
  "files": [
    { "path": "bin/shellcanvas-device.exe", "size": 4312576, "sha256": "…64 hex…", "executable": true }
  ],
  "configuration": [
    { "id": "endpoint", "label": "Device address", "kind": "text", "required": true },
    { "id": "token", "label": "API token", "kind": "password", "required": false }
  ]
}

Field	Rules
schemaVersion	Exactly 1.
id	Namespaced, dotted, at most 200 bytes, not starting with system.
name	Non-blank, at most 200 bytes.
version	Semantic version, at most 100 bytes.
description	Up to 4000 bytes.
platform	{os}-{arch}, for example windows-x86_64. In a source manifest you may write current and the CLI expands it.
entrypoint	A relative path that must also appear in files as executable. On Windows it must end in .exe.
arguments	Fixed launch arguments, without NUL bytes.
files	1 to 4096 entries, 512 MiB in total. Each has path, size, sha256 (64 lowercase hex) and optional executable.
configuration	Fields the user fills in when connecting: text, password, number or boolean, each with a unique id and a non-blank label. A password field may not carry a default.

Source manifests list only path and executable; sizes and hashes are filled in when packing. {exe} in a path expands to the platform's executable suffix.

Paths must stay inside the package: no .., no absolute paths, no symbolic links, no Windows reserved names such as CON or COM1, and nothing that collides with adapter.json.

Commands

shellcanvas-adapter build ./my-device ./my-device-package          # compile, then pack
shellcanvas-adapter build ./my-device ./my-device-package --debug  # debug build
shellcanvas-adapter pack ./my-device/adapter.json ./target/release/shellcanvas-device ./out
shellcanvas-adapter validate ./my-device-package/adapter.json
shellcanvas-adapter schema source                                   # or: schema package

build and pack refuse an output directory that already exists, write assets with restrictive permissions, and write adapter.json last so a half-written package is never mistaken for a complete one. validate re-hashes every file and prints Verified <id> <version> (<n> assets) without executing anything.

Examples

A release routine, with the package checked exactly as the desktop will check it:

shellcanvas-adapter build ./my-device ./dist/my-device-0.2.0
shellcanvas-adapter validate ./dist/my-device-0.2.0/adapter.json

Configuration a user fills in when adding your adapter as a source:

"configuration": [
  { "id": "host", "label": "Controller address", "kind": "text", "required": true },
  { "id": "port", "label": "Port", "kind": "number", "required": false, "default": 4840 },
  { "id": "verify", "label": "Verify certificate", "kind": "boolean", "required": false, "default": true },
  { "id": "secret", "label": "Shared secret", "kind": "password", "required": true }
]

Values reach your adapter in the configuration object of the initialize request. Password values are never written into saved workspace profiles.

Errors

Message	Cause
Unsupported or invalid adapter package identity	The id is not namespaced, too long, or starts with system.
Adapter packages must contain 1 to 4096 files	Empty or oversized file list.
Adapter package exceeds the 512 MiB payload budget	Total size too large.
Duplicate asset paths or invalid file hashes	Repeated path, or a hash that is not 64 lowercase hex.
Adapter entrypoint must be a declared executable file	The entrypoint is missing from files, or not marked executable.
Windows adapter entrypoints must be explicit .exe files	A Windows package pointing at something else.
Invalid or duplicate adapter configuration fields	Repeated id, blank label, or a dot in an id.
Invalid adapter field default; passwords cannot have packaged defaults	A default on a password field.
Invalid adapter asset path / Invalid or reserved adapter asset path	Traversal, control characters, or a reserved name.
Package assets cannot be symbolic links	A symlink in the package.
Choose a new package output directory	The output directory exists.
This adapter package is for a different platform	The manifest's platform does not match the desktop.
Adapter file does not match its manifest: <path>	An installed file was modified after review.
This adapter changed while being reviewed. Review the package again	The package changed between review and install.

Lifecycle and permissions

Installing happens in two steps. Review copies and hashes the package into a staged snapshot, so what you approve is fixed even if the source directory changes afterwards. Install then records it as a generation in the catalog under the desktop's local application data.

Updating installs a new generation and keeps the old directory in place, so a connection that is running keeps the exact bytes it started with. Connecting re-verifies every declared asset, which is how tampering after installation is caught. Disabled adapters stay installed but refuse to launch, and unreferenced generations are collected once nothing holds them.

Everything here establishes what you installed, not who wrote it. There is no publisher authentication, no signing and no marketplace; an adapter is native code you decided to trust.

Related guides

• Build your first adapter — producing a package.
• Adapter services — what to advertise once installed.
• Extension permissions and trust — how this compares with apps and themes.
• Adapter diagnostics — when installation or launch fails.