Plugin architecture: High-Level

[kjaymiller]

Proposal: A Plugin System for Valkey Admin

There are features proposed for this product that I think would be better suited as a plugin that isn’t included in the application.

Things like specific metric panels, embedded AI assistants, machine learning components like anomaly detection over metrics and logs. Every small feature becomes a permanent problem for the main application to bear. There are also small decisions that need to be made like each feature’s placement in the application. It also increases the complexity of the code-base and the size and attack surface of the deliverable.

The proposal

Give valkey-admin a plugin system. Each plugin would be exposed in a panel with access to the loaded page’s data that can be rendered into any of the app's seven existing sections (Dashboard, Key Browser, Send Command, Cluster Topology, Hot Keys, Big Keys, Command Logs).

What a plugin looks like, in practice

A plugin is two files: a small manifest declaring what it needs — page data, network hosts, credentials, etc — and a built script. A user installs it by pointing the app at those two files. The user adds the plugin via url.

Plugins should run inside a restricted execution boundary with no access to anything it wasn't explicitly given or specified it would need access to. It only has access to the data that is rendered on that page. Network access has to be declared to an exact destination and is enforced, not just requested. And what a user reviews at install time is guaranteed to be what actually runs later plugin content is checksummed and re-verified on every load, so a plugin can't quietly change behavior after the fact.

What ships now vs. later

The immediate ship is panels have the capability reading a section's data and rendering something new alongside it.

Future Capabilities would include**:**

• letting plugins restyle what's already there (safe, bounded theming plus a full-replacement option for a single row), rather than only adding new content.
• letting plugins run their own logic against data inside a shared sandbox. This would enable things like custom scoring, transformations, and WASM-backed compute.
• an actual marketplace and signed/verified plugins, once there's real usage to learn from.

First Steps:

1. Build the sdk that would define the registration of plugins.
2. Build the plugin adapter that allows for adding plugins into panes in the dashboard.

[ArgusLi]

Thanks for putting thought into this! I'm glad you wrote this document that really explains why this plugin architecture is needed and shows the underlying concern is a real one and worth discussing. Let's now talk about how it can be implemented.

• Where does plugin code execute? Renderer, a sandboxed iframe, a Web Worker, the Node server process, a separate child process? Each has completely different isolation and capability characteristics in an Electron app, and the answer determines whether the rest of the proposal is even achievable.
• What is the isolation primitive, and what does it actually contain? Same question for network enforcement: what layer intercepts and denies a request to an undeclared host, given we ship both an Electron app and a Docker/K8s server deployment?
• What is the manifest schema, and what is the SDK surface a plugin registers against?
• What is the compatibility contract? Plugins are third-party code pinned to an internal API; the proposal doesn't say how that API is versioned or what happens to a plugin when it changes.

"Access to the loaded page's data" is not something that exists as a stable contract today. Page data lives in RTK slices, shaped by our own websocket actions and epics, and we reshape those freely because they're internal. The moment plugins read them, our internal state shapes become a public API and we lose the ability to refactor them. That's a larger and more permanent commitment than any of the individual features this is meant to keep out of the core, and the proposal doesn't acknowledge it.

I'd suggest taking a look at docs/adr/ for the shape we use: Context, Decision, explicit Rationale per choice, then Consequences split into what it enables, what new obligations it creates, and what's in scope for the first increment.

Since this is such a big feature, I'd suggest picking the single smallest useful capability (read-only render into one section), and answer the execution-location, data-contract, and threat-model questions for just that. Then, we can go from there.

[kjaymiller]

Where does plugin code execute? Renderer, a sandboxed iframe, a Web Worker, the Node server process, a separate child process? Each has completely different isolation and capability characteristics in an Electron app, and the answer determines whether the rest of the proposal is even achievable.

The original design was to run in the same process running the rest of the React app in a ShadowDOM using SecureECMAScript (ses). This allows it to works identically in the Electron renderer, the Docker web build, and the Kubernetes web build, since all three run the same Vite-built frontend in a browser context.

cc: @ArgusLi

[kjaymiller]

@ArgusLi

What is the isolation primitive, and what does it actually contain? Same question for network enforcement: what layer intercepts and denies a request to an undeclared host, given we ship both an Electron app and a Docker/K8s server deployment?

The Compartment only governs code while it runs. A Panel's render() returns a React element tree that the host's own trusted runtime commits outside the Compartment. A JS wrapper is the only network-capable object endowed into the Compartment. A hostname check is done against a manifest allowlist before delegating to the real fetch. This covers every fetch() call the plugin's code makes directly.

It does not cover browser-native resource loads (<img>, CSS background-image, <iframe src>, etc). I'd suggest we plan to harden against these types of attacks.

[kjaymiller]

@ArgusLi

What is the manifest schema, and what is the SDK surface a plugin registers against?

We'd need to define the specifics, but the manifest would need some generics (id, name, version, hash) as well as some permission access requests.

The SDK would surface would need the PanelLocation information, the module (plugin functionality that is executed), and properties.

These attributes and properties should be discussed as a team and decided upon.

[kjaymiller]

@ArgusLi

