| 1 | # Install Netdata on macOS |
| 2 | |
| 3 | You can install Netdata in one of the three following ways: |
| 4 | |
| 5 | - **[Install Netdata with the automatic one-line installation script (recommended)](#install-netdata-with-our-automatic-one-line-installation-script)**, |
| 6 | - [Install Netdata via Homebrew](#install-netdata-via-homebrew) |
| 7 | - [Install Netdata from source](#install-netdata-from-source) |
| 8 | |
| 9 | Each of these installation option requires [Homebrew](https://brew.sh/) for handling dependencies. |
| 10 | |
| 11 | :::info |
| 12 | |
| 13 | The Netdata Homebrew package is community-created and -maintained. |
| 14 | |
| 15 | ::: |
| 16 | |
| 17 | :::note |
| 18 | |
| 19 | Community-maintained packages _may_ receive support from Netdata, but are only a best-effort affair. Learn more about [Netdata's platform support policy](/packaging/PLATFORM_SUPPORT.md). |
| 20 | |
| 21 | ::: |
| 22 | |
| 23 | ## Install Netdata with our automatic one-line installation script |
| 24 | |
| 25 | ### Local Netdata Agent installation |
| 26 | |
| 27 | To install Netdata using our automatic [kickstart](/packaging/installer/methods/kickstart.md) open a new terminal and run: |
| 28 | |
| 29 | ```bash |
| 30 | curl https://get.netdata.cloud/kickstart.sh > /tmp/netdata-kickstart.sh && sh /tmp/netdata-kickstart.sh |
| 31 | ``` |
| 32 | |
| 33 | The Netdata Agent is installed under `/usr/local/netdata`. Dependencies are handled via Homebrew. |
| 34 | |
| 35 | ### Automatically connect to Netdata Cloud during installation |
| 36 | |
| 37 | The `kickstart.sh` script accepts additional parameters to automatically [connect](/src/claim/README.md) your node to Netdata |
| 38 | Cloud immediately after installation. Find the `token` and `rooms` strings by [signing in to Netdata |
| 39 | Cloud](https://app.netdata.cloud/sign-in?cloudRoute=/spaces), then clicking on **Connect Nodes** on any of the prompts from the UI. |
| 40 | |
| 41 | - `--claim-token`: Specify a unique claiming token associated with your Space in Netdata Cloud to be used to connect to the node |
| 42 | after the install. |
| 43 | - `--claim-rooms`: Specify a comma-separated list of tokens for each Room this node should appear in. |
| 44 | - `--claim-proxy`: Specify a proxy to use when connecting to the Cloud in the form of `http://[user:pass@]host:ip` for an HTTP(S) proxy. |
| 45 | See [connecting through a proxy](/src/claim/README.md#proxy-configuration) for details. |
| 46 | - `--claim-url`: Specify a URL to use when connecting to the Cloud. Defaults to `https://app.netdata.cloud`. |
| 47 | |
| 48 | For example: |
| 49 | |
| 50 | ```bash |
| 51 | curl https://get.netdata.cloud/kickstart.sh > /tmp/netdata-kickstart.sh && sh /tmp/netdata-kickstart.sh --install-prefix /usr/local/ --claim-token TOKEN --claim-rooms ROOM1,ROOM2 --claim-url https://app.netdata.cloud |
| 52 | ``` |
| 53 | |
| 54 | The Netdata Agent is installed under `/usr/local/netdata` on your machine. Your machine will also show up as a node in your Netdata Cloud. |
| 55 | |
| 56 | If you experience issues while connecting your node, follow the steps in our [Troubleshoot](/src/claim/README.md#troubleshooting) documentation. |
| 57 | |
| 58 | ## Install Netdata via Homebrew |
| 59 | |
| 60 | To connect this Agent to Netdata Cloud, see [Connect a Homebrew-installed Agent to Netdata Cloud](#connect-a-homebrew-installed-agent-to-netdata-cloud) below. |
| 61 | |
| 62 | ### For macOS Intel |
| 63 | |
| 64 | To install Netdata and all its dependencies, run Homebrew using the following command: |
| 65 | |
| 66 | ```sh |
| 67 | brew install netdata |
| 68 | ``` |
| 69 | |
| 70 | Homebrew will place your Netdata configuration directory at `/usr/local/etc/netdata/`. |
| 71 | |
| 72 | Use the `edit-config` script and the files in this directory to configure Netdata. For reference, you can find stock configuration files at `/usr/local/Cellar/netdata/{NETDATA_VERSION}/lib/netdata/conf.d/`. |
| 73 | |
| 74 | ### For Apple Silicon |
| 75 | |
| 76 | To install Netdata and all its dependencies, run Homebrew using the following command: |
| 77 | |
| 78 | ```sh |
| 79 | brew install netdata |
| 80 | ``` |
| 81 | |
| 82 | Homebrew will place your Netdata configuration directory at `/opt/homebrew/etc/netdata/`. |
| 83 | |
| 84 | Use the `edit-config` script and the files in this directory to configure Netdata. For reference, you can find stock configuration files at `/opt/homebrew/Cellar/netdata/{NETDATA_VERSION}/lib/netdata/conf.d/`. |
| 85 | |
| 86 | ### Connect a Homebrew-installed Agent to Netdata Cloud |
| 87 | |
| 88 | The easiest way to connect a Homebrew-installed Netdata Agent to Netdata Cloud is via the local dashboard UI, as described in [Method 1: Via UI](/src/claim/README.md#method-1-via-ui-recommended): |
| 89 | |
| 90 | 1. Open the local dashboard in your browser at `http://localhost:19999` (or the Agent's IP address at port 19999). |
| 91 | 2. Sign in to your Netdata Cloud account. |
| 92 | 3. Click the **Connect** button and follow the on-screen instructions. |
| 93 | |
| 94 | For automated setups or headless machines where the UI is not accessible, you can use one of these alternatives: |
| 95 | |
| 96 | - **Kickstart script claiming flags** — this requires installing/reinstalling with kickstart (it installs under `/usr/local/netdata` by default, or your `--install-prefix` path) rather than adding flags to an existing Homebrew install. If you want to keep the Homebrew install, use the **Configuration file** method below. See the [kickstart claiming section](#automatically-connect-to-netdata-cloud-during-installation) above or the full [kickstart documentation](/packaging/installer/methods/kickstart.md). |
| 97 | - **Configuration file** — create a `claim.conf` file in your Netdata configuration directory using the [configuration file method](/src/claim/README.md#method-2-via-configuration-file). |
| 98 | |
| 99 | **Configuration directory paths for `claim.conf`:** |
| 100 | |
| 101 | | Architecture | Path | |
| 102 | |:--------------|:---------------------------------------| |
| 103 | | Intel | `/usr/local/etc/netdata/claim.conf` | |
| 104 | | Apple Silicon | `/opt/homebrew/etc/netdata/claim.conf` | |
| 105 | |
| 106 | :::note |
| 107 | |
| 108 | On macOS, Homebrew installs run under your user account and the `netdata` group does not exist. Use your own user and the `staff` group for file ownership when creating `claim.conf` manually. For full details on permissions and applying the configuration, see the [configuration file method](/src/claim/README.md#method-2-via-configuration-file). |
| 109 | |
| 110 | ::: |
| 111 | |
| 112 | :::caution |
| 113 | |
| 114 | Do **not** run the `netdata-claim.sh` script manually. It is deprecated and will be unsupported in the near future. Instead, use one of the supported claiming methods described above: the Cloud UI, kickstart claiming flags during install/reinstall, or a `claim.conf` file. |
| 115 | |
| 116 | ::: |
| 117 | |
| 118 | For the full list of claiming options and troubleshooting, see [Connect Agent to Cloud](/src/claim/README.md). |
| 119 | |
| 120 | ## Install Netdata from source |
| 121 | |
| 122 | We don't recommend installing Netdata from source on macOS, as it can be difficult to configure and install dependencies manually. |
| 123 | |
| 124 | 1. Open your terminal of choice and install the Xcode development packages: |
| 125 | |
| 126 | ```bash |
| 127 | xcode-select --install |
| 128 | ``` |
| 129 | |
| 130 | 2. Click **Install** on the Software Update popup window that appears. |
| 131 | 3. Use the same terminal session to install some of Netdata's prerequisites using Homebrew. If you don't want to use [Netdata Cloud](/docs/netdata-cloud/README.md), you can omit `cmake`. |
| 132 | |
| 133 | ```bash |
| 134 | brew install ossp-uuid autoconf automake pkg-config libuv lz4 json-c openssl libtool cmake |
| 135 | ``` |
| 136 | |
| 137 | 4. Download Netdata from our GitHub repository: |
| 138 | |
| 139 | ```bash |
| 140 | git clone https://github.com/netdata/netdata.git --recursive |
| 141 | ``` |
| 142 | |
| 143 | 5. `cd` into the newly-created directory and then start the installer script: |
| 144 | |
| 145 | ```bash |
| 146 | cd netdata/ |
| 147 | sudo ./netdata-installer.sh --install-prefix /usr/local |
| 148 | ``` |
| 149 | |
| 150 | :::info |
| 151 | |
| 152 | - Your Netdata configuration directory will be at `/usr/local/netdata/`. |
| 153 | - Your stock configuration directory will be at `/usr/local/lib/netdata/conf.d/`. |
| 154 | - The installer will also install a startup plist to start Netdata when your macOS system boots. |
| 155 | |
| 156 | ::: |
| 157 | |
| 158 | Netdata works on macOS, albeit with some limitations. |
| 159 | |
| 160 | - The number of charts displaying system metrics is limited, but you can use any of Netdata's [external plugins](/src/plugins.d/README.md) to monitor any services you might have installed on your macOS system. |
| 161 | - You could also use a macOS system as the parent node in a [streaming configuration](/src/streaming/README.md). |