Permissions

Ghosty plugins run in a sandboxed environment with no default access to platform features. To use storage, make network requests, show notifications, or navigate the host application, a plugin must declare the required permissions in its plugin.yaml manifest.

How permissions work

1. Declaration -- the developer lists required permissions in plugin.yaml.
2. Install prompt -- when a user installs the plugin, Ghosty displays a consent dialog listing every requested permission with a plain-language explanation.
3. Runtime enforcement -- the GhostySDK checks permissions on every API call. If a plugin tries to call an API it has not been granted access to, the call throws a PermissionDeniedError.
4. Revocation -- users can revoke individual permissions at any time from the plugin settings screen. Your plugin should handle PermissionDeniedError gracefully and degrade functionality rather than crashing.

Storage permissions

Storage permissions control access to the plugin's private key-value store. Each plugin has an isolated storage namespace; plugins cannot read or write another plugin's data.

Storage limits

Notification permissions

Notification permissions control a plugin's ability to display system notifications and in-app toasts.

Network permissions

Network permissions control outbound HTTP requests and WebSocket connections.

Domain allowlist

When requesting network.fetch or network.websocket, you must also declare the specific domains your plugin will communicate with:

permissions:
  - network.fetch
 
allowed_domains:
  - api.openweathermap.org
  - api.example.com

The runtime blocks any fetch or WebSocket connection to a domain not in this list. Wildcard patterns are not supported.

Navigation permissions

Navigation permissions control the plugin's ability to interact with the Ghosty host application's navigation stack.

User context permissions

User context permissions control access to information about the currently logged-in Ghosty user.

Handling permission denial

When a user revokes a permission or the plugin attempts an unpermitted action, the SDK throws a PermissionDeniedError. Always wrap SDK calls in try/catch blocks and provide meaningful fallback behaviour:

import { ghosty, PermissionDeniedError } from "@ghosty/sdk";
 
async function loadSavedCity(): Promise<string> {
  try {
    const city = await ghosty.storage.get("selected_city");
    return city ?? "London";
  } catch (error) {
    if (error instanceof PermissionDeniedError) {
      // Storage permission was revoked -- fall back to default
      console.warn("Storage permission denied, using default city.");
      return "London";
    }
    throw error; // Re-throw unexpected errors
  }
}

Permission changes between versions

When you release a new version that requires additional permissions, Ghosty prompts the user to approve the new permissions before updating. If the user declines, they stay on the previous version.

To minimise friction:

• Add new permissions only when genuinely needed.
• Use the description field in your store listing update notes to explain why new permissions are required.
• Design your plugin so that new features behind new permissions are optional, not blocking.