NetStacksNetStacks
Contact SalesDownload

Quick Start Guide

Connect to your first network device, run commands, ask the AI assistant, and save a session in NetStacks Terminal.

Overview

This guide walks you through connecting to your first network device, running basic commands, asking the AI assistant about the output, and saving the session as a profile.

Target audience: Network engineers who have just installed NetStacks Terminal and want to connect to a device for the first time.

Time estimate: About five minutes from launch to your first saved session.

Prerequisites

Install NetStacks Terminal first — see the Installation page. On first launch the Local Agent starts as a sidecar and you set a master password to unlock the credential vault.

First-run Setup Wizard

The very first launch shows a Setup Wizard that walks you through choosing an AI provider and API key, optionally connecting NetBox, and the core concepts (API Resources vs Integrations). You can skip it and configure everything later in Settings.

To run it again anytime: Settings → General → Onboarding → “Re-run Setup Wizard”, or the command palette → “Setup Wizard”. Look for the ✨ Ask AI buttons throughout Settings for guided help.

How It Works

When you connect to a device, the Terminal hands the request to its components based on your mode:

  • Personal Mode — The bundled Local Agent establishes the SSH (or Telnet) session using credentials you provide or that are stored in the local encrypted vault. Everything (sessions, profiles, vault, history) lives in a local SQLite database.
  • Enterprise Mode — The Terminal connects through a Controller, which retrieves credentials from a shared vault, can issue short-lived SSH certificates, and logs the session for audit.

Sessions can be saved as profiles for one-click reconnection. Each session opens in its own tab, and you can drag a tab into a split view to work with multiple devices side by side.

Step-by-Step Guide

This walkthrough uses a realistic scenario: connecting to a Cisco IOS-XE router at core-rtr-01.dc1.example.net (10.0.1.1) via SSH. Keyboard shortcuts below use the macOS modifier first, then Windows/Linux.

Step 1: Launch NetStacks Terminal

Open NetStacks from Applications (macOS), the Start Menu (Windows), or your application launcher (Linux). On first run, set a master password to unlock the credential vault.

Step 2: Open Quick Connect

Press Cmd+Shift+Q (macOS) or Ctrl+Shift+Q (Windows/Linux) to open Quick Connect. You can also click the + button in the tab bar.

Step 3: Enter connection details

  • Host: core-rtr-01.dc1.example.net (or 10.0.1.1)
  • Port: 22
  • Username: netadmin
  • Authentication: Password or SSH key (choose your preferred method)
SSH key authentication

If you choose SSH Key, browse to your private key (typically ~/.ssh/id_ed25519 or ~/.ssh/id_rsa). NetStacks supports Ed25519, RSA, and ECDSA key types.

Step 4: Connect

Click Connect. The Terminal opens a new tab with a live SSH session. You should see the device prompt:

core-rtr-01#

Step 5: Run your first command

Type show version and press Enter to see the IOS version, uptime, and hardware details:

core-rtr-01# show version
Cisco IOS XE Software, Version 17.09.04a
Cisco IOS Software [Cupertino], ISR Software (X86_64_LINUX_IOSD-UNIVERSALK9-M), Version 17.9.4a

core-rtr-01 uptime is 127 days, 4 hours, 23 minutes
System returned to ROM by PowerOn

cisco ISR4451-X/K9 (2RU) processor with 3670016K/6147K bytes of memory.
Processor board ID FJC2316A0GJ

Step 6: Ask the AI assistant

Open the AI assistant with Cmd+I (macOS) or Ctrl+I (Windows/Linux). Ask a question such as:

What IOS version is this device running, and is it current?

The assistant reads the sanitized terminal output from your session and answers based on the show version output.

AI provider required

AI features need an LLM provider. Open Settings → AI and add a provider: Anthropic, OpenAI, Ollama, OpenRouter, LiteLLM, or a custom OpenAI-compatible endpoint.

A separate shortcut, Cmd+Shift+A (Ctrl+Shift+A), opens the AI chat as a full tab instead of the side assistant.

Step 7: Save the session as a profile

To reconnect later with one click, save the connection as a profile via Settings → Profiles or from the Sessions sidebar. Saved profiles appear on the welcome screen for one-click reconnection.

Cmd+S saves documents, not sessions

The Cmd+S / Ctrl+S shortcut saves the active document (for example a note), not a connection profile. Use Settings → Profiles or the Sessions sidebar to save a session.

Step 8: Open a second tab

Press Cmd+T (macOS) or Ctrl+T (Windows/Linux) to open a new terminal tab. Use Quick Connect again to reach another device — for example a distribution switch at dist-sw-01.dc1.example.net.

Step 9: Split the view

