Plugin permissions

The five permissions, what a plugin sees without them, and why a WebAssembly plugin is a different proposition from a program.

What a plugin may do is declared in advance, in agentty-plugin.json, and shown to the user before they install it. A call made without its permission fails with error -32001.

The five permissions#

PermissionWhat the user is toldMethod
net.requestMake HTTP requests to the addresses you give itnet/fetch
prompt.injectStart agent sessions and send them promptsprompt/inject
terminal.writeType into terminals and press Enterterminal/send
session.readRead the conversation of AI sessions open in Agenttysession/get
workspace.readSee open workspaces, tabs, folders and agent statusworkspace/list, host/revealPath, pane/status
mcp.toolsAnswer AI agents in Agentty through the tools it offers (MCP)tools/call
terminal.proxyRoute new terminals through its proxy; requires API version 6terminal/setProxy

A plugin's own storage and its panel need no permission. storage/get, storage/set and storage/keys are its own folder (<data dir>/plugin-data/<id>/storage.json, created 0600), up to 64 keys and a megabyte. A WebAssembly plugin has no files of its own, so that is how it remembers anything.

Important

net.request together with session.read or workspace.read means the plugin can read your work and send it somewhere. A plugin that asks for both should say plainly, in its description, why it needs them — and the marketplace refuses one that does not.

Two kinds of plugin#

This is the distinction that matters most, and the Plugins page names it under About → Runs as.

wasmAgentty runs the module itself. It has no file, no socket, no environment variable and no process — it reaches only what the protocol gives it, however it is written.
node, python, executableA program running as your user, with the same file and network access as anything else you start. The permissions above still gate the protocol, but nothing gates the program.

So the permission list means something different in each case. For a WebAssembly plugin it is the whole of what the plugin can do. For a program it is the whole of what the plugin can do through Agentty — it could always open a file itself.

Only install a program plugin if you trust its author. The marketplace lists WebAssembly modules with public source and nothing else, for exactly this reason.

What a plugin sees without permissions#

Context is filtered by what the plugin declared. Without workspace.read, folder and title fields are removed; without session.read, the session id is removed. What remains are ids, kind, tool, status, running and the language — enough to know which pane is focused and whether it is busy, not where you work or what you are doing.

json
{
  "pane": { "id": 12, "kind": "claude", "tool": "claude", "status": "working", "running": true },
  "language": "en"
}

Where a prompt goes, and who chose#

The dialog is not a boundary, and it is worth being plain about that. prompt.inject lets a plugin open an agent session of its own and send it text, without asking. That is deliberate: an AgentOS is a plugin whose whole job is running steps through sessions it started, and it could not do that through a dialog.

A plugin may hand the choice to the user instead. target: "ask" opens Send to…: they see the text, pick the agent and the destination, and nothing happens until they press Send. Every other target — newTab, newWorkspace, active, pane, workspace — skips it. So a plugin acting on anything that came from outside should always use ask. A plugin a link reached is constrained: newTab and newWorkspace with agent Claude Code or Codex (or no agent given, which means Claude Code) open directly; every other case goes through Send to… unsent.

The two calls differ on Enter, and the difference is the whole of terminal.write:

  • injectPrompt never presses Enter in a terminal. It types the text and leaves it to the user.
  • sendToTerminal is the other thing, and it does press Enter — in a shell as well, where that runs the command.

agentty:// links can come from anywhere, including a web page. Once a link has reached a plugin, and for as long as that plugin keeps running:

  • prompt/inject with target newTab or newWorkspace and agent Claude Code or Codex (or no agent, which defaults to Claude Code) opens that new agent tab or workspace directly, with the text typed into the agent's prompt unsent — the user reads it and presses Enter. One such tab every few seconds: a page opening links in a loop gets one, and the rest wait in Send to…. Every other case — an open terminal with target active, pane, or workspace; split; own; a shell or terminal agent; or no target — goes through Send to…, unsent.
  • terminal/send types the text without pressing Enter (submit is forced to false), into a Claude Code or Codex terminal the plugin may type into — never a shell, where text left on the command line would run with whatever the user types next. Typing never runs anything: text is pasted with control characters removed, and newlines are bracketed-pasted or turned into spaces.
  • Both calls answer with submitted: false when Enter was left to the user.

