Installing plugins

Infrarust loads plugins from the directory pointed to by plugins_dir (default: ./plugins). When the binary is built with the wasm feature, the WASM loader loads every .wasm file directly in that directory. It does not look into subdirectories. Built-in plugins compile into the binary and register themselves at startup, with no files to copy.

The wasm feature is on by default, so a stock release build loads .wasm files. Building with --no-default-features removes it; add --features wasm back to keep WASM plugin support.

WASM plugins

A WASM plugin is a single .wasm file that implements the infrarust:plugin component model interface. To install one, copy the file into the plugins directory:

plugins/
  my-filter.wasm
  analytics.wasm

The loader will find both files on the next startup. Put every .wasm directly in the plugins directory: subdirectories are not scanned. They are where plugins keep their data (plugins/<id>/), and a plugin can write to its own data directory, so a component found there is never loaded. A backup copy left in a subdirectory is ignored.

TIP

The compiled plugins are cached in [wasm] cache_dir, ./cache/wasm by default, next to plugins/ and never inside it. The cache speeds up later startups by skipping compilation, is keyed on the plugin's content and the wasmtime version, and can be deleted at any time. See The AOT cache.

Configuring a plugin in infrarust.toml

Without any configuration entry, a discovered WASM plugin runs with the baseline capability set. To grant extra capabilities or to set other options, add a [plugins.<id>] table to infrarust.toml, where <id> matches the plugin's declared identifier:

[plugins.my-filter]
permissions = ["server-manage", "ban"]
enabled = true

The fields are:

Field	Type	Default	Description
path	string	none	Accepted for compatibility. WASM plugins are always loaded from plugins_dir, and native plugins are compiled in.
permissions	string array	[]	Extra capabilities to grant beyond the baseline. Values are kebab-case strings.
deny	string array	[]	Capabilities to remove, applied after the baseline and permissions. Also applies to built-in plugins.
strict_capabilities	bool	false	WASM plugins: refuse to load the plugin when it imports a host function whose capability it lacks.
wasm	table	none	Per-plugin overrides of the [wasm] sandbox limits, plus the network and mounts settings.
enabled	bool	true	Set to false to skip the plugin at startup.

A [plugins.<id>] table is optional. You only need one to grant or deny capabilities, disable the plugin, or change its sandbox settings. See [plugins.<id>] for every key.

Capabilities

WASM plugins start with a baseline set of capabilities and can request more via permissions. Native (built-in) plugins are trusted and receive every capability except the ones listed in their deny.

The baseline every WASM plugin receives:

• event-bus: subscribe to proxy events
• player-read: read the player registry
• player-write: send messages, titles, and kicks
• command: register in-game commands
• scheduler: run periodic tasks
• config-read: read the proxy configuration, except the other plugins' [plugins.<id>] blocks

Additional capabilities that require an explicit grant:

Capability	Description
server-manage	Start, stop, and query backend servers
ban	Access the ban service
raw-packet	Emit raw packets and receive RawPacketEvent
chat-intercept	Read, deny and rewrite players' chat messages and commands (WASM chat-message and command-execute events)
plugin-messaging	Register plugin channels, send plugin messages and receive plugin-message events
codec-filter	Register codec-level packet filters
limbo	Provide limbo handlers (hold players in a void world)
config-write	Rewrite the global infrarust.toml
permission-provider	Answer permission questions for every player when [permissions] provider names the plugin
ban-provider	Provide the proxy's bans when [ban] provider names the plugin
filesystem-extended	See the host folders listed in [[plugins.<id>.wasm.mounts]]
network	Reach the destinations listed in [plugins.<id>.wasm.network] allow

Two more capability strings exist in the model. transport-filter is the one value that config parsing refuses outright: it is native-only and listing it in permissions puts it on the rejected list. virtual-backend parses fine but its proxy-side bridge is not yet implemented, so granting it does nothing today. Treat it as planned.

WARNING

Unknown capability strings and transport-filter are skipped rather than granted. Infrarust logs a warning to the tracing output for each one, so check the startup log if a plugin behaves like it lacks a permission you listed.

Built-in plugins

Built-in plugins are compiled into the binary and activated by Cargo feature flags. There are no files to install.

Plugin	Feature flag	Activated by
Auth	plugin-auth	build flag, on by default
Server wake	plugin-server-wake	build flag, on by default
Admin API and Web UI	always compiled	[web] section present in infrarust.toml

The default-plugins feature pulls in both plugin-auth and plugin-server-wake, so a stock build has both. To build without them, disable the default features and pick only what you want:

cargo build --release --no-default-features --features "plugin-server-wake"

The Auth plugin's limbo handler and the Server wake plugin's hold logic are only active when those features are compiled in. Dropping plugin-auth from the build also removes the /login and /register commands.

Checking loaded plugins

Admins can run /ir plugins in chat to list every plugin the proxy loaded at startup, along with its version and description. For plugin-specific commands, /ir plugin <id> shows what commands that plugin registered.

The subcommands are gated by the permission nodes infrarust.command.plugins and infrarust.command.plugin, which default to admins and cannot be opened with player_commands. A plugin permission provider may still grant them. A player without the node gets [Infrarust] You don't have permission.

Data directories

Each plugin gets a data directory at <plugins_dir>/<plugin_id>/. For a WASM plugin this directory is the sandbox root: it is preopened as /, the plugin can read and write there freely, and reaching any other path requires the filesystem-extended capability. Native plugins are trusted and not sandboxed, so they use the same path by convention but can touch the wider filesystem.

Built-in plugins follow the same convention, keyed on the plugin id. The auth plugin (id auth) stores its accounts and config.toml under plugins/auth/, and the server wake plugin (id server_wake) reads its config.toml from plugins/server_wake/.

Changing plugins_dir

The default directory is ./plugins (relative to the working directory). To use a different path, set plugins_dir in infrarust.toml:

plugins_dir = "/opt/infrarust/plugins"

If the directory does not exist, WASM discovery returns an empty list and startup continues without it. A directory that exists but cannot be read (for example a permission error) is a hard failure: discovery returns an error and the proxy refuses to start, so fix the permissions or remove the bad path.