---
title: NopSec Virtual Appliance Setup Guide
description: How to setup the NopSec virtual appliance for on-prem integrations
---

[Skip to content](https://support.nopsec.com/knowledge/virtual-appliance-setup-guide#main-content)

English

Show submenu for translations

![nopsec-full-logo-white.png\]](https://support.nopsec.com/hs-fs/hubfs/Images/Logos/NopSec%20Logos/nopsec-full-logo-white.png?height=40&name=nopsec-full-logo-white.png)

Open main navigation

Close main navigation

- English
  
  Show submenu for translations
- [NopSec.com](https://www.nopsec.com/)

[NopSec.com](https://www.nopsec.com/)

 Welcome to the NopSec Knowledge Base. Start your search below.

- There are no suggestions because the search field is empty.

1. [Knowledge Base](https://support.nopsec.com/knowledge?hsLang=en)
2. [Implementation/Admin Learning Path](https://support.nopsec.com/knowledge/implementation-admin-learning-path?hsLang=en)

# NopSec Virtual Appliance Setup Guide

## How to setup the NopSec virtual appliance for on-prem integrations

### Overview

The NopSec Virtual Appliance lets NopSec work with security tools that run inside your network, without opening any inbound firewall ports.

It is a small Docker container you run on a Linux host in your environment. It makes outbound HTTPS connections only: it checks in with NopSec for work, talks to your on-premise tool, and sends the results back. NopSec never connects into your network.

You need a Virtual Appliance when an integration you use with NopSec is hosted on-premise and can't be reached directly from the internet.

- **No inbound firewall changes.** All connections start from the appliance.
- **Credentials stay protected.** Keys are generated for each appliance. Storage credentials are sent encrypted and only decrypted in memory.
- **Runs anywhere Docker runs.** Use the included setup scripts on RedHat- or Debian-based Linux, or start it with Docker Compose.
- **Status at a glance.** The NopSec platform shows whether each appliance is connected and which version it runs.

### Requirements

You need a Linux host inside your network that can reach your on-premise tool and make outbound HTTPS connections.

| Requirement | Details |
| --- | --- |
| Operating system | RedHat-based (RHEL, CentOS, Rocky) or Debian-based (Debian, Ubuntu) Linux |
| Software | Docker v28 or v29\* with Docker Compose V2. The included script can install Docker for you. unzip to extract the bundle. |
| Access | A user with sudo rights to create the dedicated clientuser account |
| Outbound network | HTTPS (port 443) to the NopSec Tunnel Server and to Amazon S3 (AWS us-east-2), where scan results are uploaded |
| Internal network | Access to the on-premise tool you are connecting to NopSec |
| Proxy (optional) | If the host reaches the internet through a proxy: proxy host, port, username and password |
| NopSec platform | A user who can view and edit Settings |

Ask NopSec Support for the Tunnel Server hostname and IP addresses to add to your firewall allow list.

\* The Virtual Appliance has been tested against Docker engine versions 28 and 29. If you need support for an older engine version, contact NopSec support.

#### Step 1: Create the appliance in NopSec

Creating an appliance gives you a setup bundle that is already configured for your account.

1. In the NopSec platform, go to **Settings \> Virtual Appliances**.
2. Click **Add new Virtual Appliance**.
3. Enter an **Appliance Name** (for example, the site or data center it will run in) and confirm. Names must be unique in your account.
4. The new appliance appears in the list with the status **Waiting for initial connection**.
5. On the appliance, download both files: 
     - **Download Docker file**: the Virtual Appliance software image (a .zip file).
     - **Download Docker compose file**: your setup bundle (scripts.zip), with your appliance's connection settings already filled in.

The setup bundle contains your appliance's unique keys. Store it securely, and copy it only to the host where the appliance will run.

#### Step 2: Link the appliance to an integration

Tell NopSec which integration should reach your tool through this appliance.

1. Go to **Integrations** and open the on-premise integration (or add a new one).
2. On the **Credentials** tab, turn on **Use Virtual Appliance**.
3. In **Virtual Appliance**, pick the appliance you created and save.

The **Use Virtual Appliance** option only appears for integration types that support on-premise deployment.

#### Step 3: Install the appliance on your host

Copy both downloaded files to the Linux host, then follow these steps. They take about 10 minutes.

1. **Create a dedicated user.** As root, run:
   
   ```
   adduser clientuser groupadd -f docker usermod -aG sudo,docker clientuser su - clientuser cd /home/clientuser
   ```
2. **Extract the setup bundle.**
   
   Install unzip first if needed (apt install unzip on Debian/Ubuntu, yum install unzip on RHEL/CentOS).
   
   ```
   unzip scripts.zip sudo chown -R clientuser:clientuser scripts/ chmod +x ./scripts/*.sh
   ```
3. **Load the software image.** Unzip the downloaded image file, then load the .tar file it contains into Docker:
   
   ```
   unzip nopsectunnelclient-<version>.zip docker load -i nopsectunnelclient-<version>.tar
   ```
4. **Add proxy settings (only if you use a proxy).** Edit scripts/appliance.env and fill in PROXY\_HOST, PROXY\_PORT, PROXY\_USERNAME and PROXY\_PASSWORD. Leave the other values unchanged.
5. **Run setup.**
   
   ```
   ./scripts/1-setup.sh
   ```
   
   If setup reports that Docker isn't installed, run ./scripts/2-install-docker.sh, log out and back in, then run ./scripts/1-setup.sh again. Setup is safe to run more than once.
6. **Check that it's running.**
   
   ```
   ./scripts/3-verify.sh
   ```
   
   This shows the container status and its most recent log lines.
7. If you change appliance.env later (for example, to add a proxy), run
   
   ```
   ./scripts/1-setup.sh
   ```
   
   again to apply the change.

#### Step 4: Confirm the connection

Within a few minutes of setup, the appliance's status in **Settings \> Virtual Appliances** should change to **Connected**.

| Status | What it means |
| --- | --- |
| Waiting for initial connection | The appliance was created but has never checked in. Setup hasn't run yet, or it can't reach NopSec. |
| Connected | The appliance checked in within the last 5 minutes. |
| Not connected | The appliance has checked in before, but not in the last 5 minutes. The row shows when it was last seen. |
| Disabled | The appliance was turned off in NopSec. |

Each appliance also shows the **version** it is running. If a newer version is available, you'll see: "A new version is available. Please download and install the updated setup."

Once the appliance is connected, contact your NopSec Customer Success Manager to set up the recurring jobs for the linked integration. Installing the appliance does not start them automatically.

### Managing your appliances

All management happens on **Settings \> Virtual Appliances**, except updating and uninstalling, which you also do on the host.

- **Disable or enable:** use the toggle on the appliance. A disabled appliance shows as **Disabled** and stays listed, so you can turn it back on later.
- **Update to a new version:** click **Download Docker file**, copy it to the host, and load it as in Step 3 (unzip, then docker load). Then run ./scripts/1-setup.sh again. The version shown in NopSec updates after the appliance next checks in.
- **Delete:** click the delete icon and confirm **Delete Appliance**. This can't be undone. Any integration using the appliance can no longer reach your tool.
- **Uninstall from the host:** deleting in NopSec does not stop the container. On the host, run:

```
cd /home/clientuser/tunnelclient docker compose down
```

You can run several appliances, for example one per site or network segment. Create each one separately so each gets its own keys.

### Security

The appliance is designed so that you never have to open your network to NopSec.

- **Outbound only.** The appliance starts every connection over HTTPS. It accepts no inbound connections from the internet.
- **Unique keys for each appliance.** Each appliance gets its own API key and encryption key when it is created. NopSec stores only a hashed copy of the API key.
- **Encrypted credentials.** The storage credentials used to upload results are not kept on the host. They arrive encrypted with each job and are decrypted only in memory.
- **Locked-down container.** The container runs with a read-only file system, under a dedicated non-root user. Its settings file is readable only by that user.
- **You stay in control.** Disable or delete the appliance in NopSec, or stop the container on your host, at any time.

### Troubleshooting

Most problems come from Docker setup or a blocked outbound connection. Run

```
 ./scripts/3-verify.sh 
```

first: its log lines usually point to the cause.

| Problem | What to do |
| --- | --- |
| Setup reports Docker is not installed | Run ./scripts/2-install-docker.sh, log out and back in, then run ./scripts/1-setup.sh again. |
| Setup reports the image isn't loaded | Unzip the downloaded Docker file and run docker load -i on the .tar inside it, then run setup again. |
| Setup reports a required value is missing from appliance.env | The bundle was edited or is incomplete. Download **Download Docker compose file** again from NopSec and use the fresh copy. |
| permission denied when running Docker | Your session doesn't have the docker group yet. Log out and back in as clientuser. |
| Status stays **Waiting for initial connection** | Check that the container is running (3-verify.sh), that outbound HTTPS to the NopSec Tunnel Server is allowed, and that proxy settings are correct if you use a proxy. |
| Status changes to **Not connected** | The host, container or network went down. Check the host is up, run 3-verify.sh, and run 1-setup.sh again to restart the container. |
| Results don't arrive after a job runs | Check that outbound HTTPS to Amazon S3 (us-east-2) is allowed, including through your proxy. |
| The setup bundle was lost or shared by mistake | Delete the appliance in NopSec and create a new one. Each new appliance gets new keys. |

### FAQ

**Does NopSec need inbound access to my network?** No. The appliance only makes outbound HTTPS connections.

**Can I run it without the setup scripts?** Yes. If you already use Docker, load the image, then run docker compose up -d from the extracted scripts folder. The scripts are the recommended path because they check your configuration first.

**How many appliances can I create?** As many as you need. Use one for each network segment or site the appliance must reach.

**Where can I get help?** Contact NopSec Support or your Customer Success Manager. Include the appliance name and the output of ./scripts/3-verify.sh.

- [NopSec Platform 101](https://support.nopsec.com/knowledge/nopsec-platform-101?hsLang=en)
- [Implementation/Admin Learning Path](https://support.nopsec.com/knowledge/implementation-admin-learning-path?hsLang=en)
- [Analyst/Remediator Learning Path](https://support.nopsec.com/knowledge/analyst-remediator-learning-path?hsLang=en#main-content)

    - [Reporting](https://support.nopsec.com/knowledge/analyst-remediator-learning-path?hsLang=en#reporting)
    - [Workflow (Remediation/Exception)](https://support.nopsec.com/knowledge/analyst-remediator-learning-path?hsLang=en#workflow-remediation-exception)
    - [Insights](https://support.nopsec.com/knowledge/analyst-remediator-learning-path?hsLang=en#insights)
    - [Asset Management](https://support.nopsec.com/knowledge/analyst-remediator-learning-path?hsLang=en#asset-management)
- [New Features](https://support.nopsec.com/knowledge/new-features?hsLang=en)
- [Training Videos](https://support.nopsec.com/knowledge/training-videos?hsLang=en)
- [Release Notes](https://support.nopsec.com/knowledge/release-notes?hsLang=en)

[![Chill listening crop-3](https://support.nopsec.com/hs-fs/hubfs/Images/Logos/NopSec-logo-160x160.png?width=24&height=24&name=NopSec-logo-160x160.png "Chill listening crop-3")](https://www.nopsec.com)

NopSec Knowledge Base

Copyright © 2026, NopSec