Skip to main content

How it works

Where plugins run​

A plugin runs in two places:

  • Its backend runs in its own Node process, started and watched by Termix.
  • Its frontend runs in the browser, in the same page as the rest of Termix.

Every plugin, official or not, runs the same way. The backend process can read only its own folder, opens no sockets or child processes unless a capability allows it, and talks to Termix only through ctx. See the plugin process.

Capabilities: what your code may do​

A capability is something your backend code is allowed to do, like ssh:connect (run commands on hosts) or network:outbound (make HTTP requests). List what you need in capabilities in the manifest.

  • An admin sees the list, worst first, before installing your plugin.
  • Every ctx method that needs a capability checks it. Calling one you didn't list throws PluginCapabilityError.
  • Every privileged call, allowed or refused, writes an audit line with your plugin's id and the user it ran for.
  • An update that adds a capability waits for an admin to approve it.

Ask for as little as you can. See all capabilities.

Permissions: what a user may do​

A permission is something a user can do, like docker.use. You declare short names in contributes.permissions, and Termix registers them as <your id>.<name>. Admins give them to roles. See permissions.

Capabilities and permissions are different things. A capability is about your code. A permission is about the person using it. They are spelled differently so you can't mix them up: hosts:read is a capability, hosts.view is a permission.

The actor​

Most backend calls run as a user, called the actor. In a route it is the signed-in user, set by Termix, never by you. ctx.currentActor() returns it.

For background work with no request, like a timer, use ctx.asUser(userId, fn). It is always audited, and everything inside still applies that user's permissions.

Lifecycle​

  1. Termix applies your migrations.
  2. It calls activate(ctx) on the backend, in dependency order.
  3. After sign in, the browser loads your frontend and calls activate(app).
  4. When an admin disables the plugin, or Termix stops, it calls deactivate() and removes everything you registered.

Rules that keep this working:

  • Create everything inside activate: No servers, timers or connections at the top of a module. A disable and enable runs activate again on the same module.
  • Register cleanup: Things made through ctx and app are cleaned up for you. Anything you make yourself goes in ctx.disposables.add(fn) or app.onDispose(fn).
  • Never touch process.exit or signals: Termix stops plugins in order on shutdown.
  • Enable, disable, enable must work without a restart.

When things go wrong​

A plugin is in one of four states:

StateMeans
enabledRunning.
disabledTurned off by an admin.
blockedA plugin it needs is missing or off.
failedactivate threw, or it hit its error budget.

Errors from your routes, sockets, event listeners and timers count against an error budget. Five inside a minute and Termix turns the plugin off, so a plugin that throws on every call can't drag the server down. An admin can press Restart to try again. A 4xx you send on purpose does not count.

What Termix protects, and what it doesn't​

The capability system means:

  • What a plugin can do through ctx is listed before you install it.
  • Calls it didn't ask for are refused.
  • Every privileged call leaves an audit line.

Since plugin API 2 a plugin is also contained: its backend runs in its own process under Node's permission model, so it can't read the database, the keys or other plugins' files, and in Docker it runs as its own Linux user. The desktop app runs it the same way inside the operating system's sandbox. Its frontend runs in sandboxed frames that reach only its own routes, see Frames. It still has everything its capabilities give it, so signing, review and admins only installing code they trust still matter. A plugin made for plugin API 1 doesn't run at all, see Moving from API 1.

Write your plugin as if the admin will read every capability and every line of the audit log. Many will.