The Local Agent
The background process that powers NetStacks Terminal in standalone mode: what it does, how it is secured, where it stores your data, and how to back up and restore it.
What the Local Agent Is
In standalone mode, NetStacks Terminal has two parts: the window you see, and a background process called the Local Agent (netstacks-agent). The agent is a separate program written in Rust and bundled inside every desktop download. The app starts it automatically on launch and stops it when you quit, so there is nothing to install or run yourself.
Only one agent runs per user. If you open a second NetStacks window, it connects to the same agent.
What It Does
All the work that touches the network or your stored data happens in the agent:
- SSH and Telnet sessions, SFTP, SSH tunnels and jump hosts
- The credential vault: encrypting and decrypting your secrets
- SNMP v2c queries, neighbour discovery and live topology polling
- AI requests to your provider, AI tools and MCP server connections
- Documents, topologies, MOP execution and session recordings
- Python scripts, the API client, Git and language servers for Workspaces
- NetBox, LibreNMS and Netdisco integrations, and hover enrichment
The window only displays things and sends your actions to the agent. That is also why the browser-based web terminal, which has no agent, always works through a Controller.
How It Is Secured
- Localhost only. The agent listens on
127.0.0.1, on a port the operating system picks at random each launch. It is not reachable from other machines. - HTTPS only. Traffic between the window and the agent is encrypted with TLS. On first run, the agent creates a self-signed certificate (“NetStacks Local Agent”, valid for
localhostand127.0.0.1), and the app adds it to your user's trust store. This is the certificate prompt you see during installation or first launch. - Per-launch token. Each time the app starts, it generates a random token and gives it to the agent. Every request must carry that token, so other programs on your computer can't use the agent.
- Encrypted secrets. Passwords, key passphrases, API keys, integration tokens and secure notes are encrypted in the vault (AES-256-GCM, key derived from your master password with Argon2id) before they are written to disk. See Credential Vault.
The agent's HTTP API is internal to the app. It changes between versions and is not meant for scripting. To automate against NetStacks, use the Controller's REST API (enterprise) or Workspaces scripts.
Where Your Data Lives
Everything you create in standalone mode is stored in a single SQLite database. That includes sessions, folders, credential profiles, the encrypted vault, topologies, documents, MOPs and settings.
| Platform | Database file | App folder (config, agent certificate) |
|---|---|---|
| macOS | ~/Library/Application Support/netstacks/netstacks.db | ~/Library/Application Support/com.netstacks.terminal/ |
| Windows | %LOCALAPPDATA%\netstacks\netstacks.db | %APPDATA%\com.netstacks.terminal\ |
| Linux | ~/.local/share/netstacks/netstacks.db | ~/.local/share/com.netstacks.terminal/ |
On macOS and Linux the database file is readable only by your user. The app folder holds app-config.json, which records whether the app starts in standalone or enterprise mode, and the agent's TLS certificate.
Some data lives elsewhere: SSH host keys you trust are written to your normal ~/.ssh/known_hosts. Tools the agent downloads on first use, such as uv for Python scripts, are cached under the netstacks data folder.
Backup & Restore
Open Settings → Integrations and scroll to Backup & Seed:
- Full backup writes a complete copy of the database, including the encrypted vault, to a file you choose. Use it to move to a new computer or to keep a safety copy. To use the secrets in it, you need the master password that was in use when the backup was made.
- Shareable seed writes the same data with all secrets removed. Use it to hand a colleague your sessions, folders, profiles (without passwords), topologies and documents.
- Import database… loads a backup or seed. The import is applied the next time NetStacks starts. Your current database is saved with a timestamp first.
NetStacks doesn't make backups automatically, so make one before major changes or reinstalling. You can also copy netstacks.db while the app is closed.
Remote Windows (Remote Agent)
You can also run the agent on a Linux server and drive it from your desktop. That is useful for working from a jump box or a host inside a remote network. Right-click a saved SSH session to a Linux host (CLI flavor Linux/Unix Shell or Auto-detect) and choose Open Remote Window.
NetStacks downloads the matching agent build to ~/.netstacks/ on that host, starts it, and opens a new window connected to it. The status bar then shows Connected to remote agent on <host>. Remote agents are available for Linux x86_64 and ARM64 (aarch64) hosts, and only in standalone mode.
In Enterprise Mode Enterprise
When the Terminal is connected to a Controller, the Local Agent does not run. The Controller does the work instead: it makes SSH connections, holds credentials and runs AI requests. So agent-only features are not available in enterprise mode. These include the local vault, local sessions and import, Workspaces, tunnels, jump hosts, remote windows and the local shell. Your standalone database stays on disk, untouched, until you switch back. See Connecting to a Controller.
Troubleshooting
The app can't reach the agent on startup
This usually means the agent certificate isn't trusted yet, for example because a keychain, Windows certificate or polkit prompt was dismissed. Quit NetStacks completely and reopen it; the certificate install runs again. On Linux, make sure polkit (pkexec) is available.
“Vault is locked”
Saved credentials can't be used until the vault is unlocked. Unlock it at startup or in Settings → Security.
An old agent seems to be stuck
Quit NetStacks. If a netstacks-agent process is still running, end it in Activity Monitor, Task Manager or with pkill netstacks-agent, then start the app again.