DEV Community

Rose
Rose

Posted on

Your agent plugin is code. The install screen should say what it can reach.

A plugin for an AI agent is not configuration. Too often it is code running with the agent's credentials, inside the agent's process, on a schedule nobody watches. The install screen is the last point where a human can decide anything about it, and that screen often tells you only a name, a version, a download count and a one-line description.

None of those answers the only question that matters: what can this thing reach?

I don't think the answer is "read the source, it's open." You can read a plugin's source and still be wrong about reach, because reach is a property of the runtime as much as the code. Two plugins with identical source can touch completely different things depending on what process they land in, what the filesystem looks like around them, and whether outbound calls are checked against anything. So the useful question for a plugin host is narrower and more concrete: what does the runtime refuse to let this code do?

Here's what we refuse, and why each one is worth the trade.

Disclosure first, because it belongs at the top and not in a footer: I write this for AgentParley, a hosted crew of specialist agents. The post describes our plugin model. The engineering arguments below are ones I'd make to any team running third-party agent extensions.

One call, one box

Every plugin call runs in a fresh sandbox, and it runs one call at a time.

That's a heavier choice than it sounds. Spawning a box per call costs latency and engineering that per-plugin installations don't. The reason to pay it is that it makes a specific class of bug cost one call instead of an installation.

Consider what a plugin can accumulate if it shares a process with the agent across a long session:

  • State it wrote in call one and reads in call four. Harmless until it's a cache poisoning bug or a flag that turns off a check in a later call. With a fresh box per call, call four starts with no in-memory or module state from call one. A plugin can still hold state, but only through an explicit platform interface — workspace storage, settings, or a live connection — rather than a variable left lying around.
  • An escalation through leftover process state. One call changes module state that weakens a check in the next. Fresh boxes remove that path; explicit workspace access is a separate, visible permission, not an accidental inheritance.
  • A leak between jobs. The same plugin runs for a scheduled job at 06:00 and a chat at 09:00. In a shared process, "fresh state per run" is a convention; in a fresh box it's a property.

One call at a time is the weaker half of the same idea. Concurrency inside a plugin means two invocations sharing whatever the plugin holds in memory, and it means a slow or looping call can stack up behind the dispatcher. Serial and fresh is a simpler contract to reason about, and simplicity is the thing you want at the boundary of code you didn't write.

Withholding the obvious

The sandbox has no direct OS filesystem access and no process object.

That line will lose us some plugins, and I'd rather say so than write it vaguely. A plugin cannot shell out to a CLI or read environment variables. It gets what the plugin interface hands it. File access is deliberately narrower too: there is no ambient disk to walk; a plugin that needs the agent's workspace must request that explicit workspace permission, which appears on the install screen.

The reasoning is mechanical rather than ideological. An OS process has a large reach by default; a plugin's actual job is usually narrower. It wants to call an API, parse a response, and hand back a result. So the isolate starts with no OS reach and exposes specific host interfaces instead. When a job genuinely needs root or the whole filesystem, that belongs on your own machine over SSH or the tunnel, with its own permissions — not in a plugin.

Outbound calls checked against declared hosts

A plugin call can reach the network. It can't reach arbitrary addresses while claiming it only talks to one host.

Outbound calls go through a gateway, and the gateway checks the destination host against the hosts the plugin declared. A call to somewhere else doesn't get quietly logged and retried; it's refused.

Two reasons this matters beyond the obvious one.

First, egress is how data actually leaves a system. A plugin with no direct OS filesystem or process access can still exfiltrate anything it was handed, if it can call anywhere. Scaling that down isn't a nice-to-have; it's the difference between a sandbox and a pane of glass.

Second, the declared hosts are part of the review artifact. "This plugin talks to api.example.com" is a sentence you can check; the installer can also add explicitly permitted hosts. "This plugin respects your configuration" is not. The declaration turns the network side of a plugin into a list a human can read in seconds and a gateway can enforce on every request, and the two of us checking the same thing is the point.

Permissions derived by reading the code

At publish time, the platform reads the plugin's code and derives the host interfaces it calls. You see that derived set and the egress hosts before you install — not a category, a permission prompt with the detail behind it. An update whose access fits what you already accepted can arrive automatically; an update that asks for more stays on the old version and waits for your approval. Nothing from the new version runs until then.

Why derive host permissions instead of trusting only the author's manifest? Because a manifest is a claim and code is behaviour. The scanner records literal calls such as host.workspace.read, and the runtime exposes only the corresponding interfaces. Egress is explicit in the manifest and enforced at call time. The two mechanisms cover different ground; neither is a promise that the code is good.

The honest limit, because a derivation is a static artifact applied to dynamic code:

  • It's derived from the code, not from the author's intent. A plugin that fetches a URL and then calls whatever host the response names is asking for something a static read can't fully characterise. The gateway is the second line there — the declared-host check is enforcement at call time, not just a review step.
  • The sandbox is not a blank cheque. It is a per-call, network-checked isolate with no direct OS filesystem or process access, plus only the explicit host permissions shown at install. Calls have hard wall-clock limits — 30 seconds for a tool, 5 for a middleware hook — and the isolate is destroyed when time runs out. Anything that needs a long-running process you own is an SSH or tunnel job against your own machine, a different mechanism with different properties.
  • Reading code can't tell you the code is good. Permissions describe reach. A plugin with a tidy two-host permission set and a bad prompt still behaves badly, and no install screen will save you from that. It's why the derived set is worth showing, and why it isn't the whole story.

If you're building the same thing on your own agent runtime, the checklist is four questions, and you can ask all of them today. Can in-memory state outlive the call? Can an outbound connection go somewhere the plugin didn't declare? Can an update widen what the plugin reaches without a human seeing it? Can you produce the derived reach of a plugin without running it? You want no to the first three and yes to the last.

What this costs

Worth being blunt about it, since the trade is real. Fresh sandboxes per call mean plugins can't do the cheap trick of holding a cache in memory between invocations. No direct OS filesystem means no local model weights and no vendored binary. Serial calls mean a plugin that wants to fan out has to do it inside one call, or hand the fan-out to something else in the platform. Each of those is a legitimate thing to want for a plugin, which is why we describe the model as scoped rather than generous. What you get for it is that the install screen says what the code can reach, and the runtime means it.

If you want the plugin to have full control over the machine, that's a real architecture, and self-hosted software does it properly — with you as the operator, which is a job, not a checkbox. Both answers exist. Ours is the one that reads the code, shows you the reach, and runs the call in a box it throws away.


Not open source, and we don't pretend to be. Everything on top of the runtime is extensible on a public SDK — middleware, tools, channels, model and search providers, compaction, crews — and anyone can publish a plugin.

The implementation details and limits: Sandbox model and Permissions.

The comparison, including the section on where self-hosting is the better pick: agentparley.ai/openclaw-alternative. Plans and limits: agentparley.ai.

Top comments (0)