Introduction

What NetStacks is, how Personal Mode and Enterprise Mode work, and whether you need just the Terminal or also the Controller.

What is NetStacks?

NetStacks is a modern terminal and network operations platform built for engineers who manage everything from a handful of switches to thousands of routers, firewalls, and appliances across multiple sites. It replaces aging tools like SecureCRT, PuTTY, and spreadsheet-based credential tracking with a single, purpose-built application that understands networking workflows.

NetStacks has two parts you can mix and match:

Terminal + Local Agent — A native desktop application built with Tauri (Rust + React). The Terminal is the window you interact with; the Local Agent is a bundled sidecar process that performs the SSH/Telnet/SFTP connections, holds your encrypted credential vault, and runs the AI integration. Together they give you multi-tab sessions, split panes, session recording, an output sanitizer that strips secrets before they reach an LLM, SNMP polling, neighbor discovery, and topology visualization. This is the open, free, single-user side of NetStacks.
Controller — A server-side application (Rust + Axum, backed by PostgreSQL with pgvector) that adds the multi-user features: a shared encrypted credential vault, RBAC, audit logging, configuration templates, scheduled automation, NOC agents, and a plugin system. The Controller is commercial software for teams and enterprises and is licensed separately.

Personal Mode vs Enterprise Mode

The same Tauri Terminal shell runs in two architectures:

Personal Mode (standalone) — Terminal plus the bundled Local Agent on a single machine. The Local Agent does SSH, holds the vault, and runs AI integration. No server, no telemetry, no license check. Ideal for an individual engineer or a small team. This side is open source under Apache 2.0.
Enterprise Mode — The same Tauri Terminal shell, but with no Local Agent. Instead the Terminal talks to a customer-hosted Controller that does multi-user SSH proxying, the shared vault, RBAC, scheduling, and plugins. Built for teams managing 100–10,000+ devices across multiple sites.

Coming from SecureCRT or PuTTY?

NetStacks can import your existing session profiles so you can get started immediately while gaining modern features like AI assistance, neighbor discovery, and real-time network topology visualization.

How It Works

In Personal Mode, the Terminal launches the Local Agent as a sidecar process on startup. You set a master password that unlocks the credential vault. The Local Agent connects directly to network devices via SSH or Telnet and stores all persistent state — sessions, profiles, encrypted vault credentials, topologies, and history — in a single local SQLite database:

macOS: ~/Library/Application Support/netstacks/netstacks.db
Linux: ~/.local/share/netstacks/netstacks.db
Windows: %APPDATA%\netstacks\netstacks.db

Vault entries are encrypted inside the database with a key derived from your master password (AES-256-GCM with Argon2id key derivation), so the .db file is safe to back up — the credentials inside it cannot be decrypted without the master password.

In Enterprise Mode, there is no Local Agent. The Terminal shell talks to a customer-hosted Controller over an HTTPS REST API and a WebSocket. The Controller retrieves device credentials from its shared encrypted vault, proxies the SSH session, applies RBAC, and records the session for audit. The Controller stores everything in PostgreSQL 16 with the pgvector extension enabled for AI embeddings.

architecture-overview.txttext

Personal Mode (open source, single user)
┌──────────────────────────────────────────────┐
│  Tauri Terminal (UI)                          │
│      │ local IPC                              │
│      ▼                                        │
│  Local Agent (sidecar)                        │
│   • SSH / Telnet / SFTP                        │
│   • Credential vault (AES-256-GCM + Argon2id) │
│   • AI integration + output sanitizer         │
│   • SQLite: netstacks.db                       │
└──────────────────────────────────────────────┘
              │ SSH / SNMP
              ▼
       Network devices

Enterprise Mode (commercial Controller)
┌──────────────────┐   HTTPS REST   ┌────────────────────────────┐
│ Tauri Terminal   │◄──────────────►│ Controller (Rust + Axum)   │
│ (no Local Agent) │   WebSocket    │  • Shared vault + RBAC      │
└──────────────────┘                │  • SSH proxy + audit log    │
                                    │  • Templates / scheduler    │
                                    │  • Plugins (Docker)          │
                                    │  • PostgreSQL 16 + pgvector  │
                                    │  • Valkey (sessions/pubsub)  │
                                    └────────────────────────────┘
                                              │ SSH / SNMP
                                              ▼
                                       Network devices

