BrowseManifest and permissions
Define your plugin’s identity, capabilities and the websites it may access.
Developer preview · macOS · Python SDK 1.1The manifest
id = "dev.yourname.reading"
name = "Reading"
version = "1.0.0"
description = "Save pages to a reading list."
author = "Your Name"
homepage = "https://example.com"
main = "main.py"
api = 1
icon = "icons/bookmark.png"
permissions = ["commands", "tabs", "sidebar"]browse.toml belongs at the root of the extension folder. Keep id stable: use a lowercase reverse-DNS identifier. The name can contain up to 60 characters. Versions use a numeric major.minor or major.minor.patch form, optionally followed by a -suffix. main defaults to main.py. homepage, icon and api are optional. The icon path must point to an image you include in the package; omit it if you have no icon.
Other Python files in the extension folder are importable. A lib folder can contain vendored pure-Python modules. Do not depend on globally installed packages, native executables or access to the person’s filesystem.
Ask for what you use
| Permission | Allows |
|---|---|
| tabs | Read and manage tabs, including their addresses and titles; receive tab events. |
| spaces | List, create and select spaces. |
| containers | List and create containers. |
| history | Search browsing history. |
| commands | Add commands to the command bar and customisation palette. |
| sidebar | Add native panels and compact widgets. |
| notifications | Show messages in the Browse window. |
| requests:<pattern> | Inspect, block or redirect matching navigations and register blocking rules. Redirect targets also need permission. |
| pages:<pattern> | Read or change matching pages; register page styles and element-hiding rules. |
| network:<host> | Make HTTP requests to the named host through browse.net. |
Storage and schedules do not need a permission. Adding a command does not grant access to tabs. Reading a page does not grant access to the network API. Declare every capability your plugin uses.
Browse presents permissions at installation and enforces them in the app. An update that adds permissions stays off until the person approves them. Removing a permission removes that access. Missing permissions raise browse.PermissionDenied.
Match websites precisely
| Pattern | Meaning |
|---|---|
| example.com | That host only. |
| *.example.com | The base host and all of its subdomains. |
| *://news.ycombinator.com/item* | HTTP or HTTPS, that host, and a matching path. |
| * or <all_urls> | Every website. Prefer a narrower scope. |
| network:api.example.com | A hostname, without a scheme or path. |
A URL pattern uses http, https or * as its scheme, a host pattern and a path glob. The event’s match filter and the manifest permission must both match the URL. Broad requests and pages permissions are highlighted during installation.
Working within permissions
In Browse on macOS, each extension runs in its own sandboxed Python process. It can read its package and runtime libraries, but cannot write arbitrary files, open its own network connections or start other programs. Use browse.storage for persistent data and browse.net for HTTP requests. The developer harness does not provide this OS sandbox.