Folders

Overview

Folders give you a nested tree for organizing your saved items. In NetStacks a folder can hold SSH sessions (the connection profiles you launch terminals from) and saved topologies. Folders let you group items by environment, by site, by customer, or any structure that matches how you work.

• Nested folder tree with arbitrary depth (a folder can have a parent folder)
• Two independent scopes: session folders and topology folders
• Drag-and-drop reordering with a per-folder sort order
• Stored locally in SQLite alongside your sessions — no server, no sync, no telemetry

How Folders Work

Nesting

Each folder has an optional parent folder. By giving a folder a parent you build a tree. A typical session tree groups by environment first, then by site or device function:

Sessions
├── Production
│   ├── Core Routers
│   ├── Distribution Switches
│   └── Firewalls
├── Lab
│   └── Test Devices
└── Customers
    ├── Acme Corp
    └── Globex

Scopes

Every folder belongs to one scope. The two scopes are independent trees, so your session folders and topology folders do not mix:

• session — the default scope; holds saved SSH sessions
• topology — holds saved topologies (see Network Topology)

Assigning items to a folder

A session or topology references its folder. Items with no folder live at the root of the tree. Moving an item is simply changing which folder it points to (or clearing it to send the item back to the root). Moving an item is purely organizational — it does not change who can use it, because NetStacks is a single-user local application.

Deleting a folder

You do not need to empty a folder before deleting it. When a folder is deleted, the sessions and topologies inside it are not deleted — they move back to the root of the tree. Child folders, however, are removed along with the parent.

Data Model

Folders are stored in the local SQLite database that also holds your sessions. The schema is intentionally small:

-- Folders for organizing items (sessions, topologies, etc.)
CREATE TABLE folders (
    id         TEXT PRIMARY KEY,
    name       TEXT NOT NULL,
    parent_id  TEXT REFERENCES folders(id) ON DELETE CASCADE,
    sort_order INTEGER DEFAULT 0,
    scope      TEXT NOT NULL DEFAULT 'session',
    created_at TEXT NOT NULL DEFAULT (datetime('now')),
    updated_at TEXT NOT NULL DEFAULT (datetime('now'))
);

-- A session points at a folder (or NULL = root)
-- folder_id TEXT REFERENCES folders(id) ON DELETE SET NULL

-- A topology points at a folder (or NULL = root)
-- folder_id TEXT REFERENCES folders(id) ON DELETE SET NULL

The fields map directly to what you see in the UI:

name

The display name of the folder.

parent_id

The parent folder, or empty for a top-level folder. This is what creates the nested tree.

scope

Either session (default) or topology. Determines which tree the folder appears in.

sort_order

Controls ordering of folders at the same level; lower values sort first.

Step-by-Step Guide

Create a folder

1. Open the sessions sidebar.
2. Create a new folder and give it a name (for example, "Production").
3. Leave the parent unset for a top-level folder, or pick an existing folder to nest under it.

Create a sub-folder

1. Create another folder (for example, "Core Routers").
2. Choose "Production" as its parent.
3. Repeat for other groupings such as "Firewalls" or "Switches".

Move a session into a folder

1. Drag the session onto the target folder, or edit the session and set its folder.
2. The session now appears nested under that folder in the sidebar.
3. To send a session back to the root, clear its folder.

Reorder folders

1. Drag folders up or down within the same level to change their order.
2. The new order is saved as each folder's sort order.

Delete a folder

1. Delete the folder from the sidebar.
2. Sessions and topologies inside it move back to the root — they are not lost.
3. Any sub-folders of the deleted folder are removed.

Examples

A folder record

This is what a session folder looks like as stored data:

{
  "id": "f-1a2b3c",
  "name": "Production",
  "parent_id": null,
  "scope": "session",
  "sort_order": 0,
  "created_at": "2026-06-01T12:00:00Z",
  "updated_at": "2026-06-01T12:00:00Z"
}

A nested sub-folder

{
  "id": "f-9z8y7x",
  "name": "Core Routers",
  "parent_id": "f-1a2b3c",
  "scope": "session",
  "sort_order": 0,
  "created_at": "2026-06-01T12:05:00Z",
  "updated_at": "2026-06-01T12:05:00Z"
}

A session assigned to that folder

The session points at the folder via folder_id. A null value means the session sits at the root:

{
  "id": "s-4d5e6f",
  "name": "core-rtr-01",
  "folder_id": "f-9z8y7x",
  "host": "10.0.0.1",
  "port": 22,
  "icon": "server"
}

Reading folders from the local database

Because everything is local SQLite, you can inspect your folder tree directly. List all session folders ordered the way the sidebar shows them:

-- All session folders, in sidebar order
SELECT id, name, parent_id, sort_order
FROM folders
WHERE scope = 'session'
ORDER BY sort_order, name;

-- Sessions that have no folder (they live at the root)
SELECT id, name, host
FROM sessions
WHERE folder_id IS NULL;

Questions & Answers

Q: Do folders store credentials?

A: No. Folders organize saved SSH sessions and topologies. Credentials are protected by the Credential Vault, which encrypts secret material independently of any folder.

Q: Do folders control who can see or use a credential?

A: No. NetStacks runs as a local, single-user application, so there are no role-based folder grants, no password-visibility flags, and no permission cascading. Folders are purely for organization.

Q: Can folders be nested?

A: Yes. Each folder has an optional parent, so you can build a tree of any depth. For everyday usability, a few levels is usually enough.

Q: What is a folder scope?

A: Each folder belongs to one scope — session (the default) or topology. The two scopes are separate trees, so session folders and topology folders never mix.

Q: What happens to my sessions when I delete a folder?

A: They are not deleted. Sessions and topologies inside a deleted folder move back to the root of the tree. Sub-folders of the deleted folder are removed.

Q: Do I have to empty a folder before deleting it?

A: No. You can delete a non-empty folder; its items simply move to the root.

Q: How do I move a session out of a folder?

A: Drag it to another folder, or edit the session and clear its folder to return it to the root.

Q: Where are folders stored?

A: In the local SQLite database alongside your sessions. Nothing is sent to a server — there is no sync and no telemetry.

Troubleshooting

A session is missing from the sidebar

If a session disappeared from where you expected it, its folder may have been deleted, which moves the session back to the root. Look for it at the top level of the tree:

SELECT id, name, host
FROM sessions
WHERE folder_id IS NULL
ORDER BY name;

A folder shows the wrong items

Folders are scoped. A session folder never shows topologies and a topology folder never shows sessions. Confirm you are looking at the right scope, and check the folder's scope value:

SELECT id, name, scope, parent_id
FROM folders
WHERE name = 'Core Routers';

Folder order looks wrong

Folders at the same level sort by sort_order first, then by name. If drag-and-drop ordering does not stick, reorder the folders again so the sort values are rewritten, then refresh the sidebar.

Related Pages

Explore related organization and credential features:

• Credential Vault — how credentials are encrypted and stored
• Personal Vaults — personal credentials, which exist outside the folder tree
• Connecting to Devices — saving and launching the SSH sessions that folders organize
• Network Topology — saved topologies, which use the topology folder scope
• Source Code & Cryptography — how the local database and encryption work