Rust Oxide plugins: install and permissions

Oxide, distributed through uMod, is the long-standing plugin framework for Rust servers. You install it by extracting the Oxide.Rust release over your server's install directory, restart, and the server gains an oxide/ folder. Plugins are single .cs files dropped into oxide/plugins; Oxide compiles and loads them on the fly, writes their settings to oxide/config, and gates what players can use through a permission system driven by oxide.grant. The catch is the monthly Rust update, which breaks Oxide every time until a new build is out. This post covers installing it, running plugins properly, the permission model, and keeping the whole thing alive through a year of updates.

What Oxide actually does to your server#

Rust has no official plugin API. Oxide works by patching the game's managed assemblies in RustDedicated_Data/Managed so that the game calls into Oxide at hundreds of points - a player connecting, an entity taking damage, a resource being gathered, an item being crafted. Each of those points is a hook. A plugin is a C# class that implements the hooks it cares about and returns values that can change what happens next.

Three consequences follow, and they explain most of the trouble people have:

• Oxide is tied to the exact game build. When Facepunch ships an update, the assemblies change, the patched ones are overwritten by SteamCMD, and Oxide is gone until you reinstall a build made for the new version.
• Plugins are compiled on your server. Oxide ships a compiler process. A plugin that references a game method Facepunch renamed fails to compile, prints an error, and stays unloaded while the others carry on.
• Your server becomes modded. By default an Oxide server reports itself as modded, which moves it to the Modded tab in the browser. That is correct for anything that changes gameplay and is covered in gather rates and kits on a modded server.

Oxide is not the only option. Carbon is a newer framework that loads most Oxide plugins without patching the game files, and is worth reading about before you commit. The plugin ecosystem described below works on both.

Installing Oxide#

1. Stop the server cleanly with quit in the console, so the world is saved.
2. Update Rust first. Run SteamCMD with validate. Installing Oxide on an out-of-date server, then updating, overwrites Oxide straight away.
3. Download the matching Oxide.Rust build from the Rust page on umod.org. There are separate archives for Windows and Linux; take the one for the operating system the server runs on, not the one you are sitting at.
4. Extract it over the server root, so its RustDedicated_Data folder merges with the existing one and overwrites files when asked.
5. Start the server and watch the console. Oxide announces itself during startup and creates the oxide/ directory on first run.
6. Confirm with oxide.version in the console. If the command is unknown, Oxide did not load.

On a panel, step 4 is easiest with the file manager: upload the zip to the server root and unpack it in place. Some panel eggs have a framework switch on the Startup tab that downloads Oxide at every start; if yours does, use that instead and do not mix it with manual installs.

The oxide folder, file by file#

The distinction between config and data matters more than anything else in that table. Config is what you chose: rates, cooldowns, prices. Data is what players did: kit redemption times, clan membership, home locations, economy balances. Wiping data on wipe day resets player state; wiping config resets your settings. People delete the wrong one regularly.

Permissions are stored in oxide/data too, in Oxide's own data files. They survive map and blueprint wipes unless you delete them, which is nearly always what you want.

Installing and managing plugins#

Drop a .cs file into oxide/plugins and Oxide notices. By default the plugin watcher compiles and loads new files automatically, and reloads a plugin when its file changes, so updating a plugin is replacing the file. The console prints either a "Loaded plugin" line with the name and version or a compile error with a line number.

oxide.plugins                 list loaded plugins with versionsoxide.load Kits               load one plugin (file name without .cs)oxide.unload Kits             unload itoxide.reload Kits             unload and load again, rereading configoxide.reload *                reload every pluginoxide.version                 framework version

Each command also has a short form with o. in place of oxide. - o.reload Kits is the same as the long one.

A few habits keep this sane:

• Read the dependencies. Many plugins need a library plugin first. ImageLibrary for UI images and Economics for anything with prices are the common ones. The plugin page says so; the console error does not always.
• One plugin per job. Two teleport plugins, two chat formatters or two stack-size controllers will fight over the same hook, and the result depends on load order.
• Keep the old file. Before replacing a plugin, copy the working version somewhere outside oxide/plugins. A plugin update that breaks is fixed fastest by putting the old one back.
• Never leave test plugins in the folder. Every loaded plugin costs hook time on every event it subscribes to.

Configs and language files

On first load, most plugins write a default config to oxide/config/PluginName.json. Edit it, save it, and run oxide.reload PluginName - the change does not apply until the plugin reloads.

{  "Cooldown (seconds)": 600,  "Max uses per wipe": 3,  "Enabled for default group": true,  "Allowed items": ["rifle.ak", "ammo.rifle"]}

JSON is unforgiving. A trailing comma, a missing quote or a stray comment stops the plugin loading, and some plugins respond to an unreadable config by writing fresh defaults over your file. Validate a large edit before you reload, and keep a copy of every config you have spent time on. Item names in configs are Rust's shortnames (rifle.ak, stones, metal.fragments), not display names.

Language files in oxide/lang/<code>/ hold every message a plugin prints. You can rewrite them freely to match your server's tone or translate them; a player sees the language their client reports if a file for it exists, otherwise English.

Permissions: groups, grants and the admin group#

Oxide's permission system is separate from Rust's own owner and moderator levels. A plugin registers permission strings like kits.use or removertool.normal, and nothing in the plugin works for a player who has not been granted the right one, directly or through a group.

There are two default groups. Every player is in default. Players with owner rights are placed in admin. You can make more.

