Mods and the sandbox

A mod is a web application plus a mod.json manifest. The manifest declares what appears in the host and which capabilities the application requests. The app then connects through @aether/sdk/sandbox.

#Execution forms

• A native panel contributes host-rendered view data.
• An app panel contributes a sandboxed iframe the user opens in the dock.
• A background entry runs in a hidden sandbox without requiring an open panel.

The iframe receives a capability-gated bridge, not server objects or unrestricted browser access. Network egress is denied by default. net.fetch exists in the registry but is not grantable in the current host.

#Capabilities

Request only what the feature needs. Examples include documents.read, chat.card, dice.roll, scene.draw, scene.input.subscribe, events.subscribe, and scene.objects. Unknown or denied capabilities remain visible to the GM but cannot be granted.

The generated mod capability reference is built from the host registry. Consent labels and Marketplace permission descriptions use that same registry.

#Connect to the host

import { connectToHost } from "@aether/sdk/sandbox";

const client = await connectToHost();
const documents = await client.invoke("documents.read");

The host validates the requested operation and arguments, applies the member's world and document permissions, and returns projected data. A grant lets the mod ask; it does not bypass server authority.

Use Build a mod interface for the native and app panel workflow. mods/spell-cards is a headless maintained example with a chat command, semantic action, settings, projected document reads, and authoritative card rolls.