Plugins

Give the agent extra tools by running plugins for your projects, sideloaded by an administrator or enabled in your organization's Vediram Cloud policy

A plugin gives the agent extra tools, for example to look things up in a business application your team uses. Each plugin is a small program (an MCP server) that Levee runs on the computer, outside the sandbox, for the project. Plugins are off by default. An administrator turns them on in policy, then adds plugins in one of two ways: by installing them on the computer (sideloading), or by enabling them in the organization's Vediram Cloud policy.

What does the agent see?

Each plugin appears to the agent as a tool server named after the plugin's short name (its slug). The agent calls its tools like any other tool. It never sees the plugin's settings or secrets.

The agent finds plugins through the configuration Levee writes into C:\levee-config. Claude Code reads it. Codex CLI does not, so a Codex agent does not get plugin tools.

Turning plugins on

Set proxies.mcp.enabled to true in policy:

{
  "proxies": {
    "mcp": { "enabled": true }
  }
}

• Only the JSON value true turns plugins on. A missing section, false, or any other value (including the string "true") leaves them off.
• The setting is read when a project starts. Start or restart the project after changing it.
• When plugins are on, every ready plugin is offered to every project on the computer. Plugins added, updated or removed later reach the running project without a restart.

Where do plugins come from?

If a sideloaded plugin and a cloud plugin have the same plugin ID or the same slug, the sideloaded plugin wins. If several versions of the same sideloaded plugin are installed, the highest version is used.

For your IT team: sideloading a plugin

The Levee installer does not include the plugin scripts. Ask Vediram support for Import-McpPlugin.ps1 and Remove-McpPlugin.ps1 with the plugin bundle, put them in a scripts folder, and run them from its parent folder in an elevated PowerShell 7 prompt:

pwsh scripts/Import-McpPlugin.ps1 -PluginId ch.example.mcp -Slug example -Version 1.4.0 `
  -Bundle .\example.zip -Descriptor .\descriptor.json -ValuesFile .\values.json

What happens:

• The bundle and descriptor are copied to %ProgramData%\Vediram\Levee\plugins\sideload\<pluginId>\<version>\. The folder is readable only by SYSTEM and Administrators.
• The values file is encrypted for this computer (Windows DPAPI) and never copied in clear. Delete your copy afterwards if it held secrets.
• Levee notices the import within a few seconds, checks the bundle against the SHA-256 hash recorded at import, and unpacks it. The plugin becomes ready once its runtime is installed and every required value is present. A plugin that is not ready is left out, never half-started.

To remove a sideloaded plugin, or one version of it:

pwsh scripts/Remove-McpPlugin.ps1 -PluginId ch.example.mcp
pwsh scripts/Remove-McpPlugin.ps1 -PluginId ch.example.mcp -Version 1.4.0

The plugin leaves running projects within a few seconds and loses access to its files.

Sideloaded plugins do not appear on the Plugins page. Their values come only from the values file.

Cloud plugins

Plugins your organization enables in Vediram Cloud arrive with the cloud policy (spec.plugins). Levee keeps the last list it applied in %ProgramData%\Vediram\Levee\plugins.json.

How Levee handles the list:

• No spec.plugins in the cloud policy: nothing changes on the computer.
• An empty list ([]), null, or any value that is not a list: every cloud plugin is removed.
• An entry that repeats a key in its tenant settings is ignored on its own; the rest of the list still applies.

How is a plugin downloaded and checked?

Levee downloads each listed plugin from Vediram Cloud using the computer's own Vediram identity, then checks it before using it:

• The download may be at most 100 MiB and must finish within 30 minutes.
• Its size and SHA-256 hash must match the list. Otherwise it is not used.
• Levee reads the plugin's definition from the downloaded package itself.
• A plugin whose type Levee does not support, or whose version is withdrawn (yanked), is not downloaded.
• A plugin that needs a newer Levee version shows as needs Levee update.
• While a new version downloads, the previous ready version stays in use.

What status can a cloud plugin have?

Organization values and user values

A plugin can need settings, such as an account ID, a region, or an access token. Some are set once for the whole organization; others only the user can provide.

• Organization (tenant) values come with the cloud policy. Secret ones are downloaded separately with the computer's identity and stored encrypted. If Vediram Cloud reports that a plugin's secrets no longer exist, the plugin becomes unavailable and stays so until they exist again, even across a restart.
• User values are entered by the user on the Plugins page in the Levee app settings. See Plugins in the user guide.

How user values are kept:

• Levee checks every value against the plugin's definition before storing any of them. If one is invalid, none is saved. A value that names a website must match the pattern the plugin declares.
• Values are stored encrypted on the computer, per plugin. They belong to the first user who saves them: another standard user on the same computer cannot change them. An administrator running the Levee app elevated can overwrite them. Clearing every value releases them.
• The page shows whether a value is set only to that user or to an elevated administrator. Stored values are never shown again.
• Saved values reach the running project automatically.

What can a plugin's server reach?

• On the web: only the websites its definition declares, on HTTPS port 443. Its traffic goes through Levee's web channel. A website taken from a user or organization value must match the pattern the definition declares; a value that does not match is dropped, so the plugin simply cannot reach it.
• On the computer: each plugin's server runs isolated from the user's files and from other plugins, and can read only its own files and its runtime. That access ends when the plugin is removed from a running project, and when the project stops.

Runtimes (Node.js and Python)

Many plugins need Node.js or Python. Levee downloads the runtime the first time a plugin needs it, from the Vediram tool catalog at runtimeProvisioning.mcpRuntimeCatalogUrl (default https://downloads.vediram.com/releases/levee-tools/stable/catalog.json). It checks the runtime's size and SHA-256 hash against the catalog, then installs it under %ProgramData%\Vediram\Levee\runtimes\. Until the runtime is installed, the plugin is not ready. A computer that cannot reach the download site cannot start such a plugin.

What happens when a plugin is removed?

The plugin leaves running projects right away, without a restart:

• Cloud: when the new cloud policy removes a plugin or withdraws its version, Levee applies it as soon as the policy arrives, even while another plugin is downloading. The plugin shows as revoked.
• Sideloaded: within a few seconds of running Remove-McpPlugin.ps1.

Levee then deletes downloaded cloud plugin versions that nothing uses any more. A cloud plugin that is no longer listed loses its folder, including its stored values.

When do changes reach the computer?

• The plugin list arrives with the cloud policy: when the Levee app starts, when it reconnects to the Levee service, every 5 minutes, and when the user clicks Sync now.
• Levee then downloads what is needed: at service start, whenever a new list arrives, and every 30 minutes. That 30-minute check is how changed organization secrets reach the computer.
• While a plugin is downloading or unavailable, Levee retries sooner, waiting from 1 minute up to 30 minutes between attempts.

Where is everything stored?

All under %ProgramData%\Vediram\Levee\:

The plugins\ and runtimes\ folders are readable only by SYSTEM and Administrators.

Related

• How Policy Works
• Web Access
• Plugins in the user guide