Skip to main content

Services

A service is how one plugin offers something to others, like Snippets offering snippets.access to Automations. Services are typed, versioned and checked per call against the caller's permissions.

Offer one​

Declare it in the manifest:

"provides": [
{ "service": "hello.greetings", "version": "1.0.0", "permission": "hello.use" }
]

Then provide it in activate:

ctx.services.provide("hello.greetings", {
async list() {
const userId = ctx.currentActor();
return listGreetings(userId);
},
});

The service name needs a dot, and should start with your id. permission is checked for the calling user before every call, and the call runs as that user, so read them from ctx.currentActor(). Never take a user id from the caller.

Treat a service like a public API. Add methods in a minor version. Bump the major to remove or change one.

Use one​

"requires": [{ "service": "hello.greetings", "versionRange": "^1.0.0", "optional": true }],
"optionalDependencies": { "hello": "^1.0.0" }
const greetings = ctx.services.get<GreetingsService>("hello.greetings");
if (greetings) {
const list = await greetings.list();
}

get returns nothing while no compatible provider runs. Plugins come and go, so always handle that. If you can't work without it, list the plugin in dependencies and the requirement without optional. Termix then won't start you without it.

For background work, ctx.services.get(name, { userId }) calls as another user. That is the same as ctx.asUser and is audited.

Several providers​

When several plugins provide the same service side by side, each one names itself. sessions.live is provided by the SSH terminal as ssh and by Remote Desktop as rdp, vnc and telnet. List the names in provides[].names, provide with { name }, and reach one with ctx.services.get(service, { provider }).

Events​

For "something happened" rather than "do something", use events. Emit plugin.<your id>.<name> with ctx.events.emit. Anyone can listen with ctx.events.on without a capability.

Frontend​

The frontend has its own ways to work across plugins: actions, slots, components and extensions. See more extension points.

Services you can use​

Each plugin's reference page lists what it provides and uses. Some useful ones:

ServiceFromWhat it does
snippets.accessSnippetsRead and run saved snippets.
tunnels.accessTunnelsOpen a port forward.
docker.containersDockerList containers and act on them.
sessions.liveSSH Terminal, Remote DesktopLive sessions.
recordings.writerSession RecordingWrite a recording.
wake-on-lan.sendWake-on-LANWake a host.