Install a plugin

install, list, show, uninstall, and where packages come from.

Written By Dustin

Last updated 27 minutes ago

tovio plugin install <source>tovio plugin listtovio plugin show <id>tovio plugin uninstall <id>

Plugins live in the repository's local store at .tovio/plugins/<id>/, and bindings in .tovio/plugins/bindings.toml. Uninstalling removes the store directory and drops any local bindings that referenced it, so you do not leave a dangling binding behind.

What a source can be

Source	Accepted
A local directory holding `manifest.toml` plus its runtime artifact	Yes.
A bare local `manifest.toml`	Yes — installs a manifest-only package. It can be inspected and validated, but not executed.
An HTTPS URL ending in `/` or `/manifest.toml`, serving a sibling `plugin.wasm`	Yes, under the retrieval rules below.
Anything else — `forge://`, another scheme, an archive to extract	No. Refused with `TVO-PLUGIN-002`.

How HTTPS install is bounded

Remote install is deliberately narrow, because a package fetch is a supply-chain step:

System-root certificate verification, with bounded connect and I/O deadlines.
A 1 MiB cap on the manifest and a 64 MiB cap on the artifact, enforced while reading rather than after.
URL credentials, fragments, query strings, redirects, non-success responses, and alternate schemes are all refused.
The artifact hash, publisher signature, trust, and revocation decision must all pass before the local store changes. Nothing partial is ever written.
Remote local_dev and hash-only packages are refused outright. Those are a local development posture, not something to pull off the network.

So the practical order for a remote package is: trust the publisher's identity first, then install.

tovio plugin trust add did:key:<64 hex digits> --label "Example Corp"tovio plugin install https://plugins.example.com/license-check/

Verify before you bind

tovio plugin validate <source>tovio plugin verify <id>

A plugin runs against your code. Check integrity, signature, publisher, and revocation before binding it — especially in enforcing mode.

What install does not do

Installing does not bind. A plugin sits inert until you bind it to an event, which is a separate deliberate step. The one exception is the built-in secret scanner, which is embedded in the binary and needs no install at all.

Integrity is fail-closed

If the stored artifact's recomputed hash does not match the manifest, installation fails with TVO-PLUGIN-003. There is no override. The same check runs again before every execution, so a package tampered with after install does not get a second chance.

Health check

tovio plugin doctor

doctor reads the whole store without executing anything: every manifest parses and validates, every artifact's integrity is checked, and every binding resolves to an installed plugin and a declared event. It exits non-zero on any problem, so CI can gate on it.