Back to Documentation

Adding Your First Server

Learn how to connect ProxMan to your Proxmox VE, Proxmox Backup Server, or Proxmox Datacenter Manager.

Prerequisites

Before adding a server, make sure you have:

  • Your Proxmox server's IP address or hostname
  • The web interface port (default: 8006)
  • Valid Proxmox credentials (username and password)
  • Network access from your mobile device to the Proxmox server

Step-by-Step Guide

1. Open ProxMan

Launch the ProxMan app on your mobile device.

2. Add New Server

Tap the Add Server button on the main dashboard.

3. Choose Server Type

Select the type of server you're adding:

  • Proxmox VE (PVE) - For virtual machines and containers
  • Proxmox Backup Server (PBS) - For backup management
  • Proxmox Datacenter Manager (PDM) - For fleet-wide datacenter management across multiple PVE clusters and PBS servers

4. Choose Authentication Method

ProxMan supports multiple authentication methods. Note: OpenID Connect is supported for PVE and PBS only — PDM requires traditional authentication or API tokens.

Standard Authentication

  • Username and password
  • Support for TOTP/2FA
  • Works with all Proxmox versions
  • Direct authentication with Proxmox

API Token Authentication

  • Uses Proxmox API Tokens instead of user passwords
  • Configured in Proxmox under Data Center > Permissions > API Tokens

OpenID Connect (OIDC)

  • Modern OAuth2-based authentication
  • Single sign-on (SSO) support
  • Token-based authentication (no password storage)
  • Requires OpenID Connect realm configured on Proxmox
  • Works with Keycloak, Azure AD, Google, Okta, Auth0, and more
  • See OpenID Connect Configuration Guide for setup instructions

5. Enter Server Information

For Traditional Authentication:

  • Display Name: Friendly name for your server

- Example: "Home Lab", "Production Server", "Backup Server"

  • Hostname/IP: Your server's address

- Example: 192.168.1.100 or proxmox.example.com

  • Port:

- 8006 for Proxmox VE (default)

- 8007 for Proxmox Backup Server (default)

- 8443 for Proxmox Datacenter Manager (default)

  • Username: Your Proxmox username (without realm)

- Example: root, admin, backup-user

  • Realm: Select authentication realm

- @pam - Linux system users (PAM authentication)

- @pve - Proxmox VE internal users

- @pbs - Proxmox Backup Server users

  • Password: Your password
  • HTTPS: Enable for secure connection (recommended)

For API Token Authentication:

  • Display Name: Friendly name for your server
  • Hostname/IP: Your server's address
  • Port: 8006 for PVE or 8007 for PBS
  • Advanced: Under advanced options, you can find API Token field.

- API Token: Your API Token must be on format for PVE: username@realm!tokenid=secret or for PBS: username@realm!tokenid:secret

  • HTTPS: Enable for secure connection (recommended)

For OpenID Connect:

  • Display Name: Friendly name for your server

- Example: "Production Cluster", "Dev Environment"

  • Hostname/IP: Server address

- Example: proxmox.example.com

  • Port: 8006 (PVE) or 8007 (PBS)
  • Realm: Select your configured OIDC realm

- Example: azuread, keycloak, okta

  • HTTPS: Enable for secure connection (required for OIDC)

Authentication Flow:

1. Tap "Authenticate with OpenID"

2. ProxMan opens your identity provider's login page

3. Log in with your identity provider credentials

4. Authorize ProxMan to access your account

5. You'll be redirected back to ProxMan with authentication complete

6. Tokens are securely stored in iOS Keychain or Android Keystore

Note: OpenID Connect requires your Proxmox server to have an OIDC realm configured. See our OpenID Connect Configuration Guide for detailed setup instructions. OpenID is not available for PDM servers.

6. Two-Factor Authentication (2FA)

If your server has TOTP/2FA enabled:

1. Enter your username and password

2. Tap "Add Device"

3. When prompted, enter your 6-digit TOTP code

4. The app will complete authentication

7. Custom Headers (Optional)

ProxMan allows you to configure custom HTTP headers for each server. This is useful for passing through strict network policies or authenticating with reverse proxies (e.g., Cloudflare Access, Authelia, Authentik).

  • On Advanced Options tap "Add Header" to specify Key-Value pairs that will be included in every request to this server.
  • See our Cloudflare Access Integration guide for a practical example.

8. Save Server

Once the connection test succeeds:

1. Review your settings

2. Tap "Save" or "Add Device"

3. Your server appears on the main dashboard

Troubleshooting Connection Issues

Cannot Connect to Server

  • Verify the IP address/hostname is correct
  • Check that port 8006 or 8007 is accessible from your network
  • Ensure your firewall allows connections to Proxmox
  • Verify your credentials are correct

Authentication Failed

Traditional Authentication:

  • Double-check your username format (without realm: root, not root@pam)
  • Verify your password is correct
  • Ensure the user has appropriate permissions in Proxmox
  • Check that the selected realm matches your user's realm

OpenID Connect:

  • Verify the OIDC realm is configured correctly on Proxmox
  • Check that your identity provider is accessible
  • Ensure redirect URIs are properly configured
  • Confirm client ID and secret are correct in Proxmox
  • See OpenID Connect Troubleshooting for detailed help

API Token Authentication:

  • Double-check your API Token format (for PVE: username@realm!tokenid=secret or for PBS: username@realm!tokenid:secret)
  • Verify your API Token is correct
  • Ensure the user has appropriate permissions in Proxmox
  • Check that the selected realm matches your user's realm

Managing Multiple Servers

You can add multiple Proxmox servers to ProxMan:

1. Repeat the steps above for each server (PVE, PBS, or PDM)

2. Long-press a server card and enter edit mode to drag and reorder your list

3. Switch between servers from the main dashboard

4. View all servers in the unified server list

Next Steps

Was this page helpful? Contact Support