Vee documentation

Trust model

Vee runs plugins as ordinary executables with your full user privileges. There is no sandbox — a plugin can do anything you can do. Rather than pretend to isolate plugins, Vee makes their intentions transparent: plugins declare what they touch, and Vee surfaces that to you in plain language before you install and while you manage them.

This is advisory, never enforced. The declarations do not restrict what a plugin can actually do. They are a way for authors to be honest and for you to make an informed choice.

Why transparency, not a sandbox

The whole point of a menu-bar script runner is to run arbitrary scripts — hit an API, read a file, shell out to a CLI tool. A real sandbox tight enough to contain that would break the plugins people want to run, which is exactly why apps in this category are distributed outside the Mac App Store (the App Store sandbox is incompatible with arbitrary plugin execution).

So Vee is honest about the trade-off:

Plugins run un-sandboxed by design, with your privileges.
Vee cannot and does not verify that a plugin only does what it declares.
What Vee can do is read the declarations, summarize them in human terms, and show a warning when something looks broad or unusual.

Treat plugins like any other script you download and run. Read the source of anything you do not trust.

Declaring capabilities

Authors add <vee.*> tags to the plugin source (anywhere; they are scanned regardless of comment syntax). The available declarations:

Tag	Meaning
`<vee.capabilities>`	Comma-separated capability names: `network`, `filesystem`, `secrets`, `exec`, `clipboard`, `notifications`.
`<vee.network>`	Comma-separated network domains the plugin connects to (e.g. `api.github.com`). Wildcards like `*.example.com` are allowed but flagged.
`<vee.filesystem.read>`	Paths the plugin reads.
`<vee.filesystem.write>`	Paths the plugin writes.
`<vee.secrets>`	Names of secrets/tokens the plugin uses (usually matching an `<xbar.var>` secret).
`<vee.exec>`	External binaries the plugin runs (e.g. `git`, `curl`).

Declaring a detail tag implies its capability — for example, listing <vee.network> domains implies the network capability, so you rarely need <vee.capabilities> on its own.

Example declaration

python

#!/usr/bin/env python3
# <xbar.title>GitHub Notifications</xbar.title>
#
# <vee.network>api.github.com</vee.network>
# <vee.secrets>GITHUB_TOKEN</vee.secrets>
# <vee.exec>git</vee.exec>
# <vee.filesystem.read>~/.config/gh</vee.filesystem.read>

Vee reads this as: connects to api.github.com, uses the GITHUB_TOKEN secret, runs git, and reads ~/.config/gh.

The install trust summary

When you install a plugin from Discover (the built-in catalog browser), Vee shows a plain-language trust summary before installing, translating the declarations into readable statements such as:

"Connects to the internet → api.github.com"
"Uses a secret → GITHUB_TOKEN"
"Runs external tools → git"
"Reads files → ~/.config/gh"

Installation goes through this trust gate, so you always see the footprint before a catalog plugin lands in your folder.

Trust levels, badges, and warnings

Vee classifies each plugin's declaration into a trust level:

Declared — the plugin fully declares its footprint.
Partial — it declares a capability but leaves out detail (for example, it says it uses the network but lists no domains).
Undeclared — it declares nothing, so its footprint is unknown.

For each declared capability, Vee shows a trust badge with a severity heuristic:

Network — low if specific domains are listed; medium if a wildcard domain is used; high if network is declared with no domains.
Filesystem — low for read-only or no writes; medium for scoped writes; high for broad writes (writing to ~, ~/, /, or *).
Secrets and exec — medium (they involve credentials or running other programs).
Clipboard and notifications — low.

Vee also raises warnings for the risky cases — a wildcard network domain, a broad filesystem write, or network declared without any domains. These badges and warnings appear in the Plugin Manager so you can review a plugin's footprint at any time, not just at install.

What this does and does not guarantee

It does give you a clear, honest picture of what an author says their plugin does.
It does flag broad or vague declarations so nothing hides in "trust me."
It does not stop a plugin from doing something it did not declare. Nothing here is enforced.

If a plugin is undeclared or you are unsure, open its source (Reveal in Finder from the Plugin Manager) and read it before enabling it.