Skip to content

Integrations and plugins

Responsibility

Integrations connect user accounts and external systems. Plugins extend Gnosi with declarative contributions and bounded executable behavior. MCP servers contribute agent tools through a separate protocol boundary.

Integration persistence

The integration manager stores non-secret account configuration and references to secrets under local data. Each machine reconnects accounts independently. Settings APIs list masked connection state, validate configuration, test connectivity, choose defaults, and disconnect providers without exposing raw tokens.

Google and Microsoft OAuth callbacks create or update provider records. IMAP, SMTP, CalDAV, Drupal, Notion, and similar adapters normalize their own settings into the common integration registry where possible.

Plugin lifecycle

stateDiagram-v2
    [*] --> Discovered
    Discovered --> Validated
    Validated --> Installed
    Installed --> Enabled
    Enabled --> Disabled
    Disabled --> Enabled
    Installed --> Removed
    Disabled --> Removed

Plugin packages declare identity, version, compatibility, permissions, contributions, and integrity information. Installation validates paths, manifest structure, signatures where required, and declared effects. Enabling reconciles managed settings, AI profiles, skills, or tools idempotently. Disabling suspends managed contributions while preserving user-owned overrides.

Built-in secondary capabilities use the same per-Vault lifecycle boundary. The authoritative registry declares dependencies, routes, UI surfaces and Settings destinations. .gnosi/plugins.json schema version 2 records explicit enabled_builtin and enabled_third_party lists while retaining disabled for older clients. Migration from an older or missing schema is atomic and idempotent: every optional capability starts disabled and all settings, permissions and unknown forward-compatible records are retained.

Lifecycle changes go through the general POST /api/vault/plugins/{id}/lifecycle contract. A change with prerequisites or enabled dependents first returns a structured conflict; an administrator then confirms the grouped activation or cascade. Disabled routes fail before their feature implementation runs, and scheduled external work checks the same registry. Core maintenance, Markdown, database calendar views, contact fields, media attachments and drawings do not depend on these plugins.

Plugins Settings owns installation, activation, permission grants, updates and removal. Configuration for active capabilities is exposed under Connections, Knowledge or Advanced. A configure action opens that destination directly and capabilities without global configuration do not create empty pages.

Executable plugin behavior runs through a sandbox boundary with a constrained environment and timeout. Plugins do not receive the complete host environment or arbitrary secret access.

Direct networking stays disabled in both plugin runtimes. A granted network capability exposes only the host RPC, which rejects private destinations and bounds methods, redirects, time, and response size. UI frames keep connect-src 'none'; the parent calls the same backend boundary after checking the plugin's declared and granted permissions.

Third-party plugins may declare the additive ui:settings permission and call gnosi.registerSettingsPanel(...). Active and granted panels appear in the dynamic Extensions group, render inside the existing opaque-origin iframe sandbox and disappear as soon as the plugin is disabled, revoked or removed. Reading or writing the plugin's own configuration additionally requires the existing settings permission. The host API remains at major version 2.

Marketplace distribution

The official plugin index and its detached signature are published as GitHub Release assets. Remote catalog installation requires a trusted signed index and every selected package requires both SHA-256 integrity and a trusted detached Ed25519 signature. Installed provenance records the source URL, checksum, and verified publisher. Local ZIP installation remains available for development, but starts disabled with no grants.

Installed plugins can be exported as deterministic ZIPs. Public submission is an administrator operation sent to an explicitly configured moderation broker; Gnosi never embeds a GitHub write token. The broker quarantines the package and publishes it only after CI and human review.

MCP boundary

Configured MCP servers are independent processes or remote endpoints. Startup discovers their tool schemas and normalizes them into the agent catalog. Retry and Retry-After handling are bounded. One failed server is recorded without discarding tools from healthy servers.

Example and companion integrations

The repository includes example plugin packaging, a Drupal MCP proxy, the LibreOffice citation extension, and a Word citation helper. These are separate clients with narrow backend contracts; they do not share backend filesystem or credential access automatically.

Invariants

  • Integration secrets live outside Git and the synchronized vault.
  • Disconnecting removes or revokes the local credential reference and selected defaults consistently.
  • Plugin-managed and user-managed values remain distinguishable.
  • Archive extraction and plugin paths cannot escape their installation root.
  • Compatibility and permission validation occurs before activation.
  • Official indexes and remote packages fail closed when integrity metadata is missing.
  • Direct plugin sockets and browser connections never bypass the host RPC.
  • A disabled capability cannot start a new route, sync, automation or external effect.
  • Disabling or migrating never deletes plugin data, settings, credentials or profiles.
  • MCP tool origin and effect remain visible after catalog normalization.

Verification focus

Run plugin manifest, signing, sandbox, state-race, AI contribution, MCP routing, retry, and connector tests. A live integration test uses a dedicated test account and must not mutate production data unintentionally.