.aexpackages and the Goja backend API described here are implemented. An.aexis a zip archive with an Aether-specific file extension; install.aexfiles through the launcher rather than using a.zipfile. The CLI and SDK are maintained in separate repositories. Install the CLI withgo install github.com/Aether-Launcher/aether-cli@latestand add the SDK to an extension project withnpm install --save-dev @aethermc/sdk.Want to change Aether's appearance without writing an extension? Themes are CSS and image packages. See the Themes Guide.
An extension has two parts:
- Backend (
main.js) runs in a Goja JavaScript runtime. It has no DOM, and can call only the launcher APIs allowed by its manifest permissions. - Frontend (
ui/index.html) is shown in an iframe inside Aether. A local HTTP server serves the extension's UI files.
The runtime limits which launcher APIs an extension can use, but it is not an operating-system security boundary. Read the Security Guide before relying on it to protect sensitive data.
- Create a project directory and add a
manifest.json. - Write the backend entry point in
main.js. - Add the interface files under
ui/, starting withui/index.html. - From
main.js, useAether.ui.registerSidebarPage()to make the page available in Aether.
// main.js
Aether.ui.registerSidebarPage({
id: "my-custom-page",
label: "My Page",
url: "ui/index.html" // Relative to the extension folder
});An extension package can include documentation, an icon, and other assets alongside its required files. For example:
my-extension.aex
├── manifest.json
├── main.js
├── README.md
├── LICENSE
├── CHANGELOG.md
├── icon.png
├── ui/
│ ├── index.html
│ ├── style.css
│ └── script.js
└── assets/
Install an .aex package from the Extensions page or Extension Gallery. Although the package uses the zip format internally, the launcher expects the .aex extension. During development, you can place an extracted extension folder in Aether's extensions data directory. Aether uses a local .aether directory when one is present; otherwise, it uses the platform's configuration directory.
Each extension needs a manifest.json at its root. For example:
{
"id": "com.example.myextension",
"name": "My Extension",
"version": "1.0.0",
"author": "Your Name",
"description": "Adds a cool new feature to Aether.",
"main": "main.js",
"api": "1.0",
"pinToSidebar": false,
"permissions": [
"ui:sidebar",
"instances:list",
"mods:install"
]
}pinToSidebar is optional and defaults to false. Registered pages without an approved pin stay under Active Extensions. Set it to true to ask for permanent links in the main sidebar; the extension must also request ui:sidebar to register pages. Aether asks the user when the extension is installed or updated. Approval or denial is remembered for that version, and a later version can ask again. Declining the pin does not remove the extension's page from Active Extensions.
The registry may also store metadata such as compatibility ranges and project links:
{
"minApi": "1.0",
"maxApi": "2.0",
"homepage": "https://example.com/myextension",
"repository": "https://github.com/example/myextension",
"license": "MIT",
"keywords": ["mods", "fabric"]
}The registry can store these fields for discovery and future tooling. The launcher does not currently enforce the API ranges or use the project links when it loads an extension.
Extensions only receive the APIs they request in manifest.json. Ask for the permissions your extension needs, and avoid requesting unrelated access.
ui:sidebar: Register extension pages that render yourui/index.htmlin an iframe. If the manifest also setspinToSidebartotrue, Aether asks the user whether to pin those pages directly in the sidebar when the extension is installed or updated.ui:dialogs: Exposes the current dialog stub; a functional dialog API is planned.instances:list: List installed instances.mods:list: List mods in an instance.mods:install: Install a mod after launcher confirmation.mods:delete: Delete a mod after launcher confirmation.mods:toggle: Enable or disable a mod after launcher confirmation.modpacks:install: Install a.mrpackmodpack as a new instance after launcher confirmation.resourcepacks:install: Download a resource pack into an instance'sresourcepacksdirectory after launcher confirmation.shaderpacks:install: Download a shader pack into an instance'sshaderpacksdirectory after launcher confirmation.screenshots:read: List, open, and read screenshots for an instance.screenshots:write: Delete a screenshot after launcher confirmation.network:http: Make backend HTTP GET requests to allowed hosts.fs:download: Download files to the sharedlibrariesdirectory.launcher:modloader: Register a launch-time mod-loader callback.skin:export: Write base64 data below the sharedskinsdirectory.account:read: Read the safe active-account subset (signedIn,id,username,type). Tokens are never exposed.skin:manage: List owned Mojang skins (Aether.skins.listMine) and upload/apply skins (upload,applyUrl) after user confirmation.cape:manage: List owned Mojang capes and equip/hide the active cape after user confirmation.discord:presence: Update Discord Rich Presence viaAether.discord.setActivity/clearActivityand subscribe toAether.events.on('instance:state').servers:list: Readservers.datfrom instances and ping servers (Aether.servers.list/Aether.servers.ping).servers:manage: Create, list, delete, and read/write files insideservers/<id>/directories. These directories are shared across extensions; this permission is not scoped to servers created by the same extension. Deleting a server asks for user confirmation.servers:process: Start, stop, query, and send console input to supervised server processes (Aether.servers.start/stop/status/send), with log streaming viaserver:log. EULA acceptance requires explicit user confirmation (Aether.servers.acceptEula). Max 2 concurrent servers.saves:list: List singleplayer worlds of an instance (Aether.instances.listWorlds). Read-only world metadata (names, last played, game mode).instances:launch: Launch the game, optionally quick-connecting to a server or world (Aether.instances.launchToServer/launchToWorld). Granted at install time; launching is a visible user action so no per-click confirmation is shown.
The older instances:patch permission remains available for compatibility and grants the current instance and mod capabilities. New extensions should request the more specific permissions listed above.
Your extension UI runs in an <iframe>, so you can build it with React, Vue, Svelte, Solid, Lit, or plain HTML and CSS. Aether does not require a particular frontend framework.
For a more seamless experience, consider using colors and patterns that sit comfortably alongside Aether's dark interface.
The extensions-src/ directory contains sample extensions, including the Modrinth Browser and Fabric mod loader.
The registry can attach a trust label to an extension, and Aether displays that label in the interface. A label describes registry metadata; it is not a security guarantee or a substitute for reviewing the code:
- Official: The registry identifies the extension as maintained by the Aether team.
- Verified: The registry assigns this label. It should not be read as a promise that the current launcher performed a security audit.
- Community: The registry lists the extension as community-maintained. Review its permissions and source before installing.
- Local: Installed from a local
.aexfile. If its manifest ID matches a registry entry, Aether may display the registry's label instead.
The launcher does not currently enforce a maintainer review process or automated code analysis. Treat all extensions according to their source and requested permissions, regardless of badge.
The CLI is maintained in a separate repository. It currently supports four project commands: init, dev, validate, and build, plus help. You can run them as aether, aet, or aether-cli.
Install it with npm:
npm install -g @aethermc/cliOr install it with Go:
go install github.com/Aether-Launcher/aether-cli@latestThe CLI is a separate Go module and currently declares Go 1.26.2. If your toolchain does not download newer Go versions automatically, install Go 1.26.2 or newer before using the Go install command.
Create an extension project by providing its display name and ID:
aether init my-extension com.example.myextensionTo create a theme instead, add --theme:
aether init my-theme com.example.mytheme --themeRun aether dev from the project directory to deploy the extension to a local Aether installation and watch for file changes. Aether must be running.
Run aether validate to check an extension project. For a theme, use aether validate --theme. The CLI can detect a theme when it finds package.json and no manifest.json.
Run aether build for an extension or aether build --theme for a theme. The CLI validates the project and creates a zip-format .aex or .theme package. It excludes .git/, node_modules/, and existing archives.
For command options and the latest behavior, see the Aether CLI repository.