--- title: "Installation" slug: "nucleus-agent-installation" updated: 2025-09-30T19:49:42Z published: 2025-09-30T19:49:42Z canonical: "help.nucleussec.com/nucleus-agent-installation" --- > ## Documentation Index > Fetch the complete documentation index at: https://help.nucleussec.com/llms.txt > Use this file to discover all available pages before exploring further. # Installation ## System requirements Centos7 or RHEL7 are the officially supported OSes. We have some deviations for Debian/Ubuntu shown below, but they may not be comprehensive. | Requirement | Details | | --- | --- | | Operating Systems | RedHat/Centos 7+ (officially supported), Debian, Ubuntu (experimental) | | CPU | 1 Core | | Memory | 4 GB RAM | | Storage | 20 GB | | Firewall | Open port 2222 outbound from the server you are installing the Nucleus agent on to the Nucleus Manager FQDN that will be provided by the Nucleus support team. | | Misc | root access (or full sudo privileges) on the machine you are installing the Nucleus agent on. This procedure assumes you are logged in as the root user. | ## Installation Step 1 Before proceeding please [submit a support request](https://nucleussec.atlassian.net/servicedesk/customer/portal/3/group/11/create/33). Our Nucleus Support team will ensure you have all the proper information for a successful Nucleus Agent install! You will be provided with the following information by Nucleus Support: The FQDN of the Nucleus Manager for your instance (referred to as in this procedure) Note Your firewall must be configured to allow outbound access from the server you are installing the Nucleus agent on to this FQDN. Your Nucleus Agent username for authentication (referred to as in this procedure) Warning The Nucleus Agent uses key based authentication. We will never ask for an account password or the private key. A list of ports assigned to your organization. Each internal tool that Nucleus will be connecting to will use one of these assigned ports. (referred to as in this procedure). Note If you are connecting to more internal tools than assigned ports, contact Nucleus support for additional ports. Once you have the above information, proceed to the next section. ## Install Dependencies ``` # For CentOS/RHEL 7+ yum install -y epel-release yum install -y supervisor autossh systemctl enable supervisord systemctl start supervisord ``` ``` # For Debian/Ubuntu apt-get install supervisor autossh systemctl enable supervisor systemctl start supervisor ``` ``` # Create service account sudo adduser ``` ``` # Setup SSH keys for authentication mkdir /home//.ssh ssh-keygen -t rsa -b 4096 -C Enter the file in which to save the key: /home//.ssh/id_rsa Enter the passphrase: Enter the same passphrase again: ``` ``` # Set up Permissions on your new key chmod 700 /home//.ssh chown -R : /home//.ssh cat /home//.ssh/id_rsa.pub Note: Copy this output and send to your Nucleus support rep or to support@nucleussec.com ``` Stop Here Send your public key file to your Nucleus support representative before continuing ## Install & Configure the Nucleus Agent ### 1. Create Supervisord File ``` You will need to complete this step to create a supervisord configuration file for each internal tool you wish to make accessible to Nucleus. Replace with the name of the internal tool you are connecting to (e.g. Nessus, Jira, etc.). ``` - For RHEL/CentOS systems, create a new file /etc/supervisord.d/.ini - For Debian/Ubuntu systems, create a new file /etc/supervisor/conf.d/.conf Note The new file should contain the following contents, with all fields inside of "< >" being replaced with custom values for your configuration. ``` [program:] command=/usr/bin/autossh -M 0 -N -R *::: @ -p 2222 -i /home//.ssh/id_rsa -o "ServerAliveInterval 30" -o "ServerAliveCountMax 3" -o "StrictHostKeyChecking=no" user= ``` #### Description of fields ``` : The name of the internal tool you are connecting to (e.g. Nessus, Jira, etc.) : One unused port from the range of ports that Nucleus assigned to your organization. If you need more ports, reach out to your Nucleus support representative. : The internal IP of the internal tool/application that you would like to expose to Nucleus. If you are installing the Nucleus agent on the server that runs the internal tool, use 127.0.0.1 : This is the port that the internal tool/application listens on. For example, Nessus Professional listens on port 8834 by default. - this is the FQDN of the Nucleus Manager given to you by Nucleus support. ``` #### Example file We are connecting an internal Rapid7 InsightVM console - The name of the internal tool we are connecting to is: insightvm - The assigned Nucleus port is: 1234 - The internal IP of the Rapid7 InsightVM console is: 192.168.1.140 - The InsightVM console is listening on port: 3780 - The username provided by support was acme-nucleusagent - The Nucleus Manager FQDN provided by support was: nucleus-mgr.nucleussec.com - The example file would be as listed ``` [program:insightvm] command=/usr/bin/autossh -M 0 -N -R *:1234:192.168.1.140:3780 acme-nucleusagent@nucleus-mgr.nucleussec.com -p 2222 -i /home/acme-nucleusagent/.ssh/id_rsa -o "ServerAliveInterval 30" -o "ServerAliveCountMax 3" -o "StrictHostKeyChecking=no" user=acme-nucleusagent ``` ### 2. Start the service ``` # For CentOS/RHEL 7+ systemctl stop supervisord systemctl start supervisord # For Debian/Ubuntu systemctl stop supervisor systemctl start supervisor ``` If you get errors during this part, please check your config file against the config file above: Example File and refer to the troubleshooting steps at the bottom of this article: Troubleshooting Checklist ### 3. Verify that the agent is running successfully ``` # supervisorctl status RUNNING pid 23198, uptime 0:12:48 ``` If the service is not starting correctly, please refer to the Troubleshooting Checklist below or contact Nucleus support. If you need any assistance, we're always close at support@nucleussec.com ## Next Steps Now that you've set up Nucleus Agent, it's time to set up a Connector through the agent. [Here's how](/v1/docs/nucleus-agent-usage). ## Troubleshooting Checklist If you are having issues with the connection, here's a checklist to attempt: | Check | Result | Solution | | --- | --- | --- | | From the machine where you installed the Nucleus agent, ensure you can reach the destination: Use something like curl, telnet or wget to ensure you can reach the destination server on that port | You should see something back from the web server | If there is connection denied or any other message that is not a web response, check your internal firewall and routing to open the connection | | From the machine where you installed the Nucleus agent, ensure you can reach the Nucleus manager in your region: Use "ssh -v username@nucleus manager fqdn -p 2222" | The connection should show an SSH error like "permission denied (publickey)" | If you are not getting an SSH error, there is most likely something blocking your outbound connections to the Nucleus manager. Please open the OUTGOING port 2222 from the machine where the Nucleus agent is installed to the Nucleus manager. | | From the machine where you installed the Nucleus agent, ensure you can log in to the Nucleus manager in your region: Use "ssh username@nucleus manager fqdn -p 2222 -i " | You should get an error like: "PTY allocation request failed on channel 0 This account can only be used for tunnels". That is correct, that means you can log in | If you are unable to login, please verify the firewall settings in the previous step, then contact support for verification of your credentials | | If the above steps pass, check your connection from Nucleus to the Nucleus manager: From within Nucleus set up a connector using the Nucleus manager's URL as the URL with the port you have mapped. E.g. within Nucleus you would use: "https://nucleus-manager.nucleussec.com:1995" if the port assigned to you is 1995. | Verify connection should not time out | If you are getting a credential error: the tunnel is set up and credential verification is required. | If the connection is timing out, please check the above steps then contact Nucleus support at support@nucleussec.com for assistance.