wick-plugins

Using wick plugins

A plugin is a connector, tool, job, or service shipped as a standalone binary. wick downloads it, verifies it, and runs it in its own process. Installing or updating one needs no core rebuild and no restart.

From the LLM's side a plugin connector is indistinguishable from a built-in one — same tool_id shape, same encrypted fields, same audit trail, same tag-based access control. The difference is purely packaging.

The four kinds

Kind	Lifetime	Reached by	Notes
connector	on demand, idle-killed	the LLM via wick_execute	gRPC
job	spawned per run (cron / Run now), killed when Run returns	the scheduler	gRPC Job; shows on the Jobs page
tool	spawned on first request (held ≤10 s, then 503), idle-killed	users at /tools/{key}	HTTP over a unix socket, proxied by wick; "plugin" badge on the home grid; KeepWarm for fast webhooks
service	always on, restarted with backoff 1s→30s	outside systems at /x/{key}/*	per-route auth public / token / session; admin page Manager → Services → {key} (status, last 200 log lines, config, access token)

Installed under <data dir>/plugins/{connectors,jobs,tools,services}/<key>/. Plugin keys use _, never - — so a built-in tool text-counter moved to a plugin becomes /tools/text_counter.

Replacing a built-in (Replaces)

When a plugin takes over an existing tool or job under a new key (built-in notion-ticket-sync → plugin notion_ticket_sync), the plugin declares the old key so it is a replacement, not a new item:

job.Meta{Key: "notion_ticket_sync", Replaces: []string{"notion-ticket-sync"}, ...}   // job plugin
tool.Tool{Key: "text_counter", Replaces: []string{"text-counter"}, ...}               // tool plugin

It lands in plugin.json (job.meta.Replaces / tool.meta.replaces). On the next boot wick, once per old→new pair:

• copies config fields whose key the plugin also declares — secrets as the stored ciphertext, never decrypted. A field already set on the plugin is kept; only an empty field, or a non-secret still at the plugin default, is filled. A field whose secret flag differs is skipped;
• for jobs, copies schedule, enabled, max runs and timeout while the plugin's job row is untouched (default cron, disabled, never run); run history stays on the old key;
• merges the old item's tags, visibility override and bookmarks into the new path;
• hides the old item (not registered, not listed, its job row disabled on every boot), so the two never both run.