Manifest reference

The plugin manifest (manifest.toml) is the source of truth for a plugin's identity, runtime, supported events, requested capabilities, schema versions, and integrity metadata. It deserializes into tovio-core's PluginManifest, whose shape a round-trip test pins against the normative example in the plugin spec. The file name matters: tovio plugin install, validate, and test look for manifest.toml inside a package directory (a bare manifest file passed directly may carry any name).

Full example

id          = "com.example.license-check"
name        = "Example License Check"
version     = "1.2.0"
publisher   = "Example Corp"
publisher_identity = "did:key:1111111111111111111111111111111111111111111111111111111111111111"
api_version = "v1"
type        = "check"
runtime     = "wasm-wasi"
events      = ["pre-land", "proposal-created"]
timeout_ms  = 5000

[schemas]
input  = "v1"
output = "v1"

[capabilities]
read_metadata            = true
read_clear_paths         = ["Cargo.toml", "Cargo.lock"]
read_protected_metadata  = false
read_protected_plaintext = false
write_working_copy       = false
write_plugin_cache       = false
network_access           = false
emit_audit               = true
invoke_tovio_command     = false
propose_resolution       = false
propose_transform        = false
block_operation          = true

[integrity.signed]
sha256    = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
signature = "ed25519:<128 hex digits>"

Top-level fields

Field	Type	Required	Notes
id	string	✓	Globally namespaced, e.g. com.example.license-check. Reverse-DNS style is idiomatic.
name	string	✓	Human-readable display name.
version	string	✓	Semver-compatible; used for ordering, pinning, and audit.
publisher	string	✓	Human-readable publisher identity.
publisher_identity	string	–	Optional Ed25519 publisher identity, did:key:<64 hex digits> (the 32-byte public key). Required when the package carries a publisher signature; the signature covers it (REQ-PLUGIN-087).
api_version	string	✓	Plugin API version this plugin targets. MVP is "v1".
type	enum	✓	One of check, transform, resolver, policy-adapter, notifier.
runtime	string	✓	wasm-wasi is the runtime the sandbox executes. native is refused at validation (REQ-PLUGIN-045).
events	array	✓	The lifecycle events this plugin supports — any of the names on Lifecycle events; unknown names fail validation.
timeout_ms	integer	✓	Wall-clock deadline per invocation: non-zero and at most 300000 (5 minutes). The sandbox derives its instruction (fuel) budget from it (REQ-PLUGIN-039).
integrity	tagged	✓	Either integrity = "local_dev" (bare key) or a [integrity.signed] table.

[schemas] is a required table:

Field	Type	Notes
schemas.input	string	Input schema version. MVP is "v1".
schemas.output	string	Output schema version. MVP is "v1".

[capabilities] (optional)

Deny-by-default. Omit the table entirely to accept the default set (which grants only read_metadata). When the table is present it has to list every field below: the parser has no per-field defaults, so a partial table is refused with TVO-PLUGIN-001 (missing field …).

Capability	Type	Default	Meaning
read_metadata	bool	true	Read event metadata (paths, change kind, actor, target).
read_clear_paths	array of globs	[]	Cleartext contents allowed for these glob patterns only.
read_protected_metadata	bool	false	Read redacted metadata for protected paths.
read_protected_plaintext	bool	false	Read protected-file plaintext. Requires the full §10 approval chain.
write_working_copy	bool	false	May propose working-copy changes (needed for transform plugins).
write_plugin_cache	bool	false	May write to the plugin's own sandbox-scoped cache.
network_access	bool	false	Egress permitted. Deny remains the default.
emit_audit	bool	false	May write structured audit metadata.
invoke_tovio_command	bool	false	May call back into tovio (heavily gated).
propose_resolution	bool	false	May propose a conflict Resolution (needed for resolver).
propose_transform	bool	false	May propose transforms.
block_operation	bool	false	Declares that the plugin may block when bound in enforcing mode.

Two consistency rules apply at validation: read_protected_plaintext = true requires read_protected_metadata = true (a contradictory request is refused rather than silently narrowed), and a manifest declaring transcript-parse has to request nothing beyond the default set — that event runs with an empty grant by construction (REQ-PLUGIN-091). Every read_clear_paths glob has to parse.

The effective capability set at execution time is the intersection of manifest, binding, actor authorization, and (for agents) the agent's capability token. See Capabilities & security.

integrity — tagged variant

Exactly one form MUST be present. integrity is a tagged variant: either the bare local-dev marker or the signed table.

Local development (before signing / distribution):

integrity = "local_dev"

Position matters

Because integrity = "local_dev" is a bare top-level key, it MUST appear before the first [table] header in the file (before [schemas], [capabilities], etc.). If you place it after a table header, TOML parses it as a subkey of that table and the manifest fails to validate (TVO-PLUGIN-001, missing field integrity).

Signed (for distribution):

[integrity.signed]
sha256    = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
signature = "ed25519:<128 hex digits>"  # optional; sha256 is required

Installers refuse packages whose runtime artifact does not hash to sha256 (TVO-PLUGIN-003). A signature is the Ed25519 signature, as ed25519: plus hex, over the canonical manifest-without-signature and the artifact digest; it verifies against the top-level publisher_identity and the repository-local publisher trust store (tovio plugin trust add, revoke, list). HTTPS installs require the signed, trusted form (REQ-PLUGIN-087–089; the decision record is ADR-0080 in the repository); a hash-only or local_dev package installs from a local path as a development-policy package and is never reported as publisher-verified.

Validation

Run tovio plugin validate ./my-plugin (a package directory) or tovio plugin validate ./manifest.toml to check the manifest without executing anything. The validator is a pure tovio-core check — no sandbox, nothing written — and catches:

• malformed or non-namespaced id (REQ-PLUGIN-006),
• non-semver-ordered version (REQ-PLUGIN-007),
• unknown type (REQ-PLUGIN-010),
• runtime = "native", or an empty runtime,
• unknown event names, or an empty events list (REQ-PLUGIN-021),
• a zero or over-cap timeout_ms,
• missing [schemas],
• both integrity variants missing,
• local_dev placed after a table header,
• a partial [capabilities] table, a contradictory plaintext request, a transcript-parse manifest that requests a capability, or an unparseable read_clear_paths glob.

Last reviewed September 9, 2026

Suggest an improvement to this page  ·  Not for security reports — see disclosure