Access to the loaded page's data" is not something that exists as a stable contract today. Page data lives in RTK slices, shaped by our own websocket actions and epics, and we reshape those freely because they're internal. The moment plugins read them, our internal state shapes become a public API and we lose the ability to refactor them. That's a larger and more permanent commitment than any of the individual features this is meant to keep out of the core, and the proposal doesn't acknowledge it.

The original plan was to restrict the number of queries made and reuse data already fetched. If there is a concern around the shape of the data, we could always offer the ability to query the data.

[KIvanow]

I saw this and wanted to share my limited experience from another relevant product. I ran the RedisInsight team, and our Workbench plugins were a constant source of security problems, mostly from decisions that looked fine at design time.

Our iframe sandbox used allow-same-origin, so plugin code shared the app origin and could reach window.parent.document. Our own bootstrap code depended on that, so we could never tighten it without breaking every plugin. The CSP (connect-src 'none') blocked fetch and websockets but not <img> or CSS url loads, so exfiltration stayed possible. Same gap as conceded above for the fetch wrapper. If you enforce network policy in JS instead of the platform, you get this hole.

Our actual security model was a line in the docs saying "only install plugins from trusted authors". We got away with it because install meant copying a folder to disk. With URL install you don't get that excuse. The sandbox has to actually hold, and ours never did.

The one thing that saved us was scope. Plugins only visualized one command's output and got {command, result} plus five host functions, never app state. So @ArgusLi "internal state becomes a public API" problem never bit us, and a bad plugin could only mess up one result card. This proposal starts with page data across seven sections.

Even with that tiny scope and a lenient trust model, plugins cost us a lot of security work. If this moves forward I'd do what Argus suggests: smallest capability, threat model first.

Last thing: who will use it? At RI the plugin push came from PMs wanting to emulate VS Code, and nobody ever built an external plugin. Here it's coming from the community, so maybe it's different. I'd want to see that proven before paying the costs above, because our failure mode was the expensive one: a sandbox, a frozen API, and permanent security duty for an ecosystem that never showed up.

Anyway, these are just my two cents from a very high level read through and might 've missed something ao take it with a grain of salt

[kjaymiller]

Even with that tiny scope and a lenient trust model, plugins cost us a lot of security work. If this moves forward I'd do what Argus suggests: smallest capability, threat model first.

I do agree that there is security work that will need to happen. Perhaps most of this can be managed by a nutrition label style disclosure as well as hash-verification and signing. This also can oppen the door to things like

Last thing: who will use it? At RI the plugin push came from PMs wanting to emulate VS Code, and nobody ever built an external plugin. Here it's coming from the community, so maybe it's different. I'd want to see that proven before paying the costs above, because our failure mode was the expensive one: a sandbox, a frozen API, and permanent security duty for an ecosystem that never showed up.

My case for this was actually for it to be utilized by cloud providers to integrate into their platforms. This would allow them to have consistent ways to customize their instance of valkey-admin without us having to maintain third-party integrations. Aiven (my employer) may want to build some custom logic that shows the savings against the data services that cache hits provide in terms of networking costs and bandwidth. Other companies could have similar plugins inspired (or forked) from that type of system and this removes the maintenance and bloat of this from the valkey-admin team.

Lastly plugins would allow us to keep the core thin and agnostic. There are always features that will get more use than others. there could be custom visualizations for things like FT.search and bloomfilters that not everyone uses. I do think and originally proposed this as a way for the valkey-admin team to potentially build plugins that would allow for base deployment of features that could be modified by a service provider to fit their specific needs. Something like exposing billing to something like AWS Bedrock savings by a semantic cache and then Azure, OpenAI or Anthropic could fork and provide their version as well.

[KIvanow]

The cloud provider use case is interesting, because I think it changes what you'd build. Aiven, AWS, Azure are a handful of known partners who control their own
deployments. They don't need a runtime sandbox, URL install, checksums or network enforcement. A documented build-time extension point would do it, and the core stays thin like you want. The expensive machinery here (the SES compartment, the fetch wrapper, exfiltration hardening) only exists to run untrusted code, and that's the audience we haven't seen show up yet. I'd build the build-time version first and leave the sandboxed one until someone asks for it.

On the nutrition label + signing: that solves provenance, not containment. Signing tells you who wrote the plugin and that it hasn't changed since you installed it.
At RI that was never our problem. We effectively had "trusted authors only" and it still cost us, because the failures were about what code could do once it ran.
A signed plugin with a leaky sandbox is still a leaky sandbox. Which loops back to the same split: signing is enough for known partners, and not enough for untrusted code, so the two audiences really do need different designs.

[kjaymiller]

I agree on the run at buildtime but I also wonder how that works from a "want/don't want from users" #400 is a great example of a feature that I would personally want included by default in my project for potentially a few reasons. If it's a plugin, it's something whose logic is separated and can be added by users.

I'd say the same thing with custom visualizations, valkey-plugin features, etc.

I agree with the maybe waiting for things like nutrition labels, but that doesn't mean that we couldn't use the architecture to make valkey extensible with optional features built by the valkey team.