Permissions

Stina uses a permission system to control what extensions can access. Permissions are declared in your extension’s manifest.json under the permissions array. Users see the list of requested permissions before installing an extension, so only request what your extension actually needs.

{
  "permissions": ["tools.register", "storage.collections", "network:*"]
}

Permissions gate API access at runtime. If you don’t declare a permission, the corresponding property on context will be undefined.

Network Access

Control outbound network requests via the Network API.

Permission	Description
network:*	Full network access to any host
network:localhost	Only localhost connections
network:localhost:8080	Only localhost on a specific port
network:example.com	Only a specific domain

Use the most restrictive permission possible. For example, an extension that connects to OpenAI should declare network:api.openai.com rather than network:*. If users might configure a custom endpoint (like a remote Ollama instance), network:* is acceptable.

Registration Permissions

These permissions control which contribution types your extension can register at runtime. Each one unlocks a corresponding property on the ExtensionContext passed to your activate function.

Permission	API Access	Description
provider.register	context.providers	Register AI model providers
tools.register	context.tools	Register tools for AI use
actions.register	context.actions	Register UI action handlers
settings.register	context.settings	Register and access user settings
commands.register	—	Register slash commands
panels.register	—	Register right-side panel views
scheduler.register	context.scheduler	Register scheduled jobs
background.workers	context.backgroundWorkers	Run background tasks

Data Access

Permissions for persisting data and managing secrets.

Permission	API Access	Description
storage.collections	context.storage	Access document collections for persisting extension data
secrets.manage	context.secrets	Access encrypted secret storage (API keys, tokens, etc.)

User Data

Permissions for reading information about the user and their conversations.

Permission	API Access	Description
user.profile.read	context.user	Read user profile (name, language, timezone)
user.location.read	—	Read user location
chat.history.read	—	Read past chat conversations
chat.current.read	—	Read current conversation context

Runtime Features

Permissions for interacting with the runtime environment.

Permission	API Access	Description
events.emit	context.events	Emit events (used for UI refresh triggers)
chat.message.write	context.chat	Append instructions or messages to the conversation

System Access

Permissions for interacting with the operating system.

Permission	Description
files.read	Read files from the filesystem
files.write	Write files to the filesystem
clipboard.read	Read from the clipboard
clipboard.write	Write to the clipboard

Common Permission Combinations

These examples show typical permission sets for different kinds of extensions.

Simple Tool

["tools.register"]

The minimum for a tool that doesn’t need storage or network access.

Tool with Persistent Storage

["tools.register", "storage.collections", "actions.register"]

For tools that need to save and retrieve data. The actions.register permission is included so the extension can register UI actions (e.g. opening a detail view).

AI Provider

["network:*", "provider.register"]

Connects to an external AI service and registers as a model provider.

Full-Featured Extension

[
  "tools.register",
  "actions.register",
  "storage.collections",
  "secrets.manage",
  "settings.register",
  "scheduler.register",
  "background.workers",
  "events.emit",
  "chat.message.write",
  "network:*",
  "user.profile.read"
]

An extension like the Mail Reader that needs network access, persistent storage, encrypted secrets, scheduled background jobs, and the ability to inject messages into conversations.

Best Practices

• Principle of least privilege — Only request permissions your extension actually needs. Fewer permissions means users are more likely to trust and install your extension.
• Use specific network permissions — network:api.openai.com is better than network:* when your extension only communicates with a known host.
• Document your permissions — Users see the permission list before installing. Consider explaining why each permission is needed in your extension’s README.
• Permissions gate API access — If you don’t declare a permission, the corresponding context property will be undefined. Use optional chaining (?.) when calling APIs to handle this gracefully.