# Will a server work with vpsFocus — instructions for an AI assistant

> **For the human.** Show this file to your AI assistant — Claude, ChatGPT,
> Cursor or any other — and ask: "Use these instructions to check whether my
> server will work with vpsFocus." It gathers facts about the server with
> commands that only read, and tells you in plain words whether it fits.
> Nothing on the server changes.
>
> The vpsFocus app runs the same check itself — the Run check button in the
> Environment check step after you add a server. These instructions are for knowing the answer before you download
> anything.

---

## For the AI assistant: what to do

The user wants to know whether vpsFocus can be installed on their server
(VPS). vpsFocus is a desktop app: over SSH it installs website analytics and
monitoring on the user's server, in isolated Docker containers, next to the
site that is already running and without changing it.

Your job is to gather facts about the server, judge them by the rules below
and explain the result in plain words. The user is most likely not a system
administrator: do not use jargon without explaining it.

### Safety rules — mandatory

1. **Read only.** Run only the commands from the Commands section below.
   Install, update, restart or reconfigure nothing, even if it would "fix"
   a problem. Fixes are advice only.
2. **Show the commands before running them**, and run them once the user
   agrees.
3. **Do not ask for passwords or keys in the chat.** If a login to the server
   is needed, the user connects themselves, the way they usually do.
4. **Do not download or run scripts from the internet** for this check.

### How to gather the facts

- **If you have a terminal** (for example Claude Code, Cursor, Codex) and the
  user can already log in to the server over SSH — run the commands on the
  server over `ssh`, as the user vpsFocus will install as.
- **If you do not have a terminal** — ask the user to log in to the server,
  run the whole block of commands and send you the entire output.

### Commands

All commands only read. Run them as the same user vpsFocus will install as
(root or a user with sudo).

```sh
echo "== OS";            cat /etc/os-release 2>/dev/null | grep -E '^(ID|VERSION_ID|PRETTY_NAME)='
echo "== KERNEL";        uname -sr
echo "== ARCH";          uname -m
echo "== VIRTUALIZATION"; systemd-detect-virt 2>/dev/null || echo "unknown"
echo "== MEMORY_MB";     awk '/^MemTotal:/ {printf "%d\n", $2/1024}' /proc/meminfo
echo "== DISK_FREE_MB";  df -Pk / | awk 'NR==2 {printf "%d\n", $4/1024}'
echo "== USER_ID";       id -u
echo "== PASSWORDLESS_SUDO"; (command -v sudo >/dev/null && sudo -n true 2>/dev/null && echo yes) || echo no
echo "== DOCKER";        (command -v docker >/dev/null && docker --version) || echo "not installed"
echo "== DOCKER_RUNNING"; (command -v docker >/dev/null && { docker info >/dev/null 2>&1 || sudo -n docker info >/dev/null 2>&1; } && echo yes) || echo no
echo "== COMPOSE";       (docker compose version 2>/dev/null) || echo "none"
echo "== SYSTEMD";       [ -d /run/systemd/system ] && echo yes || echo no
echo "== CURL";          command -v curl >/dev/null && echo yes || echo no
echo "== LISTENING_PORTS"; (ss -ltnH 2>/dev/null || netstat -ltn 2>/dev/null) | awk '{print $4}' | grep -oE '[0-9]+$' | sort -un | tr '\n' ' '; echo
echo "== FIREWALL";      for f in ufw firewall-cmd nft iptables; do command -v $f >/dev/null && echo $f; done
echo "== FORWARDS_TRAFFIC"; cat /proc/sys/net/ipv4/ip_forward 2>/dev/null
```

### Rules

The result is one of three: **works**, **works with caveats**, **will not
work**. One blocker makes it "will not work". No blockers but some caveats
makes it "works with caveats".

**Blockers — installing is impossible:**

| Check | Blocker when |
|---|---|
| Architecture | neither `x86_64`/`amd64` nor `aarch64`/`arm64` |
| Memory | less than 1024 MB in total (`MEMORY_MB`) |
| Disk | less than 5120 MB free on `/` (`DISK_FREE_MB`) |
| Privileges | not root (`USER_ID` ≠ 0) and no passwordless sudo |
| Docker | installed but not running (`DOCKER_RUNNING` = no) |
| curl | missing (`CURL` = no) |
| OS without Docker | Docker is not installed and `ID` in `/etc/os-release` is none of: `ubuntu`, `debian`, `raspbian`, `centos`, `rhel`, `rocky`, `fedora` — vpsFocus installs Docker with Docker's official script, which does not support other systems |
| Not Linux at all | Windows, macOS, shared hosting without SSH access to the server |

**Caveats — the install will go through, but mention them:**

| Check | Caveat when | What to say |
|---|---|---|
| Memory | 1024 to 2048 MB | it will run, but tightly; a traffic spike may slow it down |
| Disk | 5120 to 10240 MB | space is tight: the database and logs grow |
| Docker | not installed | vpsFocus installs it |
| Compose | Docker is there, Compose is not | vpsFocus installs it |
| systemd | missing | monitoring will not come back by itself after a reboot |
| Traffic forwarding | Docker is not installed and `FORWARDS_TRAFFIC` = 1 | the server shares its connection with other machines (a VPN like WireGuard, LXC containers); once installed, Docker takes over the network rules and that sharing may break |
| Firewall | `ufw`, `firewall-cmd`, `nft` or `iptables` found | if the firewall is on, monitoring needs one port opened: with `ufw` and `firewall-cmd` vpsFocus does it itself with the user's permission, with `nft` and `iptables` the port has to be opened by hand |
| Ports | all of 443 2053 2083 2087 2096 8443 are taken | monitoring falls back to another port; if the domain is proxied through Cloudflare on the free plan, tracking will not get through that port |
| Virtualization | `openvz` or `lxc` | Docker often does not start on such VPSes; only an install can tell for sure (if it fails, vpsFocus rolls everything back itself) |

**Not blockers, even if they look like it:**

- Ports 80 and 443 are taken — that is usually the user's site; vpsFocus
  leaves them alone and uses its own port.
- An old but supported OS version (for example Ubuntu 20.04, Debian 11) —
  the Docker install warns about it but goes through.
- A web server is already running (nginx, Apache, Caddy) — vpsFocus does not
  change it.

### What else is needed

Tell the user that besides the server the install needs **a domain or
subdomain pointed at this server** (for example `stats.myweb.com`) — the
statistics run on it. Commands on the server cannot check this — just remind
them.

### How to answer the user

1. First line — the result: works / works with caveats / will not work.
2. Then one point per problem or caveat found: what it means in plain words
   and what can be done.
3. If it works — suggest downloading the app: https://vpsfocus.xyz/download
4. If it will not work — say what exactly needs to change (for example "you
   need a VPS with at least 1 GB of memory, 2 GB is better"), without telling
   them to switch hosting if the problem can be solved on this server.

Do not promise more than you know: this check follows the same rules as the
app, but the final answer comes from the environment check in vpsFocus itself.