System Requirements

Overview

This page covers everything to verify before installing NetStacks. Requirements differ by which components you use:

• Terminal only (Personal Mode) — A lightweight native desktop app plus its bundled Local Agent. Minimal requirements; runs on macOS, Windows, and Linux.
• Controller (Enterprise Mode) — A server workload requiring Docker, PostgreSQL 16 with pgvector, a Valkey service, and more memory and disk as your device count grows.

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

How It Works

The Terminal is a native Tauri application — a Rust backend with a React frontend. 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 bundled Local Agent runs as a lightweight sidecar.

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

• Number of managed devices — each device adds inventory, credential, and configuration-history rows
• Concurrent sessions — each active SSH session through the Controller proxy consumes a connection and memory
• AI features — pgvector embeddings need extra disk and memory; local LLM inference 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

Individual engineers and small teams start with the Terminal in Personal Mode. If your organization needs a shared vault, RBAC, audit logging, or scheduled automation, you also need the Controller. See the Introduction for help deciding.

Step 2: Check your operating system

Platform compatibility matrix

The macOS build sets a minimum system version of 10.15; Apple Silicon Macs ship with macOS 11 or newer by definition.

Step 3: Check hardware requirements

Terminal requirements

Controller requirements (by deployment size)

Step 4: Verify Docker (Controller only)

The Controller ships as Docker images. Verify Docker and Docker Compose v2:

docker --version
docker compose version

Step 5: Check port availability

The Controller serves the admin UI and API over TLS on port 3000 (the admin-ui container maps 3000:443). Verify the port is free before deployment:

# Linux
ss -tlnp | grep 3000

# macOS
lsof -i :3000

If the command returns output, another service is already using the port. Stop it or remap the host-side port in docker-compose.yml.

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 port 3000 is in use
ss -tlnp | grep 3000

# macOS: check if port 3000 is in use
lsof -i :3000

# No output means the port is available

Check system resources

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

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

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

Verify PostgreSQL connectivity (bundled db profile)

The bundled db service only runs under the bundled-db profile; many deployments use an external PostgreSQL instead. If you run the bundled db, confirm it is accepting connections:

docker compose exec db pg_isready -U netstacks

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

Required ports summary

Questions & Answers

Q: What are the minimum requirements for the Terminal?

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

Q: What are the minimum requirements for the Controller?

A: For a small deployment (up to 100 devices): 2 vCPUs, 4 GB RAM, and 20 GB SSD, plus Docker and Docker Compose v2. The Controller uses PostgreSQL 16 with pgvector and a required Valkey service, both included in the official Compose stack.

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

A: Yes. The Controller supports arm64, and the pgvector/pgvector:pg16 and valkey/valkey:8-alpine images are available for arm64. A Raspberry Pi 4 or 5 with 4+ GB RAM can handle a small deployment of up to 50–100 devices.

Q: What ports does NetStacks need?

A: The Controller serves over HTTPS on port 3000. PostgreSQL (5432) and Valkey (6379) are internal to the Docker network. The Terminal and Controller need outbound TCP/22 for SSH. See the Code Examples section for the full table.

Q: Does the Controller require an internet connection?

A: No. Core features (device management, vault, templates, scheduled automation) work fully offline. Internet is only needed to pull container images and for AI/LLM features that call external APIs.

Q: Can I change the default port?

A: Yes. Change the host-side mapping for the admin-ui service in docker-compose.yml (for example 8443:443). See the Installation Guide.

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

A: No. The Terminal ships as a pre-compiled native binary; the Controller ships as Docker images. No build tools are required 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. Then verify:

docker run hello-world

Port 3000 is already in use

Another service is occupying the port. Find it and stop it, or remap the Controller:

# Find what is using port 3000
ss -tlnp | grep 3000   # Linux
lsof -i :3000          # macOS

# Change the admin-ui mapping in docker-compose.yml:
# ports:
#   - "8443:443"

Insufficient disk space for PostgreSQL

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

df -h
docker system df -v

macOS: app won't open

NetStacks is signed and notarized, so it normally opens on first launch. If a stale quarantine flag triggers a "damaged" error, clear it with xattr -cr /Applications/NetStacks.app, or open System Settings → Privacy & Security and click "Open Anyway".

Linux Terminal missing dependencies

The Terminal needs WebKit2GTK and GTK3. Install with your package manager:

# Debian / Ubuntu (.deb dependencies; add libfuse2 for the AppImage)
sudo apt install libwebkit2gtk-4.1-0 libgtk-3-0

# 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 — what NetStacks is and how it works
• Installation Guide — install the Terminal and deploy the Controller
• Quick Start Guide — connect to your first device in minutes
• HA Deployment — scale the Controller across multiple instances