Skip to main content
Most of what an expansion does needs no permission: pages, sidebar buttons, editors, item types, settings tabs, themes, commands, menus, events, exporters, apps, AI tools. None of that reaches the user’s data or the outside world. Seven permissions cover what does, and each is declared in meta.json and approved by the user.
A permission not in this list is a manifest error, so a typo is caught at load rather than at the call. files, server and echo are new in 2.1; declaring one requires "sdkVersion": "^2.1.0".

What needs no permission

Pages, the sidebar, injections, editors, creators, item types, settings tabs, and reading and writing your own settings; themes, language, icons; notifications; dialogs other than the file and item pickers; commands, keybindings, CLI commands, menus, toolbars, the status bar, panels, routes, widgets and apps; events and interceptors; AI tools; scripting targets; your own storage and private data folder; Minecraft data, text helpers and YAML; background scripts; services; undo; team presence. Some of these touch exports, imports or the server, but only see what they are handed:
  • Exporters and importers run only when the user picks them, and see only what that export or import hands them.
  • A module’s own export and validation functions see only items that use that module.
  • Logic-editor catalog entries, Coder formats and linters are data and per-file checks.
  • Server status, reload commands, sync hooks, sync-script directives and server types do not send anything themselves.
  • SFTP hooks receive the project id, the push message and the file list, never file contents.
  • Echo context and AI tools add to what Echo and connected assistants see and can do. A tool that is not readOnly asks the user before it runs. Asking Echo yourself is what needs echo.
  • Scripting targets only see the script bundle the export hands them.

How approval works

1

Needs approval

An expansion that declares permissions loads as Needs approval and does not run.
2

Review permissions

The user presses Review permissions on the Expansions page and sees the plain-language lines above.
3

Approved

On approval the expansion starts. The grant is remembered.
An update that adds a permission asks again, listing only the new ones. The user can take approval back at any time with Revoke permissions, which stops the expansion and returns it to Needs approval. Since 2.1, the app checks the grant again for what it does on an expansion’s behalf (project file access, file dialogs, opening links, downloads), not only when your code makes the call.

Being refused

A call without its permission throws SdkPermissionError (async calls reject with it) and logs:
fetch and WebSocket without network reject with a message naming your expansion. Nothing is half-done; the call simply does not happen.

Asking for less

Declare only what you use. Every permission is a line the user reads before saying yes, and an expansion that asks for nothing starts immediately. If a feature needs a permission, consider putting the feature behind a button rather than making the whole expansion wait on approval. A few patterns that avoid a permission altogether:
  • Keep your own data in sdk.storage rather than in the project.
  • To change what a plugin config contains, prefer a module export, which needs nothing, over an export transform, which sees every item and needs project:read.

What the environment gives you anyway

Inside your code you have standard JavaScript (Promise, Map, JSON, Intl, URL, TextEncoder, crypto, Blob, AbortController, structuredClone, Image, Audio, …), console, and timers that are cleaned up when your expansion unloads. You do not have window, document, require, process, localStorage or the app’s internals. fetch and WebSocket exist only with network; sockets are closed when your expansion unloads.
This is a controlled environment rather than a hard sandbox: it keeps well-behaved expansions on the SDK and makes going around it a deliberate act, and NMCrate review is the gate for the rest. Do not treat it as a security boundary when deciding what to ship.