Install RefugeBot
on your server

01 // Sign in

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

1. Open refugebot.com 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.

02 // 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: refugebot.com/s/<your-slug>/shop.
4. A modal pops up with two downloads — the Agent mod zip and your pre-filled refugebot.json (it already has your AgentKey and the Service URL baked in, so there's nothing to copy or paste). Grab both. You'll use them in the next step.

03 // Install the mod + your config

Two files to drop in: the mod itself, and the pre-filled refugebot.json you downloaded in step 2. No editing, no copy-paste — the config already has your AgentKey and Service URL baked in.

1. Stop your 7DTD dedicated server. The agent loads at process start, so installing while it's running won't pick up.
2. Unzip the Agent (RefugeBot-Agent-v1.2.39.zip, ~600 KB) 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 merges with your existing one.

   <your-7dtd-server-root>/
     Mods/
       zzzzzzzRefugeBot/        ← created by the zip
         RefugeBot.dll
         RefugeBot.Protocol.dll
         System.Threading.Channels.dll
         System.Threading.Tasks.Extensions.dll
         System.Runtime.CompilerServices.Unsafe.dll
         ModInfo.xml
         Config/ ...

3. Drop your refugebot.json into the RefugeBotData folder under your save data (create the folder if it doesn't exist):

   <UserData>/Saves/RefugeBotData/refugebot.json

   • Linux: ~/.local/share/7DaysToDie/Saves/RefugeBotData/
   • Windows: %APPDATA%\7DaysToDie\Saves\RefugeBotData\

04 // Start & confirm online

Start your 7DTD server. The agent reads refugebot.json on boot, connects to wss://refugebot.com/agent/ws with your AgentKey, and dials home — no further setup.

1. Watch the 7DTD console / log for the [RefugeBot] lines: it should report the boot path, then Dialing wss://refugebot.com/agent/ws, then a successful connect.
2. Within ~10 seconds your server's status pill in the Hub flips from offline to online. That's it — you're done.

05 // Manual setup (no dashboard access)

If you can't drop the pre-filled refugebot.json in (e.g. a locked-down host where you'd rather wire it up in a browser), the agent has a built-in first-boot web UI. Start your server without a config file present and the agent spins up a one-page setup form instead.

Find the URL in your 7DTD log

The agent picks its setup port automatically based on your server's WebDashboardPort (so multi-instance hosts each get a unique port). Watch the console right after mod load:

╔══════════════════════════════════════════════════════════════════╗
║ 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://refugebot.com/agent/ws
   • AgentKey: open your server's card in the Hub → "Or wire it up manually — show the AgentKey" to reveal the rb_… string.
   • Server nickname: a short label (e.g. "Jake Main").
3. Click Save. The agent writes refugebot.json to <UserData>/Saves/RefugeBotData/ for you, then connects. Your status pill flips to online.

Once the agent is configured, the setup port closes itself. To re-open it (e.g. to re-key), delete <UserData>/Saves/RefugeBotData/refugebot.json and restart 7DTD.

06 // 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 the Mods/zzzzzzzRefugeBot/ folder landed in the wrong place (it must sit directly under your 7DTD server root's Mods/ folder), or one of the files from 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 by adding "setupPort": 9000 (any value above 1024) to your <UserData>/Saves/RefugeBotData/refugebot.json 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 six files (plus the Config/ folder) must sit together.
• Outbound HTTPS firewalled? Whitelist refugebot.com on TCP 443.

Where is the agent config stored?

• Canonical: <UserData>/Saves/RefugeBotData/refugebot.json — this is where the pre-filled download goes and the first place the agent looks.
  • Linux: ~/.local/share/7DaysToDie/Saves/RefugeBotData/refugebot.json
  • Windows: %APPDATA%\7DaysToDie\Saves\RefugeBotData\refugebot.json
• Older install locations (a refugebot.json in the mod folder, or a refugebot-agent.json backup) are still read as a fallback for upgrades, but new installs use the canonical path above.

To re-key or move to a different tenant: download a fresh refugebot.json from the Hub and replace this file (the agent self-heals on next start), or delete it to re-trigger the manual setup web UI.

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.