oxide.grant group default kits.useoxide.grant group admin removertool.adminoxide.grant user 76561198012345678 vanish.allowoxide.revoke group default kits.useoxide.group add vip "VIP" 10oxide.group parent vip defaultoxide.usergroup add 76561198012345678 vipoxide.usergroup remove 76561198012345678 vipoxide.show groupsoxide.show group vipoxide.show user 76561198012345678oxide.show perm kits.use

Use SteamID64s rather than names in anything you script or document. Names change and contain characters that break commands; IDs do not. Parenting is how you avoid granting the same twenty permissions three times: vip inherits default, moderator inherits vip, and each grant is made once at the lowest level that should have it.

Keep your permissions as a script

Permissions built up one command at a time over a year become something nobody can describe. The fix is to keep every grant in a plain text file - one command per line, grouped by group - and treat that file as the source of truth. When you add a plugin, add its grants to the file and run them. When a moderator asks why VIPs can use a command, the file answers.

The file pays for itself three ways. You can rebuild permissions from scratch in a minute after a mistake or a corrupted data file. You can move to Carbon by changing oxide. to c. and pasting. And you can review it, which is the only way to notice that default was given an admin permission eighteen months ago by someone testing a plugin.

Granting * to a group grants everything, and a wildcard like kits.* grants every permission a plugin registers. Both are convenient and both are how a moderator ends up with a plugin's admin powers by accident. Grant the admin group broadly if you must, everyone else explicitly. Subusers and least privilege makes the same argument for panel access.

Choosing plugins worth running#

uMod hosts the free catalogue and its review rules mean plugins there are readable source. Codefling and Lone.Design host many paid plugins. Because a plugin is source code compiled on your server, it can do anything the server can - read files, make web requests, grant permissions - so get plugins from the author's real page and read anything that seems too generous. Leaked copies of paid plugins are a well-known route to backdoored servers.

Paid plugins are not automatically better. Some are excellent and actively maintained; others are a free plugin's idea with a UI added. What a price usually buys you is support and updates after the monthly patch, so judge a paid plugin by how quickly its author shipped fixes after the last few updates, which their changelog shows. A plugin you depend on for your server's identity - a custom economy, a raid system - deserves an author who is still around.

Names and maintainers change over time; check the plugin's page for the current version and whether it still works on the latest Rust. A plugin with no update in a year has usually been superseded.

Keeping a modded server clean covers the general discipline of a short plugin list, and what to do when a mod update breaks is the recovery routine.

The monthly update and Oxide#

On the first Thursday of the month the Rust update overwrites the patched assemblies. Your server starts, runs vanilla, and every plugin is silently gone: no permissions enforced, no kits, no protection plugins, and players discovering this within minutes. The fix is procedural:

1. Stop the server and update Rust with validate.
2. Wait for uMod to publish the Oxide build for the new version. It is usually hours, not days.
3. Install it, start, and read the console for plugins that fail to compile.
4. Update or unload the failing plugins before you open the server.

If your server updates Rust automatically on start, turn that off on wipe day or the server will come up unprotected before Oxide is ready. The staging branch, installed separately, lets you test plugins against next month's build a week early. The monthly force wipe schedule puts this into a calendar.

Panel notes and performance#

oxide.plugins shows each plugin with a time figure beside it - the time spent in that plugin's hooks. When the server's frame rate drops, sort through that list first; one badly written plugin hooked into entity spawning or damage costs more than the rest combined. Server performance and entity count covers the rest of the diagnosis.

On RE:NODE, and on Pterodactyl panels generally, plugins are uploaded by you through the file manager or SFTP - there is no whitelist of allowed mods and no one-click plugin installer. The file manager edits JSON with syntax highlighting, which catches the missing comma before Oxide does, and per-server SFTP credentials mean a developer can be given file access without your panel password. SFTP and the file manager covers both.

Troubleshooting#

"Unknown command: oxide.version". Oxide is not loaded. Either it was never installed, it was overwritten by an update, or you installed the Windows build on Linux.

A plugin fails with a compile error after an update. It references game code that changed. Update the plugin; if no update exists yet, unload it and wait.

A plugin loads but does nothing for players. Permissions. Run oxide.show perm <permission> to see who has it, and grant it to default if everyone should.

Config changes are ignored. The plugin was not reloaded, or it rewrote the file because the JSON was invalid. Check the console for a config error, fix the file, reload.

Admins do not have admin permissions. They are not in the admin group. Owner rights alone do not grant Oxide permissions; add them with oxide.usergroup add.

Everything reset after a wipe. Someone deleted the whole oxide/data folder. Restore Oxide's own permission files from the pre-wipe backup and decide which plugin data you meant to keep.

FAQ#

Is uMod the same thing as Oxide?

Effectively, yes. Oxide is the framework; uMod is the project and website that distributes it and hosts the plugin catalogue. Rust servers install a build called Oxide.Rust.

Do players need to install anything to join an Oxide server?

No. Oxide runs entirely on the server. Plugins with custom images or UI send them to the client as part of normal play.

Can I use Oxide plugins on Carbon?

Most of them. Carbon is designed to load Oxide plugins unchanged, and the large majority work. A few that depend on Oxide internals need an update or a replacement.

Do permissions survive a wipe?

Yes, unless you delete Oxide's data files. They are stored in oxide/data, separate from the map, save and blueprint files a wipe removes.

Why does my server show as modded after installing Oxide?

Oxide reports the server as modded by default, because most servers running it change gameplay. The setting lives in oxide.config.json; only turn it off if your plugins genuinely leave gameplay vanilla.