palyra-skills crate, the skill.toml manifest format, and the security model governing skill installation and execution. Skills are signed artifacts containing WASM modules, assets, and metadata that extend the daemon’s capabilities.
Skill Manifest (skill.toml)
The skill.toml file is the source of truth for a skill’s identity, requirements, and requested capabilities. It is parsed and validated by the palyra-skills crate before any artifact packaging or installation occurs.
Manifest Structure
A skill manifest defines several key sections:- Identity:
skill_id,name,version, andpublisher. - Entrypoints: Definitions of tools (functions) exported by the skill, including their JSON schemas and risk profiles.
- Capabilities: Requested access to system resources like the filesystem, HTTP egress, and secrets.
- Quotas: Execution limits for the WASM runtime (fuel, memory, timeouts).
- Compatibility: Minimum required protocol and runtime versions.
Example Manifest
crates/palyra-skills/examples/echo-http/skill.toml#1-45Validation Rules
Thevalidate_manifest function in manifest.rs enforces strict constraints:
- Namespacing: Tool IDs must be prefixed with the
publishername (e.g.,acme.echo) crates/palyra-skills/src/manifest.rs#74-79. - Safety: Skill IDs cannot contain dangerous characters or path traversal sequences crates/palyra-skills/src/tests.rs#149-163.
- Wildcards: Capability wildcards (e.g.,
*in egress or filesystem paths) require an explicitwildcard_opt_inflag in the manifest crates/palyra-skills/src/manifest.rs#100-137. - Schemas: Both
input_schemaandoutput_schemamust be valid JSON objects crates/palyra-skills/src/manifest.rs#92-97.
Skill Lifecycle
The lifecycle of a skill moves from development (packaging) to deployment (installation) and runtime management (quarantine/enable).1. Packaging & Signing
Thepalyra-cli uses build_signed_skill_artifact to create a .palyra-skill file. This is a ZIP archive containing:
skill.toml: The manifest.module.wasm: The compiled logic.signature.json: An Ed25519 signature of the payload (manifest + modules + assets).sbom.cdx.json: CycloneDX Software Bill of Materials.provenance.json: Build attestation data.
2. Installation & Verification
Duringpalyra skills install, the daemon performs a multi-step verification:
- Integrity: Verifies the Ed25519 signature against the payload crates/palyra-skills/src/lib.rs#24-24.
- Trust: Checks if the publisher’s public key is trusted (see Trust Model below).
- Audit: Scans the WASM module for security violations, such as excessive exported functions or module size crates/palyra-skills/src/audit.rs#1-10.
- Compatibility: Ensures the skill’s
min_palyra_versionis met by the current daemon crates/palyra-skills/src/manifest.rs#149-168.
3. Administrative State
Skills can be toggled between states via the CLI or Console API:- Quarantine: Disables a skill version, preventing its tools from being called. Requires a reason and operator principal crates/palyra-cli/src/args/skills.rs#138-158.
- Enable: Restores a skill to active status.
Skill Lifecycle Data Flow
The following diagram bridges the CLI commands to the internal crate logic and persistence. “Skill Lifecycle Flow” Sources: crates/palyra-cli/src/commands/skills.rs#5-105, crates/palyra-skills/src/lib.rs#11-24, crates/palyra-cli/tests/skills_lifecycle.rs#125-175Trust Model: TOFU & Pinning
Palyra employs a Trust On First Use (TOFU) model for skill publishers, combined with explicit allowlisting.Trust Decisions
When an artifact is verified viaverify_skill_artifact, it returns a TrustReport with one of the following decisions crates/palyra-skills/src/lib.rs#20-20:
- Allowlisted: The publisher’s public key was pre-configured as trusted.
- TofuPinned: The publisher was previously seen, and the current key matches the pinned key.
- TofuNewlyPinned: The publisher is seen for the first time, and the key has been added to the store (if
allow_tofuis enabled).
The Trust Store
TheSkillTrustStore is a JSON file that maps publisher IDs to their public keys. The CLI manages this via load_trust_store_with_integrity and save_trust_store_with_integrity, which ensure the store itself hasn’t been tampered with crates/palyra-cli/src/commands/skills.rs#117-127.
Verification Sequence
“Artifact Verification Logic” Sources: crates/palyra-cli/src/commands/skills.rs#106-140, crates/palyra-skills/src/lib.rs#8-9Runtime Capabilities & Policy
Once verified, a skill’s manifest is translated into runtime constraints and security policies.Capability Translation
Thepalyra-skills crate provides helper functions to convert manifest entries into objects used by the WASM host:
capability_grants_from_manifest(): Generates resource access tokens for the filesystem and network crates/palyra-skills/src/runtime.rs#21-23.policy_bindings_from_manifest(): Creates Cedar policy bindings for the tool authorization logic crates/palyra-skills/src/runtime.rs#21-23.
Resource Quotas
Thecapabilities.quotas section in the manifest defines the “sandbox walls” for the palyra-plugins-runtime:
- Fuel: Limits the number of WASM instructions to prevent infinite loops crates/palyra-skills/examples/echo-http/skill.toml#39-39.
- Memory: Sets the maximum linear memory available to the module crates/palyra-skills/examples/echo-http/skill.toml#40-40.
- Timeout: Wall-clock time limit for a single tool execution crates/palyra-skills/examples/echo-http/skill.toml#38-38.
| Feature | Manifest Key | Code Entity |
|---|---|---|
| Fuel Budget | capabilities.quotas.fuel_budget | wasmtime::Store::set_fuel |
| Memory Limit | capabilities.quotas.max_memory_bytes | wasmtime::ResourceLimiter |
| HTTP Egress | capabilities.http_egress_allowlist | palyra_plugins_runtime::EgressPolicy |
| Filesystem | capabilities.filesystem.read_roots | palyra_plugins_runtime::FsGrant |
Internals: palyra-skills Crate
The crate is organized into modular components handling specific aspects of the skill lifecycle:
artifact.rs: Handles ZIP encoding/decoding and path normalization for.palyra-skillfiles crates/palyra-skills/src/lib.rs#1-1.audit.rs: Implements the security scanner that inspects WASM bytecode for suspicious patterns crates/palyra-skills/src/lib.rs#2-2.manifest.rs: TOML parsing and semantic validation ofskill.tomlcrates/palyra-skills/src/lib.rs#5-5.trust.rs: Management of theSkillTrustStoreand TOFU logic crates/palyra-skills/src/lib.rs#8-8.verify.rs: Orchestrates the full verification pipeline (Signature -> Trust -> Audit) crates/palyra-skills/src/lib.rs#9-9.