Servers

Server Management

Shield servers are the core of your Lumos Gate infrastructure. Each server is a VPS running the Lumos Agent with HAProxy, acting as a reverse proxy that hides and protects your origin servers.

This page covers everything you can do with servers in the dashboard. For agent-side management (logs, service control, health monitoring), see Agent CLI.

Adding a Server

To add a new shield server:

1. Navigate to Dashboard -> Servers
2. Click Add Server
3. Enter a descriptive name for the server (e.g., "US East Shield", "EU Frankfurt Proxy")
4. Click Create

After creation, a connection token is displayed. This token is used by the agent to authenticate with the Lumos WebSocket server.

Warning: The connection token is displayed only once. Copy it immediately. The token is hashed using SHA-256 before being stored in the database, which means it cannot be retrieved or displayed again. Only a short prefix is stored for identification purposes. If you lose the token, you must decommission the server and create a new one.

Tip: Store the token temporarily in a secure location (password manager, encrypted note) until you have completed the agent installation. After the agent connects successfully, the token is no longer needed on your end -- it is stored encrypted in the agent's config file on the VPS.

Installing the Agent

Once you have the token, SSH into your VPS and install the agent:

curl -fsSL https://get.lumosgate.com/install | LUMOS_TOKEN=YOUR_TOKEN bash

The server status in the dashboard will change to Online within a few seconds after the agent connects. For full installation details including installer flags, system requirements, and troubleshooting, see Agent Installation.

Server Status

Each server has one of three statuses:

When a server goes offline, the dashboard sends a notification immediately (if server_down notifications are configured). Additionally, the maintenance loop checks for stale connections every 5 minutes as a safety net.

When an offline server reconnects, a server_recovered notification is sent, and the agent automatically performs a full configuration sync to catch up on any changes it missed while disconnected.

Tip: If a server frequently flips between Online and Offline, check the network stability of your VPS. Intermittent connectivity can cause repeated WebSocket disconnections. Review the agent logs with journalctl -u lumos-agent -f (see Agent CLI) for reconnection patterns.

Server Details Page

Click on any server in the list to view its details page. The details page shows:

• Status and uptime -- Current connection state and how long the agent has been connected
• Server info -- Name, token prefix (for identification), creation date
• Assigned domains -- All domains routed through this server, with links to each domain's configuration
• Detected sites -- Existing HAProxy sites that can be imported (see Detected Sites)
• Metrics -- Real-time traffic statistics from HAProxy's stats socket, including requests per second, bytes in/out, and active connections

Editing a Server

You can update the server name at any time from the server details page. Click the server name or the edit button to modify it.

The connection token cannot be changed or regenerated. If you need a new token (e.g., if you suspect it has been compromised), decommission the server and create a new one.

Decommissioning a Server

Decommissioning permanently removes a server from your account. To decommission:

1. Navigate to the server details page
2. Click Decommission Server
3. Confirm the action

What happens during decommissioning:

1. The server status is set to decommissioned (soft delete)
2. A decommission message is sent to the WebSocket server
3. The WebSocket server notifies the agent to disconnect
4. All domain-server assignments for this server are removed
5. After a 1-hour grace period, the WebSocket server cleans up the connection entry

Note: Decommissioning is a soft delete with a grace period to prevent race conditions. The server record remains in the database with a "decommissioned" status. The agent on the VPS will stop receiving config updates and disconnect from the WebSocket server.

Important: If you have domains assigned only to the server being decommissioned, those domains will have no active shield servers after decommissioning. Make sure to either reassign those domains to another server first, or add a second server using multiple servers before decommissioning.

Decommissioning does not uninstall the agent from the VPS. To clean up the VPS itself, SSH in and run the uninstall command:

lumos-uninstall

This stops the agent, restores the original HAProxy configuration (if the backup is valid), and removes agent files. See Agent Installation for full uninstall details.

Server Limits

The number of servers you can add depends on your plan. If you reach your server limit, you will need to upgrade your plan or decommission unused servers before adding new ones.

Check the Plans page for current limits and pricing. Decommissioned servers do not count toward your limit.

Importing Existing Sites

If your VPS was already running HAProxy before you installed Lumos Gate, the agent detects the existing configuration and sends it to the dashboard. You can then selectively import those sites into Lumos management.

This is covered in detail on the Detected Sites page. Key points:

• The agent parses your existing HAProxy config (ACL + backend blocks for both HTTP and TCP passthrough)
• Each detected site shows the domain and origin mapping
• Sites already managed by Lumos are marked to avoid duplicates
• All plans include unlimited domains

Server Error Notifications

The agent reports several error types to the dashboard via the WebSocket connection. If you have notifications configured, you will receive alerts for:

These notifications can be delivered via email or webhook. Configure them in Dashboard -> Settings -> Notifications. See Notifications for setup details.

Best Practices

• Use descriptive names -- Name servers by location and purpose (e.g., "EU-West Production", "US-East Staging") so you can quickly identify them in the dashboard.

• Monitor server status -- Set up notifications for server_down and server_recovered events to be alerted immediately when a shield goes offline.

• Multiple servers for redundancy -- Assign critical domains to at least two servers in different locations. Combined with DNS failover, this ensures your sites stay online even if one shield goes down. See Multiple Servers for configuration details.

• Decommission unused servers -- Decommissioned servers no longer count toward your plan limits. Clean up servers you are no longer using.

• Lock down origin servers -- After adding a shield server, configure your origin firewall to only accept traffic from the shield VPS IP. This prevents attackers from bypassing the proxy.

• Use WireGuard for private communication -- For maximum security, set up a WireGuard tunnel between your shield VPS and origin server. This encrypts all traffic between them and eliminates the need to expose any ports on your origin.

Next Steps

• Agent Installation -- Install the agent on your VPS
• Agent CLI -- Manage the agent service, view logs, understand health monitoring
• Detected Sites -- Import existing HAProxy sites into Lumos
• Domains -- Add and configure domains on your shield servers
• Multiple Servers -- Assign domains to multiple shields for redundancy
• DNS Failover -- Automatic traffic switching when a shield goes down
• Notifications -- Get alerts for server events
• Plans -- Check server limits for your plan