No vendor lock-in

The Terminal works with any device that speaks SSH — Cisco IOS/IOS-XE/IOS-XR/NX-OS, Juniper Junos, Arista EOS, Palo Alto PAN-OS, Fortinet FortiOS, and any Linux or Unix host. You never need the Controller to connect to devices.

Getting Started Guide

Follow these steps to go from zero to your first connected device session.

Step 1: Decide on Personal or Enterprise Mode

If you are a single engineer or a small team without centralized credential requirements, start in Personal Mode — just the Terminal and its bundled Local Agent. You can connect to a Controller later. If your organization needs a shared vault, RBAC, audit logging, or scheduled automation, deploy the Controller from the start.

Step 2: Check System Requirements

Verify your machine meets the system requirements. The Terminal runs on macOS (Intel and Apple Silicon), Windows (x64), and Linux (x64 and arm64). The Controller runs on any Docker host.

Step 3: Install the Terminal

Download and install the Terminal for your platform from the Installation Guide. All installers are code-signed and notarized, so no Gatekeeper workarounds are normally required. On first launch the Local Agent starts automatically as a sidecar.

Step 4: Set a master password

On first launch you set a master password. This unlocks the credential vault held by the Local Agent. Choose something strong and back it up — if you lose it, the encrypted vault entries in netstacks.db cannot be recovered.

Step 5: Deploy the Controller (optional)

If you chose Enterprise Mode, deploy the Controller with Docker Compose. It serves the admin UI and API over TLS on port 3000 and uses PostgreSQL plus a required Valkey service. See the Code Examples below and the Installation Guide.

Step 6: Connect to your first device

Open the Terminal, add a session (Settings → Profiles, or the Sessions sidebar), and connect. For a guided walkthrough, see the Quick Start Guide.

Code Examples

Controller Docker Compose (illustrative)

The production Controller is deployed from the official docker-compose.yml shipped with the release. The images are pulled from registry.netstacks.net, so you must log in first with docker login registry.netstacks.net. The stack includes the API, the admin UI (nginx, serving over TLS on port 3000), a required Valkey service, and a PostgreSQL database:

docker-compose.ymlyaml

services:
  valkey:
    image: valkey/valkey:8-alpine
    restart: unless-stopped
    volumes:
      - valkey_data:/data

  api:
    image: registry.netstacks.net/netstacks-controller/controller:${NETSTACKS_VERSION:-latest}
    restart: unless-stopped
    depends_on:
      valkey:
        condition: service_healthy
    environment:
      DATABASE_URL: ${DATABASE_URL}
      VALKEY_URL: "redis://valkey:6379"
      VAULT_MASTER_KEY: ${VAULT_MASTER_KEY}     # openssl rand -hex 32
      JWT_SECRET: ${JWT_SECRET}                 # openssl rand -base64 32
      SERVICE_TOKEN_SECRET: ${SERVICE_TOKEN_SECRET}  # openssl rand -base64 32
      TLS_SANS: ${TLS_SANS}                     # hostname or IP of this server
      NETSTACKS_MODE: enterprise
      API_PORT: 3000

  admin-ui:
    image: registry.netstacks.net/netstacks-controller/admin-ui:${NETSTACKS_VERSION:-latest}
    restart: unless-stopped
    depends_on:
      api:
        condition: service_healthy
    ports:
      - "3000:443"

volumes:
  valkey_data:

Production secrets

Never commit VAULT_MASTER_KEY, JWT_SECRET, or SERVICE_TOKEN_SECRET to version control. Put them in a .env file next to docker-compose.yml. If VAULT_MASTER_KEY is lost, encrypted credentials cannot be recovered.

Verify the Controller is running

The Controller serves over TLS with an auto-generated self-signed certificate, so use -k when hitting the health endpoint locally:

health-check.shbash

curl -k https://localhost:3000/health
# {"status":"ok","version":"0.0.5"}

SSH to a network device