The browser is still refused (-32001). host/openUrl is still the one thing a link-reached plugin can do outside Agentty, one address at a time. A click in the panel the link opened is not consent to run what the plugin types, and neither is waiting — a plugin can wait as easily as a user can click. Restarting the plugin is what clears it.

Agentty cannot tell a good address from a bad one, so that part is yours: treat whatever a link hands you as text from a stranger, and never open an address it gave you unexamined.

Important

If your plugin handles links, validate every parameter. The Cosmica plugin only opens .md files inside the Cosmica notes folder and refuses paths outside it.

What net.request is allowed#

net/fetch is the only way a plugin reaches the network, and Agentty bounds it:

MethodsGET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS over http or https
Headersat most 32, none of them Host, Content-Length, Transfer-Encoding, Connection, Upgrade or Expect, and none carrying a line break
Body1 MB
Response4 MB kept (truncated says when more arrived)
Timeout15 s by default, 60 s at most
In flightfour per plugin

Nothing of yours travels with the request — no cookie, no stored credential — only what the plugin puts in it. Each call is written to the plugin's log with the URL redacted.

Up to 3 redirects are followed, and each address they name goes through the same checks as the original: http or https, and not a link-local or metadata address — otherwise a server could answer 302 Location: http://169.254.169.254/… and walk past them. An Authorization or Cookie header is not carried to another host, and a redirected POST, PUT or PATCH becomes a GET without its body unless the answer was 307 or 308.

Rate limits and runaways#

Agentty protects itself from a plugin behaving badly, whether or not it meant to.

LimitWhat happens
Panel redrawsat most one every 50 ms
Notificationsat most one every 700 ms; the rest are answered normally and dropped. A message is cut at 300 characters
Opening a URLat most one every 700 ms — host/openUrl is throttled like a notification
Messagesmore than 240 a second stops the plugin as a runaway
UI tree2,000 elements, 12 levels deep, 20,000 characters per string. A choice's options and a list item's buttons each count as elements
Line length16 MB on stdout and stderr
WebAssembly64 MB module, 64 MB memory, 16 MB per message, 256 messages while handling one — send and log together

Tools for AI agents (MCP)#

A plugin can offer tools to AI agents running in Agentty — Claude Code and Codex — through an MCP server Agentty ships (agentty-plugins MCP server). Agents automatically get the server when at least one enabled plugin declares the mcp.tools permission and lists tools under contributes.tools.

A plugin must declare both the permission and the tools together: the permission without tools, or tools without the permission, is a manifest error. The permission requires API version 4.

A plugin that does not declare mcp.tools is not supported for MCP: agents never see it. Its page shows "MCP connection — Not supported".

A plugin that declares it has an "Allow MCP connection" switch on its Permissions tab, ON by default. When the user turns it OFF, agents can no longer list or call that plugin's tools.

At most 32 tools per plugin; tool name is 1–48 lower-case letters, digits or _, starting with a letter. Each call times out after 120 seconds. Arguments and text handed to the agent have size limits — see the protocol for details.

The plugin's answers go into the agent's context — treat them like any other tool output. Each call is logged (Logs tab) with the pane that called it.

Terminal proxy#

A plugin can ask Agentty to route the terminals and AI sessions you open through a proxy it runs on this computer (127.0.0.1), so it sees which hosts they reach and how much they send. You see the permission as Route new terminals through its proxy. Terminals already open are not changed; stopping the plugin ends it. Agentty builds the address from the port, so the plugin cannot point terminals anywhere else, and only one plugin holds the proxy at a time.

Writing a plugin that deserves it#

  • Ask only for the permissions you use. Every one is shown to the user, and one you do not use only costs you trust.
  • Never read or send credentials. If you read another app's config, take only the fields you need — the Cosmica plugin reads notes.path and a port.
  • Keep data in the plugin's own storage. Create files other apps read with care, and do not overwrite the user's files unasked.
  • Talk to 127.0.0.1 unless the user configured something else.
  • Check pane.status before typing. Do not interrupt working, permission or question.
  • Validate everything from outside — links, files, server responses.

Before you install someone else's#

  • Read the permissions on the card. A notes plugin asking for terminal.write should explain itself.
  • Check Runs as. A WebAssembly module is a much smaller thing to trust than a program.
  • Prefer plugins whose source you can read; the card's links usually point at the repository.
  • Logs after installing shows what the plugin actually does.
  • Disable takes effect at once; Uninstall removes it. The data folder stays until you delete it.