Skill Artifact Lifecycle
A “Skill” is a signed bundle containing Wasm modules, metadata, and security manifests. The lifecycle is managed by thepalyra-skills crate and the palyra skills CLI command group.
1. Packaging and Signing
Skills are packaged into a specific archive format (.palyra-skill) containing a skill.toml manifest, Wasm modules, and cryptographic signatures.
- Manifest: Defined in
skill.toml, it specifies tool entrypoints, required capabilities, and compatibility constraints crates/palyra-skills/examples/echo-http/skill.toml#1-45. - Build Process: The
build_signed_skill_artifactfunction orchestrates the creation of the archive, calculating SHA-256 hashes of payloads and signing them with an Ed25519 key crates/palyra-skills/src/lib.rs#11-11. - CLI Integration: The
palyra skills package buildcommand handles file reading, manifest parsing, and signature generation using keys stored in the Vault or provided via stdin crates/palyra-cli/src/commands/skills.rs#5-67.
2. Verification and Trust (TOFU)
Palyra employs a Trust-on-First-Use (TOFU) model for skill publishers, managed via aTrustStore.
- Audit: Before installation,
audit_skill_artifact_securityperforms static analysis on the Wasm binary, checking for excessive exported functions or module size crates/palyra-skills/src/lib.rs#12-15. - Verification:
verify_skill_artifactvalidates the cryptographic signature against theTrustStore. If a publisher is unknown andallow_tofuis enabled, the key is pinned for future updates crates/palyra-skills/src/lib.rs#24-24, crates/palyra-cli/src/commands/skills.rs#106-126. - Trust Store: A persistent registry of trusted publisher public keys, ensuring that once a skill is accepted, only the same publisher can provide updates crates/palyra-cli/src/commands/skills.rs#117-127.
Artifact Structure Diagram
This diagram bridges the physical file structure to the internal logic used during verification. Title: Skill Artifact Verification Flow Sources: crates/palyra-skills/src/lib.rs#1-24, crates/palyra-cli/src/commands/skills.rs#106-141Plugin Runtime (Wasmtime)
Thepalyra-plugins-runtime crate provides the execution environment for Skill modules using wasmtime. It enforces strict isolation and resource limits.
Execution Model
TheWasmRuntime manages the lifecycle of a single execution call:
- Instantiation: Creates a
wasmtime::StorewithRuntimeStoreStatecontaining limits and capability handles crates/palyra-plugins/runtime/src/lib.rs#161-172. - Fuel Injection: Uses Wasmtime’s fuel mechanism to limit CPU cycles crates/palyra-plugins/runtime/src/lib.rs#174-174.
- Epoch Interruption: Handles wall-clock timeouts via an async-friendly epoch deadline crates/palyra-plugins/runtime/src/lib.rs#175-177.
Capability Sandboxing
Plugins cannot access the host system directly. They interact through a set of host functions (imports) that are gated byCapabilityGrantSet.
| Capability | Host Function Prefix | Description |
|---|---|---|
| HTTP | host_capability_http_ | Gated by http_egress_allowlist in manifest. |
| Secrets | host_capability_secret_ | Access to specific Vault keys mapped to the skill. |
| Storage | host_capability_storage_ | Prefixed filesystem access within the state root. |
| Channels | host_capability_channel_ | Interaction with specific chat connectors. |
Runtime Execution Diagram
This diagram maps thepalyra-daemon runner to the underlying wasmtime primitives.
Title: Wasm Plugin Execution Pipeline
Sources: crates/palyra-daemon/src/wasm_plugin_runner.rs#96-126, crates/palyra-plugins/runtime/src/lib.rs#105-186
Quarantine and Security Audit
The daemon implements a quarantine mechanism for skills that fail security checks or lack explicit operator approval.Quarantine Triggers
A skill enters a quarantined state if:- Signature Mismatch: The artifact signature does not match the pinned key in the
TrustStore. - Audit Failure: Static analysis detects risky imports or exceeds module size limits (
DEFAULT_SKILL_AUDIT_MAX_MODULE_BYTES) crates/palyra-skills/src/lib.rs#14-14. - Policy Violation: The skill requests capabilities (e.g., broad filesystem access) not permitted by the global
palyradconfiguration.
Inventory Management
The CLI provides tools to inspect the status of installed skills and manage their lifecycle.- List:
palyra skills listshows theinstall_state,runtime_status, andtrustdecision for every skill in the inventory crates/palyra-cli/src/output/skills.rs#41-55. - Check:
palyra skills checkperforms a comprehensive validation of the local skills root, reportingquarantine_requiredandaudit_passedflags crates/palyra-cli/src/output/skills.rs#101-119.