Verify SSH access to a device from your workstation before adding it to NetStacks:

verify-ssh-access.shbash

# Cisco IOS-XE core router
ssh [email protected]

# Arista leaf switch
ssh [email protected]

# Out-of-band management address
ssh [email protected] -p 22

Questions & Answers

Q: What is NetStacks?: A: NetStacks is a desktop terminal for network engineers (SSH/Telnet/SFTP) with an encrypted credential vault, a network-aware AI assistant, and topology visualization. The free, open-source Terminal plus its bundled Local Agent run on a single machine; an optional commercial Controller adds multi-user features for teams.
Q: What is the Local Agent?: A: In Personal Mode the Local Agent is a sidecar process that starts alongside the Terminal. It performs the SSH/Telnet/SFTP connections, holds the encrypted credential vault, and runs the AI integration. In Enterprise Mode there is no Local Agent — the Terminal talks to a Controller instead.
Q: What is the difference between Terminal and Controller?: A: The Terminal (with its Local Agent) is the desktop app you use every day to connect to routers, switches, and firewalls. The Controller is a server that adds centralized device inventory, a shared encrypted vault, RBAC, audit logging, templates, and scheduled automation. You can use the Terminal without the Controller.
Q: Can I use the Terminal without the Controller?: A: Yes. In Personal Mode the Terminal and its bundled Local Agent connect directly to devices using credentials stored locally in an encrypted SQLite vault. No server infrastructure is required.
Q: Is NetStacks open source?: A: Yes — the NetStacks Terminal and Local Agent are open source under Apache 2.0 (see Source Code & Cryptography), along with the audited credential-vault crypto primitives. Only the Controller (multi-user vault, RBAC, audit, plugins) is commercial software, licensed separately for teams and enterprises.
Q: How does NetStacks handle credential security in Personal Mode?: A: All persistent state lives in a single local SQLite database (netstacks.db). Vault entries inside it are encrypted with AES-256-GCM using a key derived from your master password via Argon2id, held by the Local Agent. The OS keychain is not used; the master password is the single secret.
Q: What database does the Controller use?: A: PostgreSQL 16 with the pgvector extension (image pgvector/pgvector:pg16). pgvector enables vector similarity search for AI features. The Controller also runs a required Valkey service for session sharing and pub/sub.
Q: What protocols and devices does NetStacks support?: A: SSH (v2), Telnet, and SFTP, plus SNMP polling for monitoring and discovery. It works with any SSH-enabled device and has first-class support for Cisco IOS/IOS-XE/IOS-XR/NX-OS/ASA, Juniper Junos, Arista EOS, Palo Alto PAN-OS, Fortinet FortiOS, and Linux/Unix hosts.

Troubleshooting

Terminal won't launch on macOS

All NetStacks installers are code-signed and notarized, so Gatekeeper normally lets the app run on first launch. In rare cases (for example a stale quarantine flag after copying the app between machines), clear the quarantine attribute:

xattr -cr /Applications/NetStacks.app

Local Agent did not start

In Personal Mode the Terminal launches the Local Agent automatically. If sessions fail to open, fully quit and relaunch the app so the sidecar restarts. Confirm the data directory containing netstacks.db is writable.

Controller won't start

Verify Docker is running, that you are logged in to registry.netstacks.net, and that port 3000 is free:

check-controller.shbash

docker info
docker login registry.netstacks.net

# Check for a port conflict on 3000
ss -tlnp | grep 3000   # Linux
lsof -i :3000          # macOS

Cannot connect to a device

Confirm the device is reachable: ping 10.0.1.1
Confirm SSH is open: nc -zv 10.0.1.1 22
Confirm credentials work outside NetStacks: ssh [email protected]
Check that your firewall allows outbound TCP/22 from your workstation.

Continue exploring NetStacks with these guides:

Installation Guide — Install the Terminal and deploy the Controller
Quick Start Guide — Connect to your first device in minutes
System Requirements — Hardware, software, and network prerequisites
Source Code & Cryptography — The open-source Terminal, Local Agent, and crypto primitives
Terminal Overview — Tabs, split panes, and session management
Credential Vault — How NetStacks encrypts and manages device credentials