System Requirements

Overview

This page covers everything you need to verify before installing NetStacks. Requirements differ depending on which components you plan to use:

• Terminal only (standalone mode) — A lightweight native desktop application with minimal requirements. Runs on macOS, Windows, and Linux.
• Controller (enterprise mode) — A server workload requiring Docker, PostgreSQL 16 with pgvector, and more memory and disk depending on the number of managed devices.

This page also covers network and port requirements and which network device platforms are supported.

How It Works

The Terminal is a native Tauri application — Rust backend with a React frontend compiled into a single binary. Because Tauri uses the operating system's built-in WebView instead of bundling Chromium, the application is small (under 50 MB) and uses roughly 80–150 MB of RAM during normal operation.

The Controller is a Rust/Axum API server that runs alongside PostgreSQL. Resource requirements scale with:

• Number of managed devices — Each device adds rows to the inventory, credential store, and configuration history
• Concurrent sessions — Each active SSH session through the Controller's proxy consumes a connection and memory
• AI features — pgvector embeddings require additional disk space and memory. LLM inference (if using local models) is the most resource-intensive operation

Requirements Check

Walk through these steps to confirm your system is ready for NetStacks.

Step 1: Identify Which Components You Need

If you are an individual engineer or small team, start with the Terminal in standalone mode. If your organization needs centralized credential management, SSH CA, or device inventory sync, you will also need the Controller. See the Introduction for help deciding.

Step 2: Check Your Operating System

Platform Compatibility Matrix

Step 3: Check Hardware Requirements

Terminal Requirements

Controller Requirements (by deployment size)

Step 4: Verify Docker (Controller Only)

The Controller ships as a Docker image. Verify Docker and Docker Compose are installed:

docker --version
docker compose version

Step 5: Check Port Availability

The Controller uses port 3000 (API) and 5432 (PostgreSQL). Verify these ports are free before deployment:

# Linux
ss -tlnp | grep -E '3000|5432'

# macOS
lsof -i :3000 -i :5432

If either command returns output, another service is already using that port. You will need to stop the conflicting service or configure NetStacks to use alternative ports.

Code Examples

Check Docker Version and Compose

$ docker --version
Docker version 27.4.1, build 5d5a263

$ docker compose version
Docker Compose version v2.32.4

Check Available Ports

# Linux: check if ports 3000 and 5432 are in use
ss -tlnp | grep -E '3000|5432'

# macOS: check if ports 3000 and 5432 are in use
lsof -i :3000
lsof -i :5432

# If no output, the ports are available

Check System Resources

# macOS: check total memory
sysctl hw.memsize
# Example output: hw.memsize: 17179869184  (16 GB)

# Linux: check available memory
free -h
#               total    used    free
# Mem:           15Gi    4.2Gi   8.1Gi

# Check CPU architecture
uname -m
# Expected: x86_64 or aarch64

Verify PostgreSQL Connectivity

After starting the Controller with Docker Compose, confirm the database is accepting connections:

docker exec -it netstacks-db-1 pg_isready -U netstacks

# Expected output:
# /var/run/postgresql:5432 - accepting connections

Required Ports Summary

Questions & Answers

Q: What are the minimum requirements for Terminal?

A: Any 64-bit machine with 4 GB RAM and 200 MB of free disk space. The Terminal runs on macOS 11+, Windows 10 (1809+), and modern Linux distributions (Ubuntu 20.04+, Debian 11+, Fedora 34+). On Linux, you also need WebKit2GTK, GTK3, and libssl.

Q: What are the minimum requirements for Controller?

A: For a small deployment (up to 100 devices): 2 vCPUs, 4 GB RAM, and 20 GB SSD. You also need Docker and Docker Compose installed. The Controller uses PostgreSQL 16 with pgvector, which is included in the official Docker Compose configuration.

Q: Can I run the Controller on a Raspberry Pi?

A: Yes. The Controller supports arm64 architecture, and the pgvector/pgvector:pg16 image is available for arm64. A Raspberry Pi 4 or 5 with 4+ GB RAM can handle a small deployment of up to 50–100 devices. For larger fleets, use dedicated server hardware.

Q: What ports does NetStacks need?

A: The Controller API listens on port 3000 (configurable). PostgreSQL uses port 5432 (internal to Docker by default). The Terminal and Controller need outbound TCP/22 to reach network devices via SSH. See the Code Examples section for the full port table.

Q: Does the Controller require an internet connection?

A: No. The Controller operates fully offline for core features like device management, credential vaulting, SSH CA, configuration templates, and scheduled automation. An internet connection is only required if you enable AI/LLM features that call external APIs (such as OpenAI or Anthropic).

Q: Can I change the default ports?

A: Yes. Set the API_PORT environment variable to change the Controller API port, and adjust the PostgreSQL port mapping in your docker-compose.yml. See the Installation Guide for configuration details.

Q: Do I need to install Rust or Node.js?

A: No. The Terminal ships as a pre-compiled native binary for each platform. The Controller ships as a Docker image. You do not need Rust, Node.js, or any build tools to run NetStacks.

Troubleshooting

Docker is not installed

The Controller requires Docker. Install Docker Engine (Linux) or Docker Desktop (macOS/Windows) from docs.docker.com/get-docker. After installation, verify it works:

docker run hello-world

Port 3000 or 5432 is already in use

Another service is occupying the port. Find which process is using it and either stop that service or change the NetStacks port:

# Find what is using port 3000
# Linux
ss -tlnp | grep 3000

# macOS
lsof -i :3000

# Change the API port in docker-compose.yml:
# ports:
#   - "8080:3000"   # Map external 8080 to internal 3000

Insufficient disk space for PostgreSQL

PostgreSQL stores data in a Docker volume. If your disk is nearly full, the database will fail to start or write. Free disk space or mount the pgdata volume to a larger drive:

# Check disk usage
df -h

# Check Docker volume sizes
docker system df -v

macOS Gatekeeper blocks Terminal

On first launch, macOS may block the application. Right-click the NetStacks app in Finder, select "Open", and confirm. Alternatively, go to System Settings > Privacy & Security and click "Open Anyway".

Windows SmartScreen warning

Windows SmartScreen may show a warning for unsigned or newly distributed executables. Click "More info" then "Run anyway" to proceed.

Linux Terminal missing dependencies

The Terminal on Linux requires WebKit2GTK and GTK3. Install them with your package manager:

# Debian / Ubuntu
sudo apt install libwebkit2gtk-4.1-0 libgtk-3-0 libssl3

# Fedora
sudo dnf install webkit2gtk4.1 gtk3

# Arch
sudo pacman -S webkit2gtk-4.1 gtk3

Related Features

Now that you have verified your system meets the requirements:

• Introduction — Learn what NetStacks is and how it works
• Installation Guide — Download and install the Terminal and deploy the Controller
• Quick Start Guide — Connect to your first device in under 5 minutes