Text of learn.netdata.cloud › docs › netdata-cloud › connect-agent as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

Connect Agent to Cloud | Netdata Cloud | Learn Netdata

Skip to main content This section guides you through installing and securely connecting a new Agent to Netdata Cloud via the encrypted Agent-Cloud Link ( ACLK ). Connecting your Agent to your Space unlocks centralized monitoring, easier collaboration, and more. Quick Start - New Installation ​ For new installations , Netdata Cloud generates a command that you can execute on your Node to install and connect the Agent to your Space.

You can find this command in three places in the UI: Space/Room settings : Click the cogwheel (the bottom-left corner or next to the Room name at the top) and select "Nodes." Click the "+" button to add a new node. Nodes tab : Click on the "Add nodes" button. Integrations page : From the "Deploy" groups of integrations, select the OS or container environment your node runs on, and follow the instructions. Connect Existing Agent ​ For Agents already installed , you can connect them to your Space using one of three methods: Method 1: Via UI (Recommended) ​ Best for: Most users, easiest setup Open your Agent's local dashboard (normally under IP:19999 ) Sign in to your Netdata Cloud account Click the "Connect" button Follow the on-screen instructions to connect your Agent note Verifying node ownership: As part of the connection flow, your Agent's local dashboard displays a command to run directly on the machine whose Agent you are connecting — not on your local workstation or any other machine.

The command reads a random session ID (a UUID) that the Agent generates at startup and writes to its library directory ( /var/lib/netdata/ by default, following the lib option under the [directories] section of netdata.conf ). Copy the output and paste it back into the dialog. This proves you have administrative access to the node and prevents unauthorized claiming of machines you do not control. If your pasted UUID is rejected with invalid key , it is single-use: every claim attempt that presents the correct key regenerates a new one, including failed submissions.

A request with a wrong key does not regenerate it. See Pasted verification UUID rejected as invalid key . Method 2: Via Configuration File ​ Best for: Automated deployments, multiple Agents Create /INSTALL_PREFIX/etc/netdata/claim.conf : [global] url = https://app.netdata.cloud token = NETDATA_CLOUD_SPACE_TOKEN rooms = ROOM_KEY1,ROOM_KEY2,ROOM_KEY3 proxy = http://username:password@myproxy:8080 insecure = no info File Permissions and Ownership: The claim.conf file contains sensitive claiming tokens and must be properly secured: Required permissions (service installs): 0640 (owner read/write, group read, no world access) Required ownership (service installs): root:netdata (owner root, group netdata) The Netdata Cloud-generated claiming command automatically sets these permissions when creating or updating claim.conf .

If you create the file manually, ensure it follows these same security standards to prevent unauthorized access to your claiming tokens. note On macOS with Homebrew installs, the netdata group does not exist. Set ownership to your own user and the staff group instead: chown $(whoami):staff /usr/local/etc/netdata/claim.conf # Intel chown $(whoami):staff /opt/homebrew/etc/netdata/claim.conf # Apple Silicon chmod 0600 /usr/local/etc/netdata/claim.conf # Intel chmod 0600 /opt/homebrew/etc/netdata/claim.conf # Apple Silicon This prevents the chown: netdata: illegal group name error.

Using 0600 is acceptable for Homebrew installs because the Netdata Agent runs under the same user that owns the file. Configuration Options: option description required url The Netdata Cloud base URL (defaults to https://app.netdata.cloud ) no token The claiming token for your Netdata Cloud Space yes rooms A comma-separated list of Rooms that the Agent will be added to no proxy See proxy configuration below no insecure A boolean (either yes , or no ) and when set to yes it disables host verification. no Applying the Configuration: If the Agent is already running, you can either run netdatacli reload-claiming-state or restart the Agent .

Otherwise, the Agent connects when it starts. Method 3: Via Environment Variables ​ Best for: Container deployments, CI/CD pipelines You can configure Netdata using the following environment variables: Option Description Required NETDATA_CLAIM_URL The Netdata Cloud base URL (defaults to https://app.netdata.cloud ) no NETDATA_CLAIM_TOKEN The claiming token for your Netdata Cloud Space yes NETDATA_CLAIM_ROOMS A comma-separated list of Rooms that the Agent will be added to no NETDATA_CLAIM_PROXY The URL of a proxy server to use for the connection no NETDATA_EXTRA_CLAIM_OPTS May contain a space-separated list of options.

The option -insecure is the only currently used. no Connection Troubleshooting ​ If the connection process fails, you can find the reason in daemon.log (search for "CLAIM") and the cloud section of http://ip:19999/api/v3/info . Advanced Configuration ​ Proxy Configuration ​ You can configure proxy settings for both the configuration file and environment variable methods. For Configuration File (claim.conf) ​ You can set the proxy option at the [global] section in claim.conf to: empty, to disable proxy configuration none to disable proxy configuration env to use the environment variable http_proxy (this is the default) http://[user:pass@]host:port , to connect via a web proxy socks5[h]://[user:pass@]host:port , to connect via a SOCKS5 proxy Environment Variable Proxy Settings ​ Netdata uses the http_proxy environment variable only when you set the proxy option to env (which is the default).

You can set the http_proxy environment variable to: http://[user:pass@]host:port , to connect via an HTTP proxy socks5[h]://[user:pass@]host:port , to connect via a SOCKS5 or SOCKS5H proxy Proxy Security Considerations ​ note Netdata does not support secure connections to proxies. Data between Netdata Agents and Netdata Cloud remains end-to-end encrypted since the Agent establishes a TCP tunnel through the proxy (HTTP CONNECT for HTTP proxies, SOCKS5 CONNECT for SOCKS proxies) and handles all encryption directly, however initial Agent-to-proxy communication is not encrypted.

How End-to-End Encryption Works with Proxies: Proxy Connection : The Agent connects to the configured proxy using a plain TCP connection. TCP Tunneling Request : The Agent asks the proxy to establish a TCP tunnel to the Netdata Cloud server (HTTP CONNECT for HTTP proxy, SOCKS5 CONNECT for SOCKS5/SOCKS5H). Proxy Tunneling : Once accepted, the proxy forwards raw TCP data in both directions without interpreting application-layer traffic.

Encrypted Communication : The Agent then establishes a TLS/SSL connection through this tunnel directly with the Netdata Cloud server. All subsequent data (including the WebSocket handshake and MQTT protocol data) is encrypted end-to-end. note The proxy only sees encrypted TLS traffic flowing through the tunnel it established, never the decrypted content. info Netdata uses two connection libraries : libcurl for claiming and MQTToWSoHTTPS for the actual Cloud connection .

While libcurl supports encrypted proxy connections, MQTToWSoHTTPS does not - so encrypted proxy connections will fail during the Cloud connection phase. The proxy configuration patterns above work for both libraries and provide end-to-end encryption for Netdata Cloud communication. For SOCKS proxies: socks5:// resolves target hostnames locally on the Agent and sends IP to the proxy. socks5h:// sends hostname to the proxy and resolves DNS remotely on the proxy side.

Manage Connections ​ Reconnect Agent ​ Linux-based Installations To remove a node from your Space in Netdata Cloud, delete the cloud.d/ directory in your Netdata library directory. cd /var/lib/netdata # Replace with your Netdata library directory, if not /var/lib/netdata/ sudo rm -rf cloud.d/ note The Agent will be re-claimed automatically if the environment variables or claim.conf exist when you restart

The rest of this page is on the live site.