To see two sessions side by side, drag one tab into the split view, or right-click a tab and use the split option in the context menu. There is no fixed split keyboard shortcut. With both sessions visible you can run commands on both at once using Multi-Send (Cmd+Shift+M / Ctrl+Shift+M). See Multi-Tab & Split Panes for details.

Code Examples

Real network engineering commands you can try during your first session.

SSH connection (what the Local Agent does under the hood)

ssh -o StrictHostKeyChecking=accept-new [email protected]

Common first commands on a Cisco IOS device

cisco-iostext
! Software version and uptime
show version

! Interfaces with IP addresses and status
show ip interface brief

! Running config, interface sections only
show running-config | section interface

! Routing table summary
show ip route summary

Expected output: show ip interface brief

core-rtr-01# show ip interface brief
Interface              IP-Address      OK? Method Status                Protocol
GigabitEthernet0/0/0   10.0.1.1        YES NVRAM  up                    up
GigabitEthernet0/0/1   10.0.2.1        YES NVRAM  up                    up
GigabitEthernet0/0/2   unassigned      YES NVRAM  administratively down down
Loopback0              192.168.1.1     YES NVRAM  up                    up

Common first commands on a Juniper Junos device

juniper-junostext
# Software version
show version

# Interfaces with status
show interfaces terse

# Interface configuration
show configuration interfaces

Enterprise Mode: connect the Terminal to a Controller

If your team runs a Controller, connect from Settings → Enterprise. Enter the Controller URL and log in with your enterprise credentials. Devices from the centralized inventory then appear in your device list.

Verify Controller health from the command line

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

Q&A

How do I re-run the first-run Setup Wizard?
Go to Settings → General → Onboarding and click “Re-run Setup Wizard”, or open the command palette and choose “Setup Wizard”. It re-runs the AI-provider, NetBox, and concepts walkthrough without resetting anything.
How do I connect to my first device?
Press Cmd+Shift+Q (macOS) or Ctrl+Shift+Q (Windows/Linux) to open Quick Connect, enter the host, port, username, and authentication method, then click Connect. See the step-by-step guide above.
What authentication methods does NetStacks support?
Password, SSH key (Ed25519, RSA, ECDSA), keyboard-interactive, and — in Enterprise Mode — short-lived SSH certificates issued by the Controller.
How do I save a session for later?
Save it as a profile via Settings → Profiles or the Sessions sidebar. Note that Cmd+S / Ctrl+S saves the active document, not a connection profile.
Can I connect to multiple devices at once?
Yes. Open additional tabs with Cmd+T / Ctrl+T and connect each to a different device. Drag a tab into the split view (or use the tab context menu) to see sessions side by side, then enable Multi-Send (Cmd+Shift+M / Ctrl+Shift+M) to type once and broadcast to every active session.
How do I use AI assistance during a session?
Open the AI assistant with Cmd+I / Ctrl+I. It can read your (sanitized) terminal output, suggest commands, explain errors, and help troubleshoot. Configure a provider first in Settings → AI — Anthropic, OpenAI, Ollama, OpenRouter, LiteLLM, or a custom OpenAI-compatible endpoint. Cmd+Shift+A opens AI chat as a full tab instead.
What is the difference between Personal and Enterprise Mode?
In Personal Mode the Terminal and its Local Agent work independently — you provide credentials and everything is stored locally in an encrypted SQLite vault. In Enterprise Mode the Terminal connects to a Controller that provides a shared vault, RBAC, SSH certificates, session recording, and audit logging.
How do I connect the Terminal to the Controller?
Open Settings → Enterprise, enter your Controller URL (for example https://controller.company.com), and log in with your enterprise credentials.

Troubleshooting

Connection refused

The device is not reachable on the specified port. Verify the IP and port, confirm the device is powered on with SSH enabled, and check for firewalls or ACLs:

# Verify the host is reachable
ping 10.0.1.1

# Check if the SSH port is open
nc -zv 10.0.1.1 22

Authentication failed

Wrong password, key not accepted, or key algorithm mismatch. Verify credentials, ensure the device accepts your key type (some older devices do not support Ed25519), and check that the username matches an account on the device.

Host key verification failed

Appears on first connection or when a device's host key changes (reimage, replacement, new firmware). NetStacks uses trust-on-first-use and prompts you to accept the key. Accept it if the device was legitimately rebuilt; otherwise investigate — a changed host key can indicate a man-in-the-middle attack.

Connection timed out

No response within the timeout window. Common causes: a routing issue, the device being powered off, or a firewall silently dropping packets. Check routing with traceroute 10.0.1.1.

Garbled or unreadable output

Usually a terminal type or encoding mismatch. NetStacks defaults to xterm-256color, which works with most modern gear. On older equipment, try vt100 in the connection settings.

Now that you have connected to your first device, explore these features: