Opterius Panel can manage one or more servers from a single interface. The number of servers you can connect is determined by your license plan:
| Plan | Max Servers |
|---|---|
| Free | 1 |
| Starter | 1 |
| Plus | 1 |
| Business | 5 |
| Datacenter | Unlimited |
Each server runs its own Opterius Agent — a small Go binary that handles all OS-level operations (creating accounts, managing nginx vhosts, issuing SSL certificates, etc.). The Panel coordinates the fleet via authenticated HTTP calls to each agent.
How It Works
When you add a server to your Panel:
- Panel side — You enter the server's name, IP, and hostname. The Panel generates a unique agent token (HMAC secret) and stores the server record in its database.
- Server side — You SSH into the new server and run the agent installer with that token. The agent registers itself.
- License gate — The agent calls
https://opterius.com/api/license/verifywith the new server's IP. opterius.com checks: does this license have a free activation slot undermax_servers?- Yes → activation recorded, agent allowed to operate
- No → agent rejected, all write operations blocked
- Online — Once the license check succeeds and the Panel can reach the agent, the new server appears as Online in your Panel.
Prerequisites
- An active license with
max_servers > 1(Business, Datacenter, or a custom plan). - A fresh server running a supported OS (AlmaLinux 8/9, Rocky Linux 8/9, Ubuntu 22.04/24.04, Debian 12).
- Root SSH access to the new server.
- Outbound HTTPS from the new server to
opterius.com(for license verification). - Outbound HTTPS from the Panel server to the new server's agent port (default
7443).
Step 1: Add the Server in the Panel
In your Panel, go to Server Mode → Servers → Add Server. Fill in:
- Display Name — a friendly label (e.g.,
eu-frankfurt-1,client-acme). - IP Address — the new server's public IP.
- Hostname — optional, for display only.
Click Save. The Panel creates the server record and generates the agent token.
Step 2: Get the Install Command
After saving, open the new server's detail page. Click Show Install Command to reveal a one-line installer that includes the agent token:
curl -sL https://get.opterius.com/install-agent.sh | bash -s -- --token=AGENT_TOKEN_HERE
The token is unique to this server — anyone with it can register as that server, so treat it like a password.
Step 3: Install the Agent on the New Server
SSH into the new server as root and run the command from Step 2:
ssh root@new-server.example.com
curl -sL https://get.opterius.com/install-agent.sh | bash -s -- --token=AGENT_TOKEN_HERE
The installer:
- Detects your OS and architecture (amd64 / arm64).
- Downloads the agent binary to
/usr/local/bin/opterius-agent. - Writes the configuration file at
/etc/opterius/agent.conf(token, listen address, port). - Creates the
opterius-agentsystemd service and starts it. - Triggers the first license check against
opterius.com.
Installation typically completes in under two minutes.
Step 4: Confirm the Server Is Online
Return to Server Mode → Servers. The new server should appear with a status of Online within 30 seconds.
If it remains Pending or Offline after a minute, see Troubleshooting below.
You can verify the agent on the new server directly:
# Service status
systemctl status opterius-agent
# Last log lines (look for "License: valid")
journalctl -u opterius-agent -n 50
# Agent listening on port 7443
ss -tlnp | grep 7443
Step 5: Use the New Server
Once Online, the server appears in the Server dropdown when creating accounts:
Server Mode → Accounts → Create Account → Server: [eu-frankfurt-1]
Each account is provisioned on a single server. Existing accounts cannot be migrated between servers from the Panel UI — see Account Migration for that workflow.
Managing License Activations
Every server that registers consumes one activation slot under your license. Slot management lives at opterius.com → Dashboard → Licenses.
Viewing activations
Each license card shows a list of Activated Servers:
- Active (green dot) — the server has checked in within the last 7 days.
- Inactive (grey dot, "slot freed" label) — the server hasn't checked in for 7+ days. The slot is automatically freed and a new server can take its place. Inactive rows are kept for history and auto-deleted after 30 days.
Revoking an activation
If you need to free a slot manually (e.g., you're decommissioning a server and want to install on a replacement immediately), click Revoke next to the IP. The agent on that server will block all writes on its next license check (within 24 hours).
What if I exceed my limit?
If you try to install the agent on a server beyond your plan's max_servers, the agent will receive license_invalid: server_limit_reached and refuse to operate. The Panel will show the server as Pending indefinitely.
Three ways to resolve:
- Revoke an unused activation from your opterius.com dashboard.
- Wait for stale auto-expiry — if a server has been offline for 7+ days, its slot is already free; just retry the install.
- Upgrade your plan to one with more
max_servers.
Typical Use Cases
- Geographic distribution — place servers near your customers (EU, US, APAC).
- Client isolation — dedicate a server to a single large client for compliance or performance.
- Workload separation — separate development/staging from production.
- Capacity scaling — spread accounts across servers to avoid overloading any single machine.
Troubleshooting
Server stuck on "Pending"
The Panel created the record but the agent hasn't checked in. On the new server:
# Check the agent is running
systemctl status opterius-agent
# Check for errors
journalctl -u opterius-agent -n 50 --no-pager
Common causes:
- Token mismatch — the token in
/etc/opterius/agent.confdoesn't match the one in the Panel. Regenerate by deleting the server in the Panel and re-adding it. - Outbound HTTPS blocked — the agent can't reach
opterius.comfor license verification. Open port 443 outbound. - Inbound port blocked — the Panel can't reach the agent on port 7443. Open it in your firewall (allow only the Panel's IP, not the public internet).
Agent log shows "License: INVALID — server_limit_reached"
You've hit your plan's server limit. See Managing License Activations above.
Agent log shows "License: INVALID — invalid_key"
The license key in /etc/opterius/agent.conf doesn't exist or is malformed. Verify it matches the key shown at opterius.com → Dashboard → Licenses.
Agent log shows "License: INVALID — expired"
Your license has expired. Renew via your opterius.com billing dashboard.
Agent crashes immediately on start
Check /var/log/opterius-agent.log (if configured) or journalctl -u opterius-agent. Most common: missing /etc/opterius/agent.conf or invalid permissions on it (chmod 600 required).