Common Issues

Supported Operating Systems

OS	Minimum Version	Architecture	Notes
macOS	12 (Monterey)+	x64, ARM64 (Apple Silicon)	Full support including Guard and Trap
Ubuntu	20.04 LTS+	x64, ARM64	Recommended Linux distribution
Debian	11 (Bullseye)+	x64, ARM64	Full support
CentOS / RHEL	8+	x64	SELinux compatible
Windows	10 (build 1903)+	x64	Guard requires Administrator

System Requirements

Node.js

Node.js >= 20 is required. Panguard uses modern JavaScript features (top-level await, native fetch) that require Node.js 20 or later.Check your version:

node --version

Install or update via nvm:

nvm install 20
nvm use 20

Or via your package manager:

# macOS
brew install node@20

# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# Windows (winget)
winget install OpenJS.NodeJS.LTS

Root / Administrator Privileges

Different Panguard modules have different privilege requirements:

Module	Root/Admin Required	Reason
`panguard scan`	No	Reads files with user permissions
`panguard guard`	Yes	Monitors system logs, manages firewall rules
`panguard trap`	Yes	Binds to privileged ports (< 1024)
`panguard chat`	No	Sends notifications over HTTPS
`panguard report`	No	Generates reports from existing data
`panguard manager`	No	Runs as a regular HTTP server

Run privileged modules with sudo:

sudo panguard guard start
sudo panguard trap start

Disk Space

Component	Approximate Size
Panguard CLI + core	~50 MB
ATR rules (768)	~10 MB
Threat Cloud database (self-hosted)	100 MB — 10 GB (depends on data)
Guard logs + data	Grows over time, recommend 1 GB minimum

Network

Panguard requires outbound HTTPS access to:

Destination	Purpose
`tc.panguard.ai`	Threat Cloud intelligence feeds
`registry.npmjs.org`	Package installation and updates
`api.anthropic.com`	AI analysis (if using Anthropic)
`api.openai.com`	AI analysis (if using OpenAI)
`localhost:11434`	Ollama local AI (if configured)

All connections can optionally go through an HTTP proxy via the HTTPS_PROXY environment variable.

How to Update

Update Panguard to the latest version:

npm update -g panguard

npx panguard@latest doctor

panguard --version

After updating, restart any running services:

# Restart Guard
sudo panguard guard stop
sudo panguard guard start

# Restart Chat
panguard chat stop
panguard chat start

Panguard checks for updates automatically and displays a notification in the CLI when a new version is available. ATR detection rules update independently from the CLI tool.

How to Uninstall

To completely remove Panguard from your system:

macOS / Linux
Windows

# 1. Stop all running services
sudo panguard guard stop
panguard chat stop

# 2. Remove the system service (if installed)
sudo panguard guard uninstall-service

# 3. Uninstall the npm package
npm uninstall -g panguard

# 4. Remove data directories
rm -rf ~/.panguard
rm -rf ~/.panguard-guard
rm -rf ~/.panguard-chat

# 5. Remove credentials
rm -f ~/.panguard/credentials.json

# 6. Remove firewall rules added by Guard
# macOS:
sudo pfctl -F all
# Linux:
sudo iptables -F PANGUARD 2>/dev/null
sudo iptables -X PANGUARD 2>/dev/null

# 1. Stop all running services
panguard guard stop
panguard chat stop

# 2. Remove the Windows service (if installed)
panguard guard uninstall-service

# 3. Uninstall the npm package
npm uninstall -g panguard

# 4. Remove data directories
Remove-Item -Recurse -Force "$HOME\.panguard"
Remove-Item -Recurse -Force "$HOME\.panguard-guard"
Remove-Item -Recurse -Force "$HOME\.panguard-chat"

# 5. Remove firewall rules
Remove-NetFirewallRule -DisplayName "Panguard*"

Uninstalling removes all local data including scan history, threat logs, and configuration. Export your data first with panguard report generate if you need historical records.

Common Error Messages

Error: Node.js version 20 or later is required

Your Node.js version is too old. Update to Node.js 20+: bash nvm install 20 && nvm use 20

Error: EACCES permission denied

You are running a privileged module without root access: bash sudo panguard guard start For non-root setups, see the system service guide.

Error: Cannot find module 'panguard'

Panguard is not installed globally, or your PATH does not include the npm global bin directory: bash npm install -g panguard # Or check your PATH: npm config get prefix

Error: ECONNREFUSED

The target service is not running or is unreachable. Check: - Is the service started? (panguard status) - Is the port correct? (check environment variables) - Is a firewall blocking the connection?

Getting Started

Concepts

Guides

Configuration

Troubleshooting

Supported Operating Systems

System Requirements

How to Update

How to Uninstall

Common Error Messages

​Supported Operating Systems

​System Requirements

​How to Update

​How to Uninstall

​Common Error Messages

Supported Operating Systems

System Requirements

How to Update

How to Uninstall

Common Error Messages