# Plugin permissions

What a plugin declares it does, how to read and grant those permissions, and why they are not a sandbox.

A plugin declares what it does, and Loam shows that list before you turn the plugin on. Use this page to read the list, decide whether to enable a plugin from your vault, and understand what the list does not protect.

## What the permissions mean

Loam sorts a plugin’s permissions from riskiest to least risky.

| Permission | Shown as | Risk |
| --- | --- | --- |
| `vault.read` | Read your notes | low |
| `vault.write` | Change your notes | medium |
| `disk.read` | Read files outside this vault | medium |
| `local-service` | Talk to programs running on your Mac, such as a local socket or port | medium |
| `network` | Talk to servers on the internet | high |
| `shell` | Run programs on your Mac | high |
| `audio` | Record or play sound | medium |
| `clipboard` | Read and change the clipboard | medium |
| `ui` | Add views, panels and commands to the window | low |

A permission that Loam does not know, for example from a newer version, shows as “Unknown permission” and counts as high risk.

## Read a plugin’s permissions

1. Open Settings, then Plugins.
2. Open the plugin’s page. Its permissions are listed with their labels. The high-risk ones are orange.
3. For a plugin in your vault, the same list is in the `permissions` field of its `plugin.json`, in `.loam/plugins/<id>/`.
4. Read the plugin’s README for what it does with those permissions.

## Enable or refuse a plugin

Turning on a plugin from your vault opens a sheet. It lists the permissions with their descriptions, and it highlights the high-risk ones. Nothing is saved until you choose Enable.

1. Read the list in the sheet.
2. Choose **Enable** to turn the plugin on, or **Cancel** to leave it off.
3. To refuse a plugin you already installed, leave it off. To stop one, disable it or remove it.

Installing never enables a plugin. When you install from a Git URL in Settings > Plugins, the app then asks whether to enable it now. `loam plugin install <url>` only installs it. From the command line, enable, disable or remove a plugin with:

```bash
loam plugin enable <id>
loam plugin disable <id>
loam plugin remove <id>
```

`remove` moves the plugin to `.trash/plugins/` and turns it off.

## What the list does not do

Permissions are declared and shown, not enforced. A plugin runs inside the app’s process, with the same access as the app. It can read and write any file the app can, open network connections and start programs, whatever it declares. A plugin that lies about its permissions is malicious, and the list does not stop it.

- Plugins from your vault run with the same access as the app. Only enable plugins you trust.
- Holding Option at launch opens the vault in safe mode. Safe mode never loads a plugin from the vault.

## Declare permissions in a plugin

A plugin declares its permissions in `plugin.json`. Declare everything its own code does, including what it does through the services it calls. For example, a plugin that moves notes through the files service declares `vault.write`.

```json
{ "id": "hello", "name": "Hello", "version": "0.1.0", "library": "HelloPlugin", "permissions": ["vault.read"] }
```