A Home Assistant add-on for running the RustPlusPlus Discord bot, which connects to Rust game servers via the Rust+ Companion App.
In the Power Trip update, Facepunch stopped sending vending machine and event map markers (cargo, helis, travelling vendor) to Rust+. This is a change on Facepunch's side that affects every Rust+ app and bot — it is not a bug in this add-on, and there is no version you can downgrade to that brings it back.
No longer working: Cargo Ship / Patrol Helicopter / Chinook (CH47) / Oil Rig crate / Traveling Vendor / Deep Sea vendor notifications, the matching in-game and Discord commands, all vending machine features (
/market, market subscriptions, the WebUI Shops Browser, Insta-Profit trades, shop pins on the live map) and event history/predictions in statistics.Still working: teammate tracking and the live map, team chat bridge, Smart Switches and groups, Smart Alarms, Storage Monitors and TC upkeep, cameras and drones, server info and time, BattleMetrics player tracking, and Discord presence.
Details, what is being done about it, and the possible workarounds: Announcement #48
RustPlusPlus is a powerful Discord bot that provides Quality-of-Life features for Rust players by integrating with the Rust+ Companion App.
- 🚁 Event Notifications: Get notified about Patrol Helicopter, Cargo Ship, Chinook 47, and Oil Rig events
- 🔌 Smart Device Control: Control Smart Switches and Smart Switch Groups via Discord, and in-game chat
- 🚨 Smart Alarms: Set up alarms that notify you when triggered
- 📦 Storage Monitoring: Monitor Tool Cupboard upkeep and container contents
- 💬 Team Communication: Bridge Discord and in-game team chat
- 👥 Player Tracking: Track other teams using BattleMetrics integration (requires a BattleMetrics API key)
- 🎮 Discord Bot Presence: Bot status shows the connected server name and online teammate count
- 🛠️ QoL Commands: Extensive list of helpful commands for Discord and in-game use
- 🗺️ WebUI: Live map (teammate pins, events, shops with hover cards), Shops Browser and Insta-Profit trade finder with item icons, team statistics with an activity heatmap and player forecast, map replay
- 🔐 Secured WebUI: Password/token login on direct access
- Navigate to Settings → Add-ons → Add-on Store in your Home Assistant
- Click the ⋮ menu in the top right corner
- Select Repositories
- Add this repository URL:
https://github.com/KarlisKocins/homeassistant-addon-rustplusplus - Click Add
- Find "RustPlusPlus Discord Bot" in the add-on store
- Click on it and press Install
- Wait for the installation to complete
- Go to the Configuration tab
- Fill in the required fields:
- Discord Client ID: Your Discord application's client ID
- Discord Token: Your Discord bot token
- Log Level: Choose your preferred logging level (info recommended)
- Go to the Info tab
- Click Start
- Check the Log tab to ensure everything is running correctly
Before using this add-on, you need to create a Discord bot:
- Go to the Discord Developer Portal
- Click New Application and give it a name
- Go to the Bot section and click Add Bot
- Copy the Token (this is your Discord Token)
- Enable Message Content Intent under Privileged Gateway Intents
- Go to OAuth2 → General and copy the Client ID
- In OAuth2 → URL Generator:
- Select bot scope
- Select required permissions (Administrator recommended for full functionality)
- Use the generated URL to invite the bot to your Discord server
You'll need to get your Rust+ credentials using the official credential application:
- Download the RustPlusPlus Credential Application
- Run the application and follow the instructions
| Option | Type | Default | Description |
|---|---|---|---|
discord_client_id |
string | Required | Your Discord application's client ID |
discord_token |
password | Required | Your Discord bot token |
log_level |
list | info |
Logging level (debug, info, warning, error) |
battlemetrics_api_key |
password | (empty) | BattleMetrics API token, required for player tracking. See Player Tracking |
webui_enabled |
boolean | false |
Enable/disable the built-in RustPlusPlus WebUI |
webui_port |
integer | 3001 |
Port used by the WebUI when enabled |
webui_password |
password | (empty) | Password for the WebUI login on direct access. If left empty, a random access token is generated and printed in the add-on log on every start |
database_path |
string | /data/statistics.db |
Path for the statistics database used by WebUI/statistics features |
positions_retention_days |
integer | 14 |
How many days of player position history to keep for map replay; older rows are deleted during hourly maintenance |
Player trackers, the /players command and the information-channel player list all read the server's
player list from the BattleMetrics API.
BattleMetrics used to serve this for free. It no longer does — every endpoint now answers
403 Access denied. A subscription is required to use the API. A subscription and an API key are
therefore required for these features.
- Subscribe to a plan at battlemetrics.com
- Generate a token at battlemetrics.com/developers/token
- Paste it into the battlemetrics_api_key option in the add-on Configuration tab
- Restart the add-on
The key is stored as a Home Assistant secret and sent as a Bearer token. Requests are pinned to
api.battlemetrics.com and redirects are refused, so the token is never forwarded to another host.
The rest of the add-on is unaffected — smart devices, alarms, storage monitors, events, team chat, the map and the WebUI all work normally. Only the player-tracking features are unavailable:
- Player trackers report no players
/playersreturns nothing- The information-channel player list is removed rather than shown empty
The add-on log prints a warning at startup when no key is set.
The add-on can run an optional RustPlusPlus WebUI. When enabled, it listens on the configured webui_port.
Statistics and related feature data are stored in the SQLite database at database_path (default: /data/statistics.db).
There are two ways to open the WebUI:
- Through Home Assistant (recommended): use the add-on's Open Web UI button or the sidebar panel (ingress). No extra login is needed — Home Assistant's own authentication protects it.
- Directly at
http://HOME_ASSISTANT_IP:<webui_port>: a login is required. Setwebui_passwordin the configuration, or use the random access token printed prominently in the add-on log at startup (a new token is generated on every restart until a password is set).
WebUI highlights:
- Live map with teammate pins, event markers, vending machine icons and shop hover cards
- Shops Browser and Insta-Profit trade route finder, both with item icons
- Team statistics: sessions, deaths, chat history, a 7×24 activity heatmap and a player-count forecast
- Map replay of recorded team positions (retention controlled by
positions_retention_days)
Example optional settings:
webui_enabled: true
webui_port: 3001
webui_password: "choose-a-strong-password"
database_path: /data/statistics.db
positions_retention_days: 14- After starting the add-on, join your Discord server where the bot was invited
- Use the
/credentialscommand to set up your Rust+ credentials - Use the
/paircommand to connect to your Rust server - Configure your desired features using the bot's commands
/help- Show all available commands/credentials- Set up Rust+ credentials/pair- Connect to a Rust server/map- View the server map/players- See online players/upkeep- Check tool cupboard upkeep
Smart Switch automation includes AUTO-NIGHT-ANY-ONLINE.
This mode turns switches on only at night when at least one teammate is online, and turns them off during daytime or when all teammates are offline.
When connected to a Rust server, the bot's Discord status automatically displays:
- The server name
- The number of online teammates (e.g.,
My Rust Server | 3/5 Online)
The add-on stores data in the following locations:
- Credentials:
/data/credentials/ - Server Instances:
/data/instances/ - Logs:
/data/logs/ - Maps:
/data/maps/ - Statistics Database:
/data/statistics.db(default, configurable viadatabase_path)
All data persists between add-on restarts and updates.
If you encounter issues during the first installation, try restarting the add-on:
- Go to the Info tab
- Click Stop to stop the add-on
- Wait a few seconds, then click Start
- Check the Log tab to verify the add-on is running correctly
Sometimes a restart can resolve initialization problems or temporary configuration issues that may occur during the initial setup.
- Check the add-on logs for errors
- Verify your Discord token and client ID are correct
- Ensure the bot has proper permissions in your Discord server
- Check if the bot is online in your Discord server
- Verify your Rust+ credentials are valid
- Check if the Rust server supports Rust+ (most official servers do)
- Ensure you're paired with the correct server
- Try restarting the add-on
Access denied. A subscription is required to use the APIin the log means BattleMetrics rejected the request. Either nobattlemetrics_api_keyis set, the token is wrong, or the subscription lapsed. Verify the token at battlemetrics.com/developers/token- After adding or changing the key, restart the add-on — it is read from the environment at startup
- Empty player lists with no error in the log usually mean the server has no BattleMetrics ID stored.
Check the server's settings in the Discord
settingschannel - Player tracking is the only feature that needs the key. If devices, events or the map are also broken, the cause is elsewhere — see the sections above
- When opening the WebUI on its direct URL, a login is required — this is expected since v2.0.0
- If you haven't set
webui_password, find the auto-generated access token in the add-on Log tab (printed in a highlighted block at startup) - Opening the WebUI through the Home Assistant sidebar or the Open Web UI button never asks for this login
- After changing
webui_password, restart the add-on and hard-refresh the browser (Ctrl+F5)
Check the add-on logs in the Log tab for detailed error messages. Common issues include:
- Invalid Discord credentials
- Missing Rust+ credentials
- Network connectivity problems
- Server pairing issues
For local development/release checks, run the startup smoke test:
chmod +x scripts/ha_addon_smoke_test.sh
./scripts/ha_addon_smoke_test.shThis emulates add-on startup with a generated /data/options.json plus a mock Supervisor API endpoint, and fails if bootstrap does not reach run.sh -> node index.js.
For support and documentation:
This add-on is based on RustPlusPlus by alexemanuelol, licensed under GPL-3.0.