Install RefugeBot on your server

1 Sign in

Use Steam (recommended — your in-game account) or Discord (if your community lives there).

1. Open app.refugegaming.org and click either Continue with Steam or Continue with Discord.
2. Steam OpenID handles the redirect — we don't see your password and don't need a Steam app registration. Discord OAuth works the same way.
3. You'll land on the Hub.

2 Create a tenant + add a server

Your tenant is your team / organization. Each tenant can have one or more servers. Each server gets its own AgentKey that the Agent uses to authenticate.

1. From the Hub, click + Add server.
2. If you don't have a tenant yet, you'll be prompted to name one (e.g. "Jake's PVE"). The slug auto-generates from the name.
3. You'll be prompted for a server name (e.g. "Jake Main"). The slug becomes part of the URL where your players will visit the shop: app.refugegaming.org/s/<your-slug>/shop.
4. A modal pops up with your AgentKey — a string starting with rb_ followed by 22 random characters. Copy it now. It's only shown once in cleartext.

3 Install the mod

1. Stop your 7DTD dedicated server. The agent loads at process start, so installing while it's running won't pick up.
2. Download RefugeBot-Agent-v1.0.2.zip (835 KB).
3. Unzip directly into your 7DTD server's root directory — the same folder that contains 7DaysToDieServer.exe (Windows) or startserver.sh (Linux). The zip's Mods/ folder will merge with your existing one.

   <your-7dtd-server-root>/
     Mods/
       zzzzzzzRefugeBot/        ← created by the zip
         RefugeBot.dll
         RefugeBot.Protocol.dll
         Newtonsoft.Json.dll
         ModInfo.xml

4. Open your serverconfig.xml and confirm EnableMods is true — without this, 7DTD silently skips the Mods/ folder.

4 First-boot setup web UI

Start your 7DTD server. On first boot the agent has no AgentKey yet, so it spins up a tiny one-page web UI and waits for you to configure it.

Find the URL in your 7DTD log

The agent picks its port automatically based on your server's WebDashboardPort (so multi-instance hosts each get a unique port). Watch the 7DTD console / log right after mod load — you'll see:

╔══════════════════════════════════════════════════════════════════╗
║ RefugeBot Agent — first-boot setup                              ║
║ Open this URL in a browser to configure:                        ║
║   http://<this-server-ip>:8081/                             ║
║ (or http://localhost:8081/ if you're on the box)               ║
╚══════════════════════════════════════════════════════════════════╝

The port shown there is what to open. Common values: 8081 if your server uses the default WebDashboardPort=8080, or 8765 as a fallback if serverconfig.xml couldn't be located.

Configure

1. From a browser that can reach your server, open the URL from the log line above.
   • Same machine as 7DTD: use http://localhost:<port>.
   • Remote box: SSH-tunnel — ssh -L 8081:localhost:8081 user@your-server, then open http://localhost:8081 on your laptop. (Substitute the actual port from your log.)
2. Paste:
   • Service URL: wss://app.refugegaming.org/agent/ws
   • AgentKey: the rb_… string from step 2.
   • Server nickname: a short label (e.g. "Jake Main").
3. Click Save. The agent writes the config to two places:
   • <mod folder>/refugebot.json
   • <server-root>/RefugeBotData/refugebot-agent.json (backup, survives mod-folder wipes)
4. Within ~10 seconds your server's status pill in the dashboard flips from offline to online. You're done.

Once the agent is configured, the setup port closes itself — leaving it forwarded is harmless but pointless. To re-open it (e.g. to change the AgentKey), delete both config files above and restart 7DTD.

Troubleshooting

Setup page doesn't load

• First, find the actual port the agent picked — look for the boxed "RefugeBot Agent — first-boot setup" banner in your 7DTD console log; it prints the URL with the resolved port. If you don't see that banner at all, the mod isn't loading — usually EnableMods is off in serverconfig.xml, the Mods/zzzzzzzRefugeBot/ folder is in the wrong place, or one of the seven files in step 3 is missing.
• If you see "Could not bind any setup port starting at NNNN": every port in the hunt range was taken. Pin a specific free port via Mods/zzzzzzzRefugeBot/refugebot.json → {"setupPort": 9000} (any value above 1024) and restart 7DTD.
• Firewall: allow inbound TCP on the port the log shows (default range starts at WebDashboardPort + 1 — usually 8081 — or 8765 as fallback).

Connects but dashboard says "offline" or "handshake rejected"

• Almost always a wrong AgentKey. The rb_ prefix is required. Re-copy from the dashboard, paste again, restart 7DTD.
• If you see Could not load type … RefugeBot.Protocol in the 7DTD log, RefugeBot.Protocol.dll is missing from the mod folder. Re-extract the zip — all four files must sit together.
• Outbound HTTPS firewalled? Whitelist app.refugegaming.org on TCP 443.

Where is the agent config stored?

• Primary: <7dtd-root>/Mods/zzzzzzzRefugeBot/refugebot.json
• Backup: <7dtd-root>/RefugeBotData/refugebot-agent.json

To rotate the key or move to a different tenant: edit either file (the agent self-heals on next start) or delete both to re-trigger setup mode.

Still stuck?

Hop into our Discord and post in #self-host-help with the last 50 lines of your 7DTD log around the [RefugeBot] entries.