Connect your computer

A website cannot see your network traffic, so ShadowSense AI uses a small agent that runs on your computer. It reads connection metadata only (IP addresses, ports, byte and packet counts) and never payloads, pages, URLs or files. Your devices' data is visible only to your account. Use it only on computers you own or are allowed to monitor.

1. Add this computer

Copy this now. The token is shown only once.

2. Install and run the agent

You need: the token command from step 1, administrator/root rights on that computer, and an internet connection. The agent must stay running (keep its window open) while you want the computer monitored.

Step 2.1 – Download the agent. Download shadowsense_agent.py on the computer you want to monitor. It usually lands in your Downloads folder. If the browser renamed it (for example shadowsense_agent (1).py), delete the old copy and rename the new one back to shadowsense_agent.py.

Step 2.2 – Follow the steps for your system:

Windows

Install Python 3.12 from python.org. On the first installer screen tick “Add python.exe to PATH”, then click Install Now.
Install Npcap from npcap.com (it is the packet-capture driver). Keep the default options and finish the installer.
Open the Start menu, type PowerShell, right-click “Windows PowerShell” and choose Run as administrator. Click Yes on the prompt.
Install the capture library:
```
pip install scapy
```
Go to the folder where you saved the agent:
```
cd $HOME\Downloads
```
Paste the command from step 1 and press Enter. On Windows use python instead of python3:
```
python shadowsense_agent.py --server https://YOUR-SERVER --token ssd_YOUR_TOKEN
```

macOS

Open Terminal (Spotlight → type Terminal). Check Python with python3 --version. If it is missing, install it from python.org.
Install the capture library:
```
pip3 install scapy
```
Go to the folder where you saved the agent:
```
cd ~/Downloads
```
Paste the command from step 1 with sudo in front, press Enter and type your Mac password when asked (nothing shows while you type):
```
sudo python3 shadowsense_agent.py --server https://YOUR-SERVER --token ssd_YOUR_TOKEN
```

Linux

Open a terminal. Python 3 is normally pre-installed (check with python3 --version). Nothing else needs to be installed.
Go to the folder where you saved the agent:
```
cd ~/Downloads
```

Paste the command from step 1 with sudo in front and enter your password:

sudo python3 shadowsense_agent.py --server https://YOUR-SERVER --token ssd_YOUR_TOKEN

3. Check that it is working

Right after you start it the agent prints a line saying it is capturing flow metadata (no payloads).
Use the computer normally for 10–20 seconds (open a few websites or a video). Every few seconds the agent prints a status line like raw_seen=… packets=… sent=…. If packets and sent are above 0 and growing, it is working.
Reload this page. In the table below your computer should change from “never connected” to online and the Flows count should go up.
Open the dashboard. Your flows appear in Live events within a few seconds.

If something does not work

“Packet capture needs administrator/root rights”: close the window and start it again as Administrator (Windows) or with sudo (macOS/Linux).
“Install scapy first”: run pip install scapy (macOS: pip3 install scapy). On Windows also make sure Npcap is installed.
“No packets seen at all”: the wrong network adapter was picked. Run python shadowsense_agent.py --list-interfaces to see the adapters, then add --iface all (or an adapter name) to your command.
“could not reach the server”: check your internet connection and that the --server address is exactly the one shown in step 1.
“server answered HTTP 401”: the token is wrong, was copied only partly, or the computer was removed. Create a new token in step 1 and use that.
Lost the token? It is shown only once. Remove that computer in the table below and create a new token.

To stop the agent press Ctrl+C in its window. To stop monitoring a computer for good, click Remove next to it below: its token stops working immediately.

Your computers

Name	Status	Flows	Last seen

Back to the dashboard