How to configure CtrlFreak with your homelab. Setup instructions for each integration, answers to common questions, and tips for getting connected.
Demo mode lets you explore the full app without connecting to any real servers. It populates every screen with realistic mock data so you can see exactly what CtrlFreak looks like with a working homelab.
To enable it: open the app for the first time and tap Try Demo, or go to Settings and toggle Demo Mode on.
Demo mode is read-only. Actions like starting a VM or restarting a container are simulated locally and have no effect on real infrastructure.
CtrlFreak supports importing a JSON configuration file so you don't have to enter API tokens and addresses one field at a time on your phone keyboard.
All credentials are stored encrypted in the OS keychain after import and the raw JSON is discarded.
Copy the template below, fill in your server details, and import it in Settings > Import JSON. Remove any integrations you don't use. The id fields can be any unique string.
{
"proxmoxServers": [
{
"id": "proxmox-1",
"label": "My Proxmox",
"host": "https://192.168.1.38:8006",
"token": "user@pam!tokenname=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"verifySSL": false
}
],
"portainerHost": "http://192.168.1.73:9000",
"portainerToken": "your-portainer-api-token",
"uptimeKumaHost": "http://192.168.1.73:3001",
"uptimeKumaUser": "",
"uptimeKumaPass": "",
"idracServers": [
{
"id": "idrac-1",
"label": "My Server",
"host": "https://192.168.1.51",
"username": "root",
"password": "your-idrac-password"
}
],
"piholeHost": "http://192.168.1.100",
"piholeToken": "your-pihole-api-token",
"tailscaleTailnet": "your-tailnet-name",
"tailscaleApiKey": "tskey-api-xxxxxxxxxxxx",
"tailscaleApiUrl": "",
"unraidServers": [
{
"id": "unraid-1",
"label": "Unraid Tower",
"host": "http://192.168.1.52",
"apiKey": "your-unraid-api-key"
}
],
"npmServers": [
{
"id": "npm-1",
"label": "Nginx Proxy Manager",
"host": "http://192.168.1.73:81",
"email": "admin@example.com",
"password": "your-npm-password"
}
],
"adGuardServers": [
{
"id": "adguard-1",
"label": "AdGuard Home",
"host": "http://192.168.1.53:3000",
"username": "admin",
"password": "your-adguard-password"
}
],
"pbsServers": [
{
"id": "pbs-1",
"label": "Proxmox Backup Server",
"host": "https://192.168.1.38:8007",
"token": "user@realm!tokenname=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
],
"dockgeServers": [
{
"id": "dockge-1",
"label": "Dockge",
"host": "http://192.168.1.73:5001",
"username": "admin",
"password": "your-dockge-password"
}
],
"beszelServers": [
{
"id": "beszel-1",
"label": "Beszel",
"host": "http://192.168.1.73:8090",
"username": "you@example.com",
"password": "your-beszel-password"
}
],
"trueNASServers": [
{
"id": "truenas-1",
"label": "TrueNAS",
"host": "http://192.168.1.52",
"apiKey": "your-truenas-api-key"
}
],
"opnsenseServers": [
{
"id": "opnsense-1",
"label": "OPNsense",
"host": "https://192.168.1.1",
"apiKey": "your-api-key",
"apiSecret": "your-api-secret"
}
],
"hpiloServers": [
{
"id": "hpilo-1",
"label": "HP iLO",
"host": "https://192.168.1.51",
"username": "Administrator",
"password": "your-ilo-password"
}
],
"synologyServers": [
{
"id": "synology-1",
"label": "Synology NAS",
"host": "http://192.168.1.54:5000",
"username": "admin",
"password": "your-dsm-password"
}
],
"wolDevices": [
{
"id": "wol-1",
"name": "My Server",
"mac": "AA:BB:CC:DD:EE:FF",
"broadcastIp": "192.168.1.255"
}
],
"wolRelayUrl": "",
"enabledIntegrations": {
"proxmox": true,
"portainer": true,
"uptimeKuma": true,
"idrac": true,
"pihole": true,
"tailscale": true,
"unraid": true,
"nginxProxyManager": true,
"adGuardHome": false,
"proxmoxBackupServer": false,
"dockge": false,
"beszel": false,
"truenas": false,
"opnsense": false,
"hpilo": false,
"synology": false
},
"demoMode": false
}
tailscaleApiUrl and wolRelayUrl as empty strings unless you have a custom setup. Arrays like proxmoxServers support multiple entries.Demo mode (always free): Explore all 16 integrations with realistic sample data. No account or server required, no time limit.
7-day free trial: Connect your real servers and use everything. Starts automatically when you add your first integration.
Pro ($9.99 one-time): Full access to all 16 integrations with your real infrastructure after the trial ends. No subscription, no renewal, no tricks.
All server credentials, API tokens, and passwords are stored in the OS secure keychain (iOS Keychain / Android Keystore). They are encrypted at rest and never leave your device.
CtrlFreak has no backend server. There is no developer cloud, no relay, no telemetry. Every request goes directly from your phone to your servers.
root@pam) or create a dedicated userctrlfreak)The token format is: user@realm!tokenname=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
https://192.168.1.38:8006For read-only access: PVEAuditor role on /.
For full control (start/stop VMs, etc.): PVEAdmin role on /, or PVEVMAdmin on /vms if you want to limit scope.
To assign roles: Datacenter > Permissions > Add > API Token Permission.
Yes. You can add multiple Proxmox servers in Settings and the dashboard aggregates data from all of them. Each server entry has its own host, token, and label.
If your nodes are in a cluster, you only need to add one node since the API returns data for all nodes in the cluster.
The host should be your Portainer URL without a trailing slash, e.g. http://192.168.1.73:9000
The slug is the short name at the end of your status page URL.
http://your-host:3001/status/defaultdefault in that exampleEnter the slug in Settings. CtrlFreak uses the public status page API, so no login credentials are needed for Uptime Kuma.
CtrlFreak connects to iDRAC8 via the Redfish API using Basic authentication. Enter the iDRAC IP address, your username, and password in Settings.
The most common cause is the TLS protocol setting. iDRAC8 defaults to TLS 1.0 in some firmware versions and the app requires TLS 1.2.
Fix: iDRAC web UI > iDRAC Settings > Services > Web Server > TLS Protocol: TLS 1.2 and Higher.
Other things to check:
The host should be the URL to your Pi-hole admin panel, e.g. http://192.168.1.100
tskey-api-)Your tailnet name is visible in the Tailscale admin console URL and on the DNS settings page.
It is either your organization name (e.g. example.com) or the email domain you signed up with (e.g. gmail.com becomes youremail.gmail.com.beta.tailscale.net).
The easiest way: go to admin console > DNS and your tailnet name is shown at the top under Tailnet name.
The host should be your Unraid server IP or hostname, e.g. http://192.168.1.52
CtrlFreak connects to Synology DSM using your admin username and password. The app authenticates via the Synology WebAPI and caches the session for 20 minutes per device.
The host should include the DSM port. Synology defaults to port 5000 for HTTP and port 5001 for HTTPS, e.g. http://192.168.1.54:5000 or https://192.168.1.54:5001
admin account or create a separate user with limited permissions. For read-only access, the user needs the Monitoring and Storage Manager read permissions.The Synology screen shows:
Yes. You can add multiple Synology servers in Settings. The screen shows a tab picker at the top when more than one device is configured.
CtrlFreak connects using your NPM admin email and password. It authenticates via the NPM API and caches the session token for 23 hours.
The host should be your NPM instance including the port, e.g. http://192.168.1.73:81
NPM defaults to port 81 for the admin interface.
CtrlFreak uses API token authentication. In the PBS web UI, go to Configuration > Access > API Tokens and create a token for a user that has Datastore.Audit permissions.
The token format is: user@realm!tokenname=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
The host should include the port, e.g. https://192.168.1.38:8007
CtrlFreak connects using your Dockge admin username and password. Dockge defaults to port 5001, so the host should be: http://192.168.1.73:5001
The app authenticates and caches the session token automatically. If the token expires, it re-authenticates on the next request.
CtrlFreak connects to Beszel using your account email address and password. Beszel defaults to port 8090, so the host should be: http://192.168.1.73:8090
The app uses the PocketBase authentication API that Beszel is built on.
CtrlFreak connects to HP iLO 4 and iLO 5 via the Redfish API using Basic authentication. Enter the iLO IP address, your username (default is Administrator), and password in Settings.
The host should be the iLO management IP, e.g. https://192.168.1.51
CtrlFreak connects using your AdGuard Home admin username and password. The default port is 3000, so the host should be: http://192.168.1.53:3000
If you have changed AdGuard's port in its settings, use that port instead.
The host should be your OPNsense LAN IP, e.g. https://192.168.1.1
In TrueNAS SCALE: go to Credentials > API Keys and click Add. Give it a name and copy the key.
In TrueNAS CORE: go to Accounts > Users, edit your admin user, and look for API Keys at the bottom of the page.
The host should be your NAS IP, e.g. http://192.168.1.52
Yes. CtrlFreak accepts self-signed and untrusted SSL certificates by design. Homelab servers commonly run with self-signed certs and the app is built to connect to them directly without requiring a trusted CA chain.
A per-server SSL verification toggle is on the roadmap for users who want stricter control.
The SSL Health screen (found in the Network Tools section) checks whether each of your configured servers is reachable over HTTPS. It shows a green dot and latency for hosts that respond, and a red dot for hosts that are unreachable or timing out.
It does not validate certificate chains. It only checks reachability.
Yes. You can enter HTTP addresses for any integration. There is no requirement to use HTTPS, though it is recommended where possible.
iDRAC is an exception: it only supports HTTPS connections via the Redfish API.