# Permissions

> Ask only for what your app uses, and say why in one sentence. The person reads it before the app opens.

An app lists what it needs in `app.json` › `permissions`, each with a reason written for a musician:

```json
"permissions": {
  "files": "Open the songs you choose and save the copies next to them.",
  "library": "Add the converted copies to your Library.",
  "network": {
    "why": "Download the separation model the first time you use it.",
    "hosts": ["github.com", "objects.githubusercontent.com"]
  }
}
```

| Code | Covers |
| --- | --- |
| `files` | `ox.Files` and `ox.Folder` controls, files next to the ones chosen, and `ox.files` on a page |
| `library` | Adding to the Library: returning `ox.sound`, `ox.midi` or `ox.file`, and `ox.library.add` in Python and on a page. It doesn't show the app what is already there |
| `library-read` | Seeing the Library on a page: `ox.library.list`, `ox.library.file` and `LibraryDialog`. Names and facts, never paths; a file only for a sound the person picks or the app added |
| `data` | `ox.data`, the app's own private folder, in Python and on a page |
| `gpu` | torch or onnxruntime running a model on the graphics chip (Metal on a Mac, CUDA on Linux). Optional: without it, or when the person says no, the same code runs on the CPU, so fall back rather than fail |
| `network` | Reaching the listed hosts, and only those |

The exact words the person sees for each code are in the [permissions reference](https://docs.0x1audio.com/reference/permissions.md).

`library-read` is new in Mixel 0.1.23, and needs `mixel` 0.3.5 or later.

## What the person sees

Before an app opens for the first time, Mixel shows what it would like to do, with your reason under each line. Nothing runs until they allow it, and they can change their mind later from the app's menu.

![The sheet Mixel shows before an app opens: Open files you choose, Add to your Library, each with the app's reason, and Allow](https://docs.0x1audio.com/images/permit-light.png)

## Declared is binding

Whatever `app.json` doesn't list is refused, without asking the person. There's no way to ask for more while the app runs. That keeps the sheet honest: what people allowed is everything the app can do.

`mixel check` reads your code and tells you when it uses something `app.json` doesn't ask for (`permission_undeclared`) or asks for something it doesn't use (`permission_unused`). `mixel check --fix` adds a missing code with a `TODO:` reason. Replace it with your own words, because `mixel check --strict`, and so publishing, won't pass a TODO.

## Writing a reason

- One sentence, 12 to 120 characters, that says what the person gets: "Save the mono copies to your Library."
- Name their things: songs, sounds, files, your Library. Leave out how it works inside.
- Be specific about network use. "Download the vocal model once (300 MB)." tells them what to expect.

## Network

`network` is the only permission that needs more than a reason. List every host the app reaches:

```json
"network": { "why": "Download the model the first time you use it.", "hosts": ["github.com"] }
```

The whole web (`*`), IP addresses and `localhost` are refused. A page's `fetch` reaches only these hosts.

**What permissions cover today.**
Mixel enforces permissions on the app's page and on everything the app asks Mixel to do: files from the pickers, the Library, its data folder, network from the page. The app's Python code isn't yet walled off by the operating system. Until it is, review checks that the code keeps to what it declared, and `mixel check` flags code that runs programs or opens sockets.