Logs & Diagnostic Information

Where the NetStacks desktop app keeps its files on macOS, Windows and Linux, how to see the local agent's output, how to recover when the local agent will not start or the app is stuck in Controller mode, and what to send when asking for help.

Overview

The desktop app has two parts: the window you see, and a bundled background program, the local agent (netstacks-agent). In standalone mode the agent does the SSH and Telnet connections, holds the vault, stores your data and calls your AI provider. It listens only on 127.0.0.1, on a random port chosen at each start, over HTTPS with a self-signed certificate. In enterprise mode the agent is not used; the app talks to the Controller instead.

Where NetStacks Keeps Its Files

OS	App folder (config, certificates)	Database (sessions, vault, documents, settings)
macOS	`~/Library/Application Support/com.netstacks.terminal/`	`~/Library/Application Support/netstacks/netstacks.db`
Windows	`%APPDATA%\com.netstacks.terminal\`	`%LOCALAPPDATA%\netstacks\netstacks.db`
Linux	`~/.local/share/com.netstacks.terminal/`	`~/.local/share/netstacks/netstacks.db`

Files in the app folder that matter for troubleshooting:

File	Purpose
`app-config.json`	Holds `controllerUrl`. If it is set, the app starts in enterprise mode; if not, in standalone mode.
`controller-cert.json`	The Controller CA fingerprint the app trusted, per Controller URL.
`localhost.crt`, `localhost.key`	The local agent's self-signed certificate.
`tls_installed.txt`	Records that the agent certificate was added to your OS trust store.
`agent.lock`	Used at start-up to find and stop a leftover agent from a previous run.

Everything you create in standalone mode, including the encrypted vault, lives in the single netstacks.db file. Trusted SSH host keys are kept in ~/.ssh/known_hosts. Session recordings are saved under ~/Documents/NetStacks/recordings/.

Seeing the Local Agent's Output

The desktop app does not write a log file. To watch what it and the local agent are doing, start it from a terminal window. Agent lines are prefixed with [sidecar], and Controller certificate checks with [cert].

macOSbash

/Applications/NetStacks.app/Contents/MacOS/NetStacks

Linux (AppImage)bash

./NetStacks-x86_64.AppImage

The agent logs at info level. For more detail while reproducing a problem, set RUST_LOG before starting the app, for example RUST_LOG=netstacks_agent=debug. Passwords and keys are shown as [REDACTED] in the agent's logs, but read the output before sharing it.

Local Agent Does Not Start

Symptom: the startup screen says Cannot connect to backend. Please ensure the app is running correctly.

Quit NetStacks completely (all windows) and start it again.
Approve the certificate prompt. On first run the app adds the agent's certificate to your OS trust store and restarts itself. macOS may ask for your login password, Windows asks you to confirm a root certificate, and Linux shows a polkit password prompt. If you cancelled it, quit NetStacks, delete tls_installed.txt from the app folder, and start again to get the prompt back.
Linux only: the certificate step needs polkit (pkexec) and a polkit agent in your desktop session. The app also needs libwebkit2gtk-4.1-0 and libgtk-3-0; the AppImage additionally needs libfuse2.
Run it from a terminal (previous section) and look for [sidecar] terminated or TLS cert install failed lines.

Note

If the app is set to use a Controller, the local agent exits on purpose and prints Enterprise mode detected. Agent not needed. That is normal.

Switching Back to Standalone by Hand

Normally you switch modes in the app: Use standalone mode instead on the sign-in screen, or Settings → Enterprise. If the app only shows a Cannot Connect screen and you cannot reach either:

Quit NetStacks.
Open app-config.json in the app folder and remove the controllerUrl entry (or change it to the correct URL). Deleting the file also returns the app to standalone mode.
Start NetStacks.

app-config.json (standalone)json

{}

Your standalone data is not touched by switching modes; it is all in netstacks.db.

Backing Up the Local Database

Before trying risky fixes (such as a vault reset), back up your data. In standalone mode open Settings → Integrations and use Backup & Seed:

Full backup includes the vault contents (still encrypted with your master password).
Shareable seed has secrets removed, for giving a starter setup to a colleague.
Import database… stages a backup and swaps it in the next time the app starts. The current database is saved first with a timestamp.

You can also copy netstacks.db while NetStacks is not running.

Controller Logs Enterprise

On the Controller host, from the deployment directory:

docker compose logs -f api admin-ui

See Controller Deployment & Health for health checks and the other services. For the web terminal, your browser's developer console (F12) shows network and certificate errors.

Asking for Help

Include the following so the problem can be reproduced:

NetStacks Terminal version (About NetStacks) and, if used, the Controller version (Administration → Deployment Info).
Operating system and whether you use standalone mode, the desktop app with a Controller, or the web terminal.
The exact error text, and the device type and OS version if it is a device connection problem.
The steps that lead to the problem, and relevant log lines with passwords, keys and hostnames you cannot share removed.

See the Support page for ways to reach us, or email [email protected].