Skip to main content
YourSSH has two kinds of plugins. They coexist at runtime and appear together under Plugins in the sidebar. To write a script plugin, see Plugin authoring.

Built-in Dart plugins

Dart plugins are registered in app/lib/plugins/plugin_registry.dart in the kRegisteredPlugins list. The three that ship today are:

Add a Dart plugin

1

Add the package

Add it to the dependencies in app/pubspec.yaml (and to dependency_overrides if it is a local package under packages/).
2

Register it

Import it in plugin_registry.dart and add an instance to kRegisteredPlugins.

The YourSSHPlugin interface

Every Dart plugin implements YourSSHPlugin from packages/yourssh_plugin_api:
  • buildUI(context, pluginContext) returns the plugin’s widget. Wrap it in YsPluginHost (from yourssh_ui) so it keeps the app’s forui theme even when it is mounted outside the app’s root builder, as Snippets, DevOps and Web Tools do.
  • onActivate(ctx) and onDeactivate() are lifecycle hooks.
  • minApiVersion is checked at runtime against the app’s API version.
YourSSHPluginContext gives a plugin controlled access to the app: the active sessions, execCommand(sessionId, cmd), sendInput(sessionId, text) to type into a session’s terminal (Snippets uses it to insert a snippet), and namespaced savePreference and getPreference. Dart plugins can be switched on and off with feature flags in Settings.

JavaScript script plugins

Script plugins live in ~/.yourssh/plugins/, one folder each, with a plugin.json manifest. The runtime is the packages/yourssh_script_engine package.

Components

  • PluginManifest parses and validates plugin.json: id, name, version, entry file, minimum app version and permissions. An unknown permission is rejected.
  • PluginUiRegistry lets a plugin register UI through ui.register(id, spec); the app renders it in the plugin manager. A plugin can also declare a panel, an HTML view shown in the app. A panel is plugin-controlled HTML, so its messages to the app (running a command, listing sessions, reading a file) go through the same permission checks as the JavaScript bridges.
  • The plugin manager screens let users enable or disable a plugin, reload it and read its console.log output.

Hooks

The HookBus delivers typed events to plugin handlers in three styles: The app wires the bus into SshService, so plugins see terminal.output, terminal.input, session connect and disconnect events, and ssh.exec command events. The complete list of events and the permission each one needs is in Plugin authoring.

Bridges

Bridges are the Dart APIs a plugin can call from JavaScript:

Permissions

A plugin must declare each permission in its manifest. The recognized permissions are: terminal.read, terminal.transform, terminal.intercept, terminal.inject, session.observe, session.control, ssh.exec, sftp.read, sftp.write, command.intercept, ui.notify, ui.statusbar, ui.panel, ui.clipboard. PermissionGuard checks the manifest before it dispatches any bridge call. Observing is separate from changing: terminal.read observes output only, and rewriting it needs terminal.transform. The first time a plugin loads, the app shows a consent dialog listing the permissions it asks for. The user must accept before the plugin runs.
  • Consent is bound to a SHA-256 hash of every file in the plugin folder. Change any file and the user is asked again.
  • Stored grants are intersected with the manifest’s current permissions, so a plugin can’t gain a permission by editing its manifest.
  • Pending consent requests queue in order.
  • manifest.entry and a panel’s HTML entry must stay inside the plugin folder. Paths with ../, absolute paths and symlinks that escape are rejected.

Execution limits

The C bridge (packages/yourssh_script_engine/native/bridge/qjs_bridge.c) enforces hard limits on every plugin: A call that exceeds its deadline raises QuickJsTimeoutException.

Circuit breaker

PluginErrorTracker protects the app from a misbehaving plugin. An error counts 1, a timeout counts 5 and a success resets the count. At 10, the plugin’s hooks are skipped and the plugin is unloaded. The user can see what happened in the plugin’s console.

Reserved built-in ids

The ids of the built-in Dart plugins are reserved. PluginLoader never loads or prompts for a script plugin with a reserved id, so a script plugin can’t impersonate Snippets, DevOps Hub or Web Tools.
Only the macOS arm64 QuickJS library (libqjsbridge.dylib) is prebuilt. See Build from source to rebuild it after changing the C bridge.