On your server
What ServerMage can and can't do on your server.
Updated October 25, 2026 · Agent 0.19.0
The short version
- ServerMage puts one small program on your server, the Agent, in a Docker container named
servermage-agent. - It installs, updates, backs up and checks the apps you pick, and does nothing else. There's no way to run commands on your server through it.
- It never changes containers it didn't create, and never deletes your data unless you ask it to.
- It contacts a short list of internet addresses, all listed below. It sends no analytics or tracking.
- You can remove it completely from the app at any time.
This page is for anyone who wants to know exactly what they're letting onto their server, and for the friend who set it up for them. If anything here is unclear, or you find the Agent doing something this page doesn't say, please tell us.
What the Agent can access, and why
To install and look after apps, the Agent needs real access to your server. Here's all of it:
- Docker. The Agent uses Docker to start, stop, update and remove the apps it installed. Access to Docker is powerful (on Linux it amounts to full control of the server), which is why what the Agent does with it is limited to the short list on this page, and why only your iPhone can ask it to do anything.
- Its own folder,
/opt/servermage. Its settings, the apps' data, backups and logs live here. It's the only place on your server the Agent writes to directly. - The rest of your server, read only. The Agent can read (never change) your server's files. It uses this to report memory, disk space and other health figures, check folders before an install, and let you browse folders when you choose where an app keeps its files.
- Your network. The Agent listens on port 47800 on your home network, where your iPhone connects to it. It's never put on the internet, even with remote access on.
The Agent runs as root inside its container, because Docker and /opt/servermage require it. Its container has no shell or package manager, only the Agent program itself.
What it changes on your server
- The apps you install. Each app runs in its own containers, named starting with
sm-and labelledapp.servermage.*. Every app definition comes from ServerMage's signed catalog and is checked before it runs: images pinned to exact versions, and no app gets powers that could take over your server. Apps answer on their own ports on your home network (Jellyfin on 8096, for example), shown in the app. - Folders you choose for an app. If a folder you picked doesn't exist yet, the Agent creates it, plus up to two missing folders above it, using a short-lived helper container that can see only that spot. It never takes over a folder that already exists in its place.
- Two helpers of its own.
sm-caddygives your apps simple addresses on port 80.sm-cloudflaredruns only when you turn remote access on. - Its own updates. Between 3:30 and 5:00 at night (server time), the Agent installs a new version of itself if the signed catalog offers one, and goes back to the old version if the new one doesn't start properly. It only accepts ServerMage's own published images. You can turn automatic updates off in the app.
- Pi-hole names, if you use Pi-hole. It adds names like
jellyfin.yourserver.hometo Pi-hole's local DNS list, each marked as ServerMage's, and only ever changes its own entries. - Your Cloudflare account, if you turn on remote access. Using a token you create, it sets up one tunnel and one web address for each app you choose. It never touches anything else in your account.
What it never does
- Run commands you didn't ask for. The Agent only accepts specific requests like "install Jellyfin" or "back up Immich". There's no way to send it a shell command or a raw Docker command, from the app or anywhere else.
- Touch containers it didn't create. The app can show your other containers, but ServerMage never starts, stops, changes or removes them.
- Delete your data by default. Removing an app keeps its data unless you choose to delete it, and ServerMage never deletes your own folders (your media, photos or documents).
- Change your system. After setup, it doesn't install system packages, change system settings, change your firewall's settings or open ports on your router. (Docker itself adds network rules for the ports your apps use, as it does for any container.)
- Phone home. No analytics, crash reports or usage data. Requests to our catalog carry no account, device or server identifier.
- Take orders from anyone but you. Every request must be signed by a key kept in the Secure Enclave of an iPhone you paired. You can see and revoke paired iPhones in the app.
Every internet address it contacts
Your server makes these connections because of ServerMage. You can watch for them, or block anything you don't use.
catalog.servermage.app, always, about every 6 hours: the signed list of apps and Agent updates. Hosted on Cloudflare.ghcr.io(GitHub's container registry) anddocker.io(Docker Hub), when you install or update an app, and when the Agent updates itself. Docker downloads the images from there and from those registries' download servers.push.servermage.app, only if you turn on notifications (Pro). The message is encrypted on your server, so the relay can't read it.api.cloudflare.com, only if you turn on remote access (Pro), to set up and remove the tunnel and addresses in your own Cloudflare account.- Cloudflare's tunnel network, only while remote access is on:
sm-cloudflaredkeeps an outgoing connection to Cloudflare, which carries visits to the apps you chose. Nothing is opened on your router.
During setup only (once, over SSH, when you add the server): if Docker isn't installed yet, setup downloads it from Docker's official repository, download.docker.com, and installs the Agent from ghcr.io.
The apps themselves make their own connections, under their own settings. For example, Immich downloads its search models and Plex signs in to plex.tv. ServerMage doesn't add any.
What setup does
When you add a server, the app signs in over SSH once and runs two short scripts:
- A read-only check of your server: its Linux version, memory, disk space, Docker and firewall. It changes nothing.
- The install: Docker from Docker's official repository if it's missing; the
/opt/servermagefolder; port 47800 (for your iPhone) and mDNS (so your iPhone can find the server) opened in ufw or firewalld, if one is active; then the Agent.
After that, the app forgets your password. SSH is only used again if you ask the app to repair or remove ServerMage.
You can read the scripts before you add a server. They're the exact files the app runs: the check, the install and the removal, with their SHA-256 checksums.
Removing it
"Remove ServerMage from This Server" in the app signs in over SSH and removes the Agent, its helpers and the firewall rules setup opened: port 47800, and mDNS if setup was the one that opened it (a rule your server already had stays). You choose whether its apps go too, and whether their data and backups in /opt/servermage are deleted. It never removes Docker, your other containers or your own folders.
Check it yourself
If you're comfortable with a terminal, you can confirm what's on this page:
docker inspect servermage-agentshows the Agent's image, the folders it can see (Mounts) and its network.docker ps --filter label=app.servermage.managedlists ServerMage's apps, anddocker ps --filter label=app.servermage.systemits helpers. Everything else is yours.- Watch your server's outgoing connections (for example in your router or Pi-hole) and compare them with the list above.
- The Agent keeps a log of every action it takes and which iPhone asked for it, in its own database under
/opt/servermage. Nothing can edit or delete it, not even ServerMage. The app shows it: open a server, then Activity.
Questions or a problem
If you think you've found a security problem, or the Agent doing anything this page doesn't describe, email hello@theblackwell.app. We read every message and will reply.