Skip to main content

Manifest

manifest.json describes your plugin. Termix reads it before running any of your code, so everything that decides whether the plugin can load, what it may do and where its UI shows up is in here.

Unknown fields are refused, at every level. A typo fails validation instead of being quietly ignored.

{
"id": "hello",
"name": "Hello",
"version": "1.0.0",
"description": "Says hello and keeps a few notes.",
"author": { "name": "You", "url": "https://example.com" },
"license": "Apache-2.0",
"repository": "https://github.com/you/termix-plugin-hello",
"docs": "https://github.com/you/termix-plugin-hello/tree/main/docs",
"category": "Productivity",
"icon": "Hand",
"features": ["A tab from the sidebar", "Notes per user"],
"engine": { "termix": ">=26.10.0", "api": "^1.2" },
"capabilities": ["db:own", "network:serve", "ui:surface"],
"env": [],
"contributes": {
"tabs": [
{
"id": "hello",
"titleKey": "tab.title",
"icon": "Hand",
"openFrom": ["rail"]
}
],
"permissions": [
{
"name": "use",
"titleKey": "permissions.use.title",
"descriptionKey": "permissions.use.description",
"defaultRoles": ["admin", "user"]
}
]
},
"locales": "locales",
"platforms": ["linux", "win32", "darwin"]
}

The main fields​

FieldWhat it is
idLowercase, starts with a letter, 2 to 40 characters. It names your tables, routes and permissions, so it never changes.
versionSemver. Must match package.json and the newest CHANGELOG.md section.
categoryOne of the categories.
iconA Lucide icon name, like Hand.
featuresUp to 20 short lines, shown on the plugin's page in Termix and on this site.
docsAn https link to your docs. Termix shows it on the plugin's page and in its settings.
envEnvironment variables your plugin reads. See below.
engine.termixThe Termix versions you work with.
engine.apiThe plugin API versions you work with, a semver range. Termix 26.11.2 has API 2.8. A range below 2 never runs.
capabilitiesWhat your code may do. See how it works.
dependenciesPlugins you can't work without: { "snippets": "^1.0.0" }.
optionalDependenciesPlugins you use when they are there. You must keep working without them.
provides, requiresServices you offer and use.
contributesEverything you add to Termix.
desktopHow a linked desktop app treats you: mirror (follow the server, the default), local (each desktop decides) or server (never runs on a linked desktop).
platformsServer operating systems you run on.

contributes​

FieldWhat it adds
tabs, panelsTab types and sidebar panels. Your frontend registers the components.
dashboardCardsDashboard cards.
actions, actionSlotsFrontend actions, and slots other plugins can fill.
permissionsPermissions.
settingsSettings at admin, user and host scope.
protocolsConnection protocols next to SSH, like RDP.
authLogin methods, second factors and SSH auth types. See auth.
syncEntitiesTables that sync to a linked desktop.
keybindingActionsThings keys can be bound to.
httpRedirects from old URLs.
guest, guestViewsViews that work without signing in, like a shared session.
uiPresetsWhat your UI shows in the Simple, Balanced and Advanced presets.
mobileHow the plugin shows in the mobile app. See below.

Every field is listed in the manifest reference, made from the schema.

Mobile app​

mobile tells the Termix mobile app what to do with your plugin. Without it the app shows nothing for it.

"mobile": { "mode": "webview", "views": ["hello"], "sizes": ["phone", "tablet"] }
  • mode: webview shows your UI from the server inside the app, native means the app has its own screens for it, none means nothing to show.
  • entry: a bundle made for the app, like dist/mobile.js, next to frontend.js. termix-plugin build makes it from src/mobile/index.tsx. Leave it out and your normal frontend runs in a phone sized frame.
  • sizes: phone, tablet or both.
  • views: the tab, panel or card ids the app offers. Every tab by default.
  • feature: for native, the app feature that stands in for the plugin.
  • note: a locale key or plain text the app shows next to the plugin.

It needs Termix 26.10.6. Older versions refuse a manifest that has it, so set "engine": { "termix": ">=26.10.6", "api": "^1.13" }. How the app runs your plugin and checks its version is in Mobile app.

Environment variables​

List every environment variable your backend reads. They show up in your docs, on this site's environment variables page and on your plugin's page in Termix.

"env": [
{
"name": "HELLO_API_URL",
"description": "Where to send greetings.",
"default": "https://api.example.com",
"required": false
},
{ "name": "HELLO_TOKEN", "description": "Token for the API.", "secret": true }
]

termix-plugin validate warns when your code reads process.env.X and X is not listed.

Prefer settings over environment variables. Settings can be changed in the app, saved per user or host, and secrets are encrypted. Use an environment variable only for something that has to be set before Termix starts.

Editor help​

Point your editor at the schema for checks while you type:

{
"$schema": "./node_modules/@termix-ssh/plugin-sdk/schema/manifest.schema.json"
}