# AidaIDE — full documentation corpus

> Every chapter of the AidaIDE user guide concatenated as markdown (26 chapters, ~48,304 words). Generated from docs-content.json by scripts/build-docs-chapter.py --export-llms-full. Canonical HTML lives at https://aidaide.app/docs/<chapter>. See https://aidaide.app/llms.txt for the short index.

## Chapters

- [AidaIDE User Guide](https://aidaide.app/docs/user-guide)
- [Keyword Index](https://aidaide.app/docs/keyword-index)
- [Getting Started](https://aidaide.app/docs/getting-started)
- [SSH Devices and Connections](https://aidaide.app/docs/ssh-devices)
- [File Browser and Editor](https://aidaide.app/docs/file-browser)
- [LCOT Panel](https://aidaide.app/docs/lcot)
- [Fleet Management](https://aidaide.app/docs/fleet)
- [Network Tools](https://aidaide.app/docs/network-tools)
- [Security Tools](https://aidaide.app/docs/security-tools)
- [AI Assistant and Sidebar](https://aidaide.app/docs/ai-assistant)
- [AI Hierarchy Builder](https://aidaide.app/docs/hierarchy-builder)
- [Cameras](https://aidaide.app/docs/cameras)
- [Databases](https://aidaide.app/docs/databases)
- [Sysadmin Tools](https://aidaide.app/docs/sysadmin)
- [Settings, Themes, Preferences](https://aidaide.app/docs/settings-themes)
- [Shortcuts and Command Palette](https://aidaide.app/docs/shortcuts)
- [Plugins, Widgets, Marketplace](https://aidaide.app/docs/plugins)
- [Workspaces and Layouts](https://aidaide.app/docs/workspaces)
- [Updates, Licensing, Support](https://aidaide.app/docs/licensing)
- [Troubleshooting & FAQ](https://aidaide.app/docs/troubleshooting)
- [Glossary](https://aidaide.app/docs/glossary)
- [Quick Reference (Cheat Sheet)](https://aidaide.app/docs/quick-reference)
- [Cloud Portal and Web Access](https://aidaide.app/docs/cloud-portal-docs)
- [Input Devices in the Browser](https://aidaide.app/docs/input-devices)
- [Hardware Lab](https://aidaide.app/docs/hardware-lab)
- [OTA Updates](https://aidaide.app/docs/ota-updates)

---

# AidaIDE User Guide

Source: https://aidaide.app/docs/user-guide

Welcome to AidaIDE — the terminal-first IDE for SSH, fleet management, embedded/IoT workflows, and AI agent hierarchies.

This guide is organized by what you see on screen. Each chapter walks through one part of the UI, defines its terms, and ends with a **Terms & Setup** section that explains anything the chapter assumes you already have (a working SSH server, an API key, a license, etc.).

If you know the name of the thing you are looking for, jump to the **[Keyword Index](/docs/keyword-index)** and it will point you at the right chapter and section.

## How to read this guide

- **Bold UI text** matches what you see on screen — menu items, button labels, tab names.
- `code` is exactly what you type or copy.
- "Click **File → Open File…**" means open the **File** menu and pick **Open File…**.
- Shortcut hints follow the Windows convention: `Ctrl+S`. On macOS substitute `⌘+S`.
- Every chapter has a Terms & Setup section at the end. If a step says *"Use your SSH credentials,"* and you do not have any, follow the link there.

## Chapters

1. **[Getting Started](/docs/getting-started)** — From a fresh install to the main window. Vault unlock, splash, first-run wizards, what every part of the screen is called.
2. **[SSH Devices and Connections](/docs/ssh-devices)** — The primary workflow. Add a host, connect, save credentials, manage keys.
3. **[File Browser and Editor](/docs/file-browser)** — Local and remote files, the code editor, split panes, find/replace, run-file.
4. **[LCOT Panel](/docs/lcot)** — The Local Chain of Thought panel. READ vs. WRITE zones, the Sysadmin Quick Toolkit, adding your own commands.
5. **[Fleet Management](/docs/fleet)** — Manage many devices at once. Fleet Manager, Deploy Lite, OTA updates.
6. **[Network Tools](/docs/network-tools)** — Scanner, topology map, packet capture, traffic analyzer, diagnostics.
7. **[Security Tools](/docs/security-tools)** — Vulnerability/CVE/secret/SAST scanners, certificate inventory, PKI, IP ACL, compliance.
8. **[AI Assistant and Sidebar](/docs/ai-assistant)** — Inline AI suggestions, chat, Claude Agent Manager, AI workflows, persona portal.
9. **[AI Hierarchy Builder](/docs/hierarchy-builder)** — The SoC/IC canvas. Build, wire, and run multi-agent pipelines.
10. **[Cameras](/docs/cameras)** — ONVIF/RTSP discovery, Camera Manager, grid viewers.
11. **[Databases](/docs/databases)** — Connect to MySQL, PostgreSQL, MongoDB, Redis. Query Editor.
12. **[Sysadmin Tools](/docs/sysadmin)** — Windows management, patching, configuration, containers, alerts, backup/DR.
13. **[Settings, Themes, Preferences](/docs/settings-themes)** — Settings, themes, the Workbench switch, and display tweaks.
14. **[Shortcuts and Command Palette](/docs/shortcuts)** — Default shortcuts, Command Palette (`Ctrl+Shift+P`), Feature Browser, custom bindings.
15. **[Plugins, Widgets, Marketplace](/docs/plugins)** — Install, manage, and create plugins and widgets.
16. **[Workspaces and Layouts](/docs/workspaces)** — Split, stack, or tear off panels, and save named layouts (desktop, ships with rc18).
17. **[Updates, Licensing, Support](/docs/licensing)** — Enter a license key, check for updates, file a bug, contact support.
18. **[Troubleshooting & FAQ](/docs/troubleshooting)** — Symptom-first lookup for "it broke" moments. Cheapest fix first; how to file a useful bug.
19. **[Glossary](/docs/glossary)** — Every term defined across the guide, consolidated A–Z with chapter cross-references.
20. **[Quick Reference (Cheat Sheet)](/docs/quick-reference)** — Single printable page. Every CLI flag, environment variable, file path, default port, and full shortcut table consolidated. Plus a per-OS quirks list and top "how do I…?" one-liners.
21. **[Cloud Portal and Web Access](/docs/cloud-portal-docs)** — Browser access via aidaide.app, guest passes, remote desktop in a tab, web dashboards, web Hierarchy Composer.
22. **[Input Devices in the Browser](/docs/input-devices)** — Touch gestures, virtual cursor, on-screen shortcut bar, international keyboard layouts (QWERTZ/AZERTY/ES), presence and spectate.

## Quick start (one-minute path)

1. Launch AidaIDE. Enter your master password to **unlock the vault**. (Brand-new install? Create a master password — write it down.)
2. The cyan `$_` splash plays for ~4 seconds, then the main window opens.
3. The **toolbar** at the top has a **New Tab** button (`+`). Click it.
4. Pick an existing connection from the dropdown, or click **Connection Manager** (`≡` icon) to add a host.
5. Once connected, the left pane is your terminal, the middle pane is the file browser/editor, and the right pane is **LCOT** — your one-click command library.

For anything more involved, open the relevant chapter above.

## Where help lives inside the app

- **Help → User Guide** — Opens this guide in a polished in-app viewer with TOC, cross-chapter search, bookmarks, light/dark theme, font zoom, and reader mode. See [Chapter 14 §User Guide viewer](/docs/shortcuts#user-guide-viewer-help--user-guide) for the keyboard shortcuts; `Ctrl+I` jumps to the Keyword Index, `Ctrl+P` copies the current chapter to the clipboard, `F11` is reader mode.
- **Help → Welcome Guide** — Short overview of the IDE.
- **Help → Setup Wizard** — Re-runs the first-run wizard.
- **Help → Ask Macy (Interactive Guide)** — Voice-narrated guided tour, including the 16-section Hierarchy Builder tour.
- **Help → Documentation** — Opens the online docs at aidaide.app.
- **Help → Bug Reports / Report a Bug** — Captures logs and opens a report.
- **Help → Check for Updates** — Pulls a manifest from updates.aidaide.app.
- **View → Feature Browser** — Searchable list of every feature tab, grouped by category. If you cannot remember where something is, this is the fastest path.
- **View → Command Palette** (`Ctrl+Shift+P`) — Type a few letters of anything (menu items, tabs, settings) and it jumps you there.

## Layout reminders

From rc18 the desktop window is a workbench, on by default. Every tab is a panel: drag it to an edge to split, to the middle to stack, or outside the window to tear it off. Named layouts live in the toolbar **Workspace** list. This is how the app is arranged, not a separate product. See [Workspaces and Layouts](/docs/workspaces).

Android stays a separate Lite-class app, not a desktop host download. The Cloud Portal is unchanged. Linux experimental (soft peer).

To use a plain tabbed window, uncheck **View → Workbench → Use the workbench shell** and restart. The old Grid Layout mode does not come back.

## Conventions used in this guide

- **Cyan** = the AidaIDE brand accent (`#4DE4E4`). When you see a cyan lin

## Using the User Guide viewer

The window you are reading right now is the **AidaIDE User Guide viewer** (Help → User Guide). It is built to feel like a small book reader:

- **Sidebar TOC.** Chapters in the top list; click any chapter to open it. Expand the triangle to drill into the chapter's H2 sections — clicking a section jumps directly to that heading.
- **Search.** Click in the search box (or press `Ctrl+F`), type, and hit `Enter` for **Next**, `Shift+Enter` for **Prev**. `F3` and `Shift+F3` work too. `Esc` clears the search.
- **Chapter navigation.** **◂ Prev** / **Next ▸** in the toolbar and footer. Or `Alt+Left` / `Alt+Right`, or `Ctrl+PgUp` / `Ctrl+PgDn`. `Ctrl+Home` jumps to the first chapter, `Ctrl+End` to the last.
- **Font zoom.** `Ctrl+=` makes everything bigger, `Ctrl+-` smaller, `Ctrl+0` resets. The TOC sidebar follows the body font.
- **Index button.** The **📖 Index** toolbar button (`Ctrl+I`) jumps to the [Keyword Index](/docs/keyword-index) — fastest way to find a term whose name you remember.
- **Theme toggle.** The **◐ Theme** button (`Ctrl+L`) flips between dark and light palettes. Your choice is remembered for next time.
- **Reader mode.** **Reader** in the toolbar (or `F11`) hides the toolbar, footer, and sidebar for distraction-free reading. `F11` or `Esc` to come back.
- **Clickable cross-references.** Any `[link](anchor)` inside a chapter — like the chapter links above — is clickable and navigates within the viewer. Try clicking [SSH Devices](/docs/ssh-devices) below to see it in action.
- **Web docs button.** Opens the same guide at <https://aidaide.app/docs> in your browser.

The viewer remembers the last chapter you were reading, your font size, theme, reader-mode state, last search term, and sidebar width. State lives in `~/.aidaide/user_guide_state.json` (or `%APPDATA%\AidaIDE\user_guide_state.json` on Windows).

> **Tip.** If you ever lose your place, `Ctrl+I` always lands you at the keyword index.

---

# Keyword Index

Source: https://aidaide.app/docs/keyword-index

Alphabetical lookup. Click any entry to jump to the chapter that explains it. If a term has more than one home, the most useful place is listed first.

Tip: your browser's in-page search (`Ctrl+F`) on this page is often the fastest way to find a term.

If you know your symptom but not the term ("save did not work", "license will not activate") jump straight to [Chapter 18 — Troubleshooting & FAQ](/docs/troubleshooting). If you need the definition of a term in plain language, [Chapter 19 — Glossary](/docs/glossary) lists every term A–Z with one-line definitions. If you want a single printable page of every flag/path/port/shortcut, see [Chapter 20 — Quick Reference](/docs/quick-reference).

## A

- **About dialog** — [Ch. 17 §Help menu](/docs/licensing#help-menu)
- **Accent colour** — [Ch. 13 §Themes and appearance](/docs/settings-themes#themes-and-appearance)
- **Access panel (Cloud Portal)** — [Ch. 21 §The Access panel](/docs/cloud-portal-docs#the-access-panel)
- **Active Directory tab** — [Ch. 12 §Windows management](/docs/sysadmin#windows-management)
- **Add command (LCOT)** — [Ch. 4 §Adding your own command](/docs/lcot#adding-your-own-command)
- **Add host (Connection Manager)** — [Ch. 2 §Adding a host](/docs/ssh-devices#adding-a-host)
- **Add panel** — [Ch. 16 §Add any panel](/docs/workspaces#add-any-panel) (`Ctrl+Shift+B`; `Ctrl+Shift+A` is AI Chat)
- **Admin Dashboard (web)** — [Ch. 21 §Other web dashboards](/docs/cloud-portal-docs#other-web-dashboards)
- **AI Agent Manager** — see *Claude Agent Manager*
- **AI Agent Portal** — [Ch. 8 §AI Agent Portal](/docs/ai-assistant#ai-agent-portal)
- **AI Agents tab** — [Ch. 8 §AI sidebar vs AI tabs](/docs/ai-assistant#ai-sidebar-vs-ai-tabs)
- **AI Chat** — [Ch. 8 §AI Chat](/docs/ai-assistant#ai-chat-ctrlshifta)
- **AI Hierarchy Builder** — [Ch. 9](/docs/hierarchy-builder)
- **AI sidebar (toggle)** — [Ch. 8 §AI sidebar vs AI tabs](/docs/ai-assistant#ai-sidebar-vs-ai-tabs)
- **AI Workflows** — [Ch. 8 §AI Workflows](/docs/ai-assistant#ai-workflows)
- **aida-lite** — [Ch. 5 §Terms & Setup](/docs/fleet#aida-lite)
- **AidaVirtualCursor** — [Ch. 22 §Trackpad mode and the virtual cursor](/docs/input-devices#trackpad-mode-and-the-virtual-cursor)
- **Air-gapped install** — [Ch. 17 §"I want an air-gapped install"](/docs/licensing#i-want-an-air-gapped-install)
- **Alert Manager** — [Ch. 12 §Monitoring & alerts](/docs/sysadmin#monitoring--alerts)
- **Anatomy of a connection tab** — [Ch. 2 §Anatomy of a connection tab](/docs/ssh-devices#anatomy-of-a-connection-tab)
- **Animations toggle** — [Ch. 13 §Animations](/docs/settings-themes#animations)
- **Ansible Runner** — [Ch. 12 §Configuration management](/docs/sysadmin#configuration-management)
- **Anthropic Claude** — [Ch. 8 §Claude Agent Manager](/docs/ai-assistant#claude-agent-manager-ctrlshiftm); see also *API key*
- **API key** — [Ch. 8 §Terms & Setup](/docs/ai-assistant#api-key)
- **API key (no key yet, setup paths)** — [Ch. 8 §"I don't have an API key yet" — setup paths](/docs/ai-assistant#i-dont-have-an-api-key-yet--setup-paths)
- **Ask Macy (Interactive Guide)** — [Ch. 1 §Onboarding & guided tours](/docs/getting-started#onboarding--guided-tours)
- **Audit log** — [Ch. 7 §Where the audit log lives](/docs/security-tools#terms--setup) | [Ch. 13 §Security](/docs/settings-themes#security)
- **Auto Layout (Composer)** — [Ch. 9 §Web Composer](/docs/hierarchy-builder#web-composer-browser-version) | [Ch. 21 §Web Hierarchy Composer](/docs/cloud-portal-docs#web-hierarchy-composer)
- **Auto Wire (Composer)** — [Ch. 9 §Web Composer](/docs/hierarchy-builder#web-composer-browser-version)
- **Auto-save (arrangement)** — [Ch. 16 §Pick up where you left off](/docs/workspaces#pick-up-where-you-left-off)
- **Auto-save (editor)** — [Ch. 3 §Editor features](/docs/file-browser#editor-features-worth-knowing) | [Ch. 13 §Editor](/docs/settings-themes#behaviour)
- **Auto-update** — [Ch. 17 §Auto-update](/docs/licensing#auto-update)
- **Autocomplete (SQL)** — [Ch. 11 §Query Editor](/docs/databases#query-editor)
- **Autosave (Hierarchy Builder drafts)** — [Ch. 9 §Autosave & crash recovery](/docs/hierarchy-builder#autosave--crash-recovery)
- **AZERTY (French keyboard)** — [Ch. 22 §International keyboard layouts](/docs/input-devices#international-keyboard-layouts)
- **Azure OpenAI** — [Ch. 8 §Terms & Setup](/docs/ai-assistant#api-key)
## B

- **Backup Dashboard (web)** — [Ch. 21 §Other web dashboards](/docs/cloud-portal-docs#other-web-dashboards)
- **Backup Manager** — [Ch. 12 §Backup & disaster recovery](/docs/sysadmin#backup--disaster-recovery)
- **Beta features** — see *Experimental Features*
- **Board Library Manager** — [Ch. 5 §Board Library Manager](/docs/fleet#board-library-manager)
- **Bookmarks (editor)** — [Ch. 3 §Editor features](/docs/file-browser#editor-features-worth-knowing) (`Ctrl+F2`)
- **BPF filter** — [Ch. 6 §Terms & Setup](/docs/network-tools#bpf-filter)
- **Branch (Git)** — [Ch. 3 §Git integration](/docs/file-browser#git-integration)
- **Browser remote access** — [Ch. 21 — Cloud Portal](/docs/cloud-portal-docs)
- **Bug Reports** — [Ch. 17 §Filing a bug](/docs/licensing#filing-a-bug) | [Ch. 18 §Filing a useful bug report](/docs/troubleshooting#filing-a-useful-bug-report)
- **Bulk actions (Fleet)** — [Ch. 5 §Bulk actions](/docs/fleet#bulk-actions)
- **Buying a license** — [Ch. 17 §Buying a license](/docs/licensing#buying-a-license)
## C

- **"Connection refused" / "Connection timed out"** — [Ch. 18 §SSH and connections](/docs/troubleshooting#connection-refused-or-connection-timed-out)
- **CA (Certificate Authority)** — [Ch. 7 §Terms & Setup](/docs/security-tools#ca-root-ca-intermediate)
- **Camera Feed Grid** — [Ch. 10 §Feed Grid vs Grid Viewer](/docs/cameras#feed-grid-vs-grid-viewer)
- **Camera Grid Viewer** — [Ch. 10 §Feed Grid vs Grid Viewer](/docs/cameras#feed-grid-vs-grid-viewer)
- **Camera Manager** — [Ch. 10 §Camera Manager](/docs/cameras#camera-manager)
- **Capture buffer (network)** — [Ch. 13 §Network](/docs/settings-themes#network)
- **Certificate Inventory** — [Ch. 7 §Certificate Inventory](/docs/security-tools#certificate-inventory)
- **Chain of Thought (LCOT)** — [Ch. 4 §Why "Chain of Thought"?](/docs/lcot#why-chain-of-thought)
- **Cheat Sheet (quick reference)** — [Ch. 20](/docs/quick-reference)
- **Check for Updates** — [Ch. 17 §Checking for updates](/docs/licensing#checking-for-updates)
- **chmod +x (remote)** — [Ch. 3 §Remote file browser (SFTP)](/docs/file-browser#remote-file-browser-sftp)
- **CIDR notation** — [Ch. 6 §Terms & Setup](/docs/network-tools#cidr-notation)
- **CIS benchmark** — [Ch. 7 §Compliance Assessment](/docs/security-tools#compliance-assessment)
- **Classic layout** — [Ch. 16 §Classic layout](/docs/workspaces#classic-layout). The old Classic Tabs layout mode is retired; see [Go back to tabs](/docs/workspaces#go-back-to-tabs).
- **Claude Agent Manager** — [Ch. 8 §Claude Agent Manager](/docs/ai-assistant#claude-agent-manager-ctrlshiftm)
- **Claude models (Sonnet/Opus/Haiku)** — [Ch. 8 §Claude Agent Manager](/docs/ai-assistant#claude-agent-manager-ctrlshiftm)
- **CLI (Redis)** — [Ch. 11 §Redis Management](/docs/databases#redis-management)
- **CLI flags / command-line flags** — [Ch. 20 §Command-line flags](/docs/quick-reference#command-line-flags) | [Ch. 18 §Safe mode](/docs/troubleshooting#safe-mode)
- **Cloud Portal** — [Ch. 21 — Cloud Portal](/docs/cloud-portal-docs) | [Ch. 13 §Cloud Portal](/docs/settings-themes#cloud-portal)
- **Cloud Portal — tunnel down** — [Ch. 18 §Cloud Portal — tunnel down](/docs/troubleshooting#cloud-portal--tunnel-down)
- **Collaborator (permission group)** — [Ch. 21 §Permission groups in plain language](/docs/cloud-portal-docs#permission-groups-in-plain-language)
- **Command ID** — [Ch. 14 §Terms & Setup](/docs/shortcuts#command-id)
- **Command Palette** — [Ch. 14 §Command Palette](/docs/shortcuts#command-palette-ctrlshiftp)
- **Command Palette prefixes (`>` `@` `:`)** — [Ch. 14 §Command Palette tips](/docs/shortcuts#command-palette-tips) | [Ch. 20 §Default keyboard shortcuts (full table)](/docs/quick-reference#default-keyboard-shortcuts-full-table)
- **Comment line (`Ctrl+/`)** — [Ch. 14 §Edit shortcuts](/docs/shortcuts#edit)
- **Compliance Assessment** — [Ch. 7 §Compliance Assessment](/docs/security-tools#compliance-assessment)
- **Composer (Web Hierarchy)** — [Ch. 21 §Web Hierarchy Composer](/docs/cloud-portal-docs#web-hierarchy-composer) | [Ch. 9 §Web Composer](/docs/hierarchy-builder#web-composer-browser-version)
- **Composer parity gaps (web vs desktop)** — [Ch. 18 §Composer (web vs desktop) parity](/docs/troubleshooting#composer-web-vs-desktop-parity)
- **Config Dashboard (web)** — [Ch. 21 §Other web dashboards](/docs/cloud-portal-docs#other-web-dashboards)
- **Config Drift Detection** — [Ch. 12 §Configuration management](/docs/sysadmin#configuration-management)
- **Connection Manager** — [Ch. 2 §Connection Manager](/docs/ssh-devices#connection-manager)
- **Connection tab** — [Ch. 2 §Anatomy of a connection tab](/docs/ssh-devices#anatomy-of-a-connection-tab)
- **Connection timeout (SSH)** — [Ch. 13 §SSH](/docs/settings-themes#ssh)
- **Container Dashboard (web)** — [Ch. 21 §Other web dashboards](/docs/cloud-portal-docs#other-web-dashboards)
- **Containers** — see *Docker / Kubernetes*
- **Core updates** — see *Check for Updates*
- **Crash recovery (Hierarchy Builder)** — [Ch. 9 §Autosave & crash recovery](/docs/hierarchy-builder#autosave--crash-recovery)
- **Create New Plugin/Widget** — [Ch. 15 §Creating a plugin](/docs/plugins#creating-a-plugin-or-widget)
- **Crosshair (virtual cursor)** — see *AidaVirtualCursor*
- **Customer Portal** — [Ch. 17 §License Status](/docs/licensing#license-status)
- **CVE Scanner** — [Ch. 7 §CVE Scanner](/docs/security-tools#cve-scanner)
- **CVSS score** — [Ch. 7 §Terms & Setup](/docs/security-tools#cvss)
## D

- **"Demo mode" output** — [Ch. 18 §"Demo mode" vs real data](/docs/troubleshooting#demo-mode-vs-real-data)
- **Dashboard (Device)** — [Ch. 5 §Device Dashboard](/docs/fleet#device-dashboard)
- **Database Manager** — [Ch. 11 §Database Manager](/docs/databases#database-manager)
- **DB Connection Manager** — [Ch. 11 §Saving connections](/docs/databases#saving-connections)
- **Debug Console** — [Ch. 13 §Debug Console](/docs/settings-themes#debug-console-ctrlshiftd) | [Ch. 18 §Diagnostics you can run yourself](/docs/troubleshooting#diagnostics-you-can-run-yourself)
- **Default port (SSH)** — [Ch. 13 §SSH](/docs/settings-themes#ssh) | [Ch. 2 §Ports and the port-22 trap](/docs/ssh-devices#ports-and-the-port-22-trap)
- **Dependency Scanner** — [Ch. 7 §Dependency Scanner](/docs/security-tools#dependency-scanner)
- **Deploy ESP32** — see *Deploy Lite*
- **Deploy Lite** — [Ch. 5 §Deploy Lite](/docs/fleet#deploy-lite)
- **Desired State Configuration (DSC)** — [Ch. 12 §Configuration management](/docs/sysadmin#configuration-management)
- **Device binding (license)** — [Ch. 17 §Device binding](/docs/licensing#device-binding)
- **Device Dashboard** — [Ch. 5 §Device Dashboard](/docs/fleet#device-dashboard)
- **Device detail page (Cloud Portal)** — [Ch. 21 §The device detail page](/docs/cloud-portal-docs#the-device-detail-page)
- **Device enrolment** — [Ch. 21 §Registering a device](/docs/cloud-portal-docs#registering-a-device) | [Ch. 21 §Terms](/docs/cloud-portal-docs#device-enrolment)
- **Device Setup Wizard** — [Ch. 1 §First-run wizards](/docs/getting-started#first-run-wizards)
- **Diagnostics (self-serve)** — [Ch. 18 §Diagnostics you can run yourself](/docs/troubleshooting#diagnostics-you-can-run-yourself)
- **Diff Viewer** — [Ch. 3 §Diff Viewer](/docs/file-browser#diff-viewer)
- **Direct Touch mode** — [Ch. 22 §Touch modes](/docs/input-devices#touch-modes)
- **Disaster Recovery** — [Ch. 12 §Backup & disaster recovery](/docs/sysadmin#backup--disaster-recovery)
- **Disconnect (active session)** — [Ch. 21 §The Access panel](/docs/cloud-portal-docs#the-access-panel)
- **Disconnect / Reconnect (DB)** — [Ch. 11 §Database Manager](/docs/databases#database-manager)
- **Discover Devices** — [Ch. 5 §Discover Devices](/docs/fleet#discover-devices)
- **Display settings** — [Ch. 13 §Display settings](/docs/settings-themes#display-settings)
- **DNS resolver** — [Ch. 13 §Network](/docs/settings-themes#network)
- **Docker Compose** — [Ch. 12 §Containers](/docs/sysadmin#containers)
- **Docker Manager** — [Ch. 12 §Containers](/docs/sysadmin#containers)
- **Double tap (touch)** — [Ch. 22 §Gesture vocabulary](/docs/input-devices#gesture-vocabulary)
- **DPI scaling** — [Ch. 13 §Multi-monitor + DPI](/docs/settings-themes#multi-monitor--dpi)
- **Drafts (Hierarchy Builder)** — [Ch. 9 §Autosave & crash recovery](/docs/hierarchy-builder#autosave--crash-recovery)
- **Drag-and-drop (file transfer)** — [Ch. 3 §Remote file browser (SFTP)](/docs/file-browser#remote-file-browser-sftp)
## E

- **Edge swipe (top)** — [Ch. 22 §Gesture vocabulary](/docs/input-devices#gesture-vocabulary)
- **Editor** — [Ch. 3](/docs/file-browser)
- **Editor font** — [Ch. 13 §Font and spacing](/docs/settings-themes#font-and-spacing)
- **Enable Cloud Access (Settings)** — [Ch. 13 §Cloud Portal](/docs/settings-themes#cloud-portal) | [Ch. 21 §Registering a device](/docs/cloud-portal-docs#registering-a-device)
- **Encoding (UTF-8)** — [Ch. 3 §Encoding (UTF-8)](/docs/file-browser#encoding-utf-8) | [Ch. 13 §Behaviour](/docs/settings-themes#behaviour)
- **Encryption profile** — [Ch. 13 §Security](/docs/settings-themes#security)
- **Enter License Key** — [Ch. 17 §Activating your license](/docs/licensing#activating-your-license)
- **Environment variables (AIDA_SPLASH, AIDA_LOG_DIR, etc.)** — [Ch. 20 §Environment variables](/docs/quick-reference#environment-variables)
- **ESP32** — [Ch. 5 §Deploy Lite](/docs/fleet#deploy-lite)
- **EU jurisdiction (R2)** — [Ch. 17 §EU/data-residency note](/docs/licensing#eudata-residency-note)
- **Experimental Features** — [Ch. 13 §Experimental Features](/docs/settings-themes#experimental-features)
- **Export chapter as PDF (Ctrl+Shift+E)** — [Ch. 14 §User Guide viewer (Help → User Guide)](/docs/shortcuts#user-guide-viewer-help--user-guide)
- **Export query results** — [Ch. 11 §"Export a query result to my team"](/docs/databases#export-a-query-result-to-my-team)
- **Export whole guide as one PDF (Ctrl+Shift+G)** — [Ch. 14 §User Guide viewer (Help → User Guide)](/docs/shortcuts#user-guide-viewer-help--user-guide)
## F

- **F1-F12 (on-screen)** — [Ch. 22 §The mobile shortcut bar](/docs/input-devices#the-mobile-shortcut-bar)
- **F5 (Run file / Run query)** — [Ch. 14 §Editor shortcuts](/docs/shortcuts#editor) | [Ch. 11 §Query Editor](/docs/databases#query-editor) | [Ch. 20 §Default keyboard shortcuts](/docs/quick-reference#default-keyboard-shortcuts-full-table)
- **F8 (Run selection in SQL)** — [Ch. 11 §Query Editor](/docs/databases#query-editor) | [Ch. 20 §Default keyboard shortcuts](/docs/quick-reference#default-keyboard-shortcuts-full-table)
- **Feature Browser** — [Ch. 14 §Feature Browser](/docs/shortcuts#feature-browser)
- **Feature tab** — [Ch. 1 §What you see](/docs/getting-started#what-you-see)
- **File menu** — [Ch. 1 §Menu bar](/docs/getting-started#menu-bar)
- **File paths (vault.enc, layouts/, logs/, etc.)** — [Ch. 20 §File and directory paths](/docs/quick-reference#file-and-directory-paths)
- **Find / Find in Files** — [Ch. 3 §Find and Find in Files](/docs/file-browser#find-and-find-in-files)
- **First-run wizard** — [Ch. 1 §First-run wizards](/docs/getting-started#first-run-wizards)
- **Fleet Manager** — [Ch. 5 §Fleet Manager](/docs/fleet#fleet-manager)
- **Floating panels** — [Ch. 16 §Floating panels](/docs/workspaces#floating-panels)
- **Fly.io (Cloud Portal deploy)** — [Ch. 21 §Self-hosting the portal](/docs/cloud-portal-docs#self-hosting-the-portal)
- **Forgot password (vault)** — [Ch. 1 §Unlocking the vault](/docs/getting-started#unlocking-the-vault)
- **Format on save** — [Ch. 3 §Editor features](/docs/file-browser#editor-features-worth-knowing)
- **Format SQL** — [Ch. 11 §Query Editor](/docs/databases#query-editor) (`Ctrl+Shift+F`)
- **Freeze (UI hang)** — [Ch. 18 §The UI freezes for a few seconds at a time](/docs/troubleshooting#the-ui-freezes-for-a-few-seconds-at-a-time)
## G

- **Gamepad (browser)** — [Ch. 22 §"I do not have a gamepad yet" — Gamepad API](/docs/input-devices#i-do-not-have-a-gamepad-yet--gamepad-api)
- **General settings** — [Ch. 13 §General](/docs/settings-themes#general)
- **Gesture (touch)** — [Ch. 22 §Gesture vocabulary](/docs/input-devices#gesture-vocabulary)
- **Ghost text (AI inline)** — [Ch. 8 §Toggle Inline Suggestions](/docs/ai-assistant#toggle-inline-suggestions) | [Ch. 18 §Ghost text appears in the wrong place](/docs/troubleshooting#ghost-text-appears-in-the-wrong-place)
- **Git Manager** — [Ch. 3 §Git integration](/docs/file-browser#git-integration)
- **Git Pull / Push / Status** — [Ch. 3 §Git integration](/docs/file-browser#git-integration)
- **Glossary** — [Ch. 19](/docs/glossary)
- **Go to Line** — [Ch. 3 §Find and Find in Files](/docs/file-browser#find-and-find-in-files)
- **Grid Layout (retired)** — rc18 replaced the per-tab Grid Layout mode. Old grid layouts are not carried over. [Ch. 16 §Go back to tabs](/docs/workspaces#go-back-to-tabs)
- **Groups (Connection Manager)** — [Ch. 2 §Grouping hosts](/docs/ssh-devices#grouping-hosts)
- **Groups (Fleet)** — [Ch. 5 §Groups](/docs/fleet#groups)
- **Guest Pass** — [Ch. 21 §Inviting a guest](/docs/cloud-portal-docs#inviting-a-guest) | [Ch. 21 §Terms](/docs/cloud-portal-docs#guest-pass)
- **Guest pass claim fails** — [Ch. 18 §Guest pass claim fails](/docs/troubleshooting#guest-pass-claim-fails)
- **Guided Tour** — see *Ask Macy*
## H

- **"Host key has changed!"** — [Ch. 18 §"Host key has changed!"](/docs/troubleshooting#host-key-has-changed)
- **Hardware Lab** — [Ch. 23](/docs/hardware-lab); citation-ready definition [/guides/hardware-lab](/guides/hardware-lab)
- **HIL (virtual)** — see *Hardware Lab* — not Fleet Test Panel
- **Haptic (vibrate on mode switch)** — [Ch. 22 §Touch modes](/docs/input-devices#touch-modes)
- **Heartbeat (presence)** — [Ch. 22 §Terms](/docs/input-devices#heartbeat-presence)
- **Help menu** — [Ch. 17 §Help menu](/docs/licensing#help-menu)
- **Hidden commands (LCOT)** — [Ch. 4 §Hidden commands](/docs/lcot#terms--setup) | [Ch. 13 §LCOT](/docs/settings-themes#lcot)
- **Hierarchy Builder** — [Ch. 9](/docs/hierarchy-builder)
- **Host Discovery** — [Ch. 6 §Host Discovery](/docs/network-tools#host-discovery)
- **Host key** — [Ch. 2 §Terms & Setup](/docs/ssh-devices#host-key)
- **HTTP proxy** — [Ch. 13 §Network](/docs/settings-themes#network) | [Ch. 17 §"My license stopped working"](/docs/licensing#my-license-stopped-working)
## I

- **"Invalid API key"** — [Ch. 18 §"Invalid API key"](/docs/troubleshooting#invalid-api-key)
- **IC (Integrated Circuit)** — [Ch. 9 §Component library](/docs/hierarchy-builder#component-library)
- **Import (Connection Manager from SSH config)** — [Ch. 2 §Importing existing SSH config](/docs/ssh-devices#importing-existing-ssh-config)
- **Import / Export bindings** — [Ch. 14 §Importing / exporting](/docs/shortcuts#importing--exporting)
- **Industrial PLC** — [Ch. 5 §PLC Monitor](/docs/fleet#plc-monitor) | [Ch. 5 §"Industrial PLC: how do I find my register addresses?"](/docs/fleet#industrial-plc-how-do-i-find-my-register-addresses)
- **Inline images (User Guide viewer)** — [Ch. 14 §User Guide viewer (Help → User Guide)](/docs/shortcuts#user-guide-viewer-help--user-guide)
- **Inline Suggestions (AI)** — [Ch. 8 §Toggle Inline Suggestions](/docs/ai-assistant#toggle-inline-suggestions) | [Ch. 18 §Inline suggestions appear in unrelated files](/docs/troubleshooting#inline-suggestions-appear-in-unrelated-files)
- **Input devices (browser RD)** — [Ch. 22 — Input Devices in the Browser](/docs/input-devices)
- **Intel Panel** — [Ch. 2 §Anatomy of a connection tab](/docs/ssh-devices#anatomy-of-a-connection-tab)
- **Invite a guest** — [Ch. 21 §Inviting a guest](/docs/cloud-portal-docs#inviting-a-guest)
- **IOC Database** — [Ch. 7 §IOC Database](/docs/security-tools#ioc-database)
- **IP Access Control** — [Ch. 7 §IP Access Control](/docs/security-tools#ip-access-control)
## J

- **JSON (workspace files)** — [Ch. 16 §"How do I share a workspace with a teammate?"](/docs/workspaces#how-do-i-share-a-workspace-with-a-teammate)
- **JSON (settings)** — [Ch. 13 §Where settings persist](/docs/settings-themes#where-settings-persist)

## K

- **Keepalive interval (SSH)** — [Ch. 13 §SSH](/docs/settings-themes#ssh)
- **Key file / passphrase** — [Ch. 2 §Authentication](/docs/ssh-devices#authentication)
- **Key permissions errors** — [Ch. 2 §Key permissions errors](/docs/ssh-devices#key-permissions-errors)
- **Keybinding context** — [Ch. 14 §Keybinding context](/docs/shortcuts#keybinding-context)
- **Keyboard layout (en-US / GB / de / fr / es)** — [Ch. 22 §International keyboard layouts](/docs/input-devices#international-keyboard-layouts)
- **Keyboard Shortcuts editor** — [Ch. 14 §Customising shortcuts](/docs/shortcuts#customising-shortcuts)
- **Known hosts file** — [Ch. 13 §SSH](/docs/settings-themes#ssh)
- **Kubernetes Client** — [Ch. 12 §Containers](/docs/sysadmin#containers)
## L

- **Layout (keyboard)** — [Ch. 22 §Terms](/docs/input-devices#layout-keyboard)
- **Layout Mode (retired)** — Grid vs Classic Tabs is gone. [Ch. 16 §Go back to tabs](/docs/workspaces#go-back-to-tabs)
- **Layout Presets (retired)** — No bundled presets. Named layouts: [Ch. 16 §Save named layouts](/docs/workspaces#save-named-layouts)
- **Layout Wizard (retired)** — The sparkle wizard is gone. Save a named layout from the toolbar **Workspace** list. [Ch. 16 §Save named layouts](/docs/workspaces#save-named-layouts)
- **LCOT Panel** — [Ch. 4](/docs/lcot)
- **LDAP / LDAPS** — [Ch. 12 §Terms & Setup](/docs/sysadmin#ldap--ldaps)
- **License gating (AI features)** — [Ch. 8 §License gating](/docs/ai-assistant#license-gating)
- **License key format** — [Ch. 17 §Terms & Setup](/docs/licensing#license-key-format)
- **License Status** — [Ch. 17 §License Status](/docs/licensing#license-status)
- **License will not activate** — [Ch. 18 §License will not activate](/docs/troubleshooting#license-will-not-activate)
- **Linting** — [Ch. 3 §Editor features](/docs/file-browser#editor-features-worth-knowing)
- **Live Coding Agents** — [Ch. 8 §Live Coding Agents](/docs/ai-assistant#live-coding-agents-ctrlshiftj)
- **Loading Splash** — [Ch. 1 §Splash screen](/docs/getting-started#splash-screen)
- **Local file browser** — [Ch. 3 §Local file browser](/docs/file-browser#local-file-browser)
- **Local model (Ollama)** — [Ch. 8 §"I don't have an API key yet" — setup paths](/docs/ai-assistant#i-dont-have-an-api-key-yet--setup-paths)
- **Logs** — [Ch. 17 §Logs](/docs/licensing#logs)
- **Long press (touch right-click)** — [Ch. 22 §Gesture vocabulary](/docs/input-devices#gesture-vocabulary)
- **Loopback testing (`127.0.0.1`)** — [Ch. 6 §"I don't have a network to scan" — practice without disturbing real hosts](/docs/network-tools#i-dont-have-a-network-to-scan--practice-without-disturbing-real-hosts)
## M

- **Marketplace Store** — [Ch. 15 §Marketplace Store](/docs/plugins#marketplace-store)
- **Master password** — [Ch. 1 §Unlocking the vault](/docs/getting-started#unlocking-the-vault)
- **Menu bar** — [Ch. 1 §Menu bar](/docs/getting-started#menu-bar)
- **Metrics Collector** — [Ch. 12 §Monitoring & alerts](/docs/sysadmin#monitoring--alerts)
- **Minimap** — [Ch. 9 §Navigation and tools](/docs/hierarchy-builder#navigation-and-tools)
- **Mobile shortcut bar** — [Ch. 22 §The mobile shortcut bar](/docs/input-devices#the-mobile-shortcut-bar)
- **Modifier latch (Ctrl/Alt/Shift)** — [Ch. 22 §The mobile shortcut bar](/docs/input-devices#the-mobile-shortcut-bar)
- **Module (Hierarchy Builder)** — [Ch. 9 §Component library](/docs/hierarchy-builder#component-library)
- **Mojibake (UTF-8 mismatch)** — [Ch. 18 §File browser, editor, save](/docs/troubleshooting#file-browser-editor-save)
- **MongoDB Management** — [Ch. 11 §Per-engine tabs](/docs/databases#per-engine-tabs)
- **Monitoring Dashboard** — [Ch. 12 §Monitoring & alerts](/docs/sysadmin#monitoring--alerts)
- **Mouse gestures** — [Ch. 14 §Mouse gestures](/docs/shortcuts#mouse-gestures)
- **Multi-cursor** — [Ch. 3 §Cursor and selection](/docs/file-browser#cursor-and-selection)
- **Multi-monitor** — [Ch. 13 §Multi-monitor + DPI](/docs/settings-themes#multi-monitor--dpi)
- **Multi-port agents (roadmap)** — [Ch. 9 §Multi-port agents — coming](/docs/hierarchy-builder#multi-port-agents--coming)
- **Multi-window** — [Ch. 16 §Multi-window](/docs/workspaces#multi-window)
- **My Devices (portal)** — [Ch. 21 §Logging in](/docs/cloud-portal-docs#logging-in)
- **MySQL Management** — [Ch. 11 §Per-engine tabs](/docs/databases#per-engine-tabs)
## N

- **Named layouts** — [Ch. 16 §Save named layouts](/docs/workspaces#save-named-layouts)
- **Network Diagnostics** — [Ch. 6 §Network Diagnostics](/docs/network-tools#network-diagnostics)
- **Network Topology** — [Ch. 6 §Network Topology](/docs/network-tools#network-topology)
- **Network (no LAN to scan)** — [Ch. 6 §"I don't have a network to scan" — practice without disturbing real hosts](/docs/network-tools#i-dont-have-a-network-to-scan--practice-without-disturbing-real-hosts)
- **New Tab** — [Ch. 2 §Opening a new connection](/docs/ssh-devices#opening-a-new-connection)
- **"No API key yet"** — [Ch. 8 §"I don't have an API key yet" — setup paths](/docs/ai-assistant#i-dont-have-an-api-key-yet--setup-paths)
- **"No device yet"** — [Ch. 5 §"I don't have a device yet"](/docs/fleet#i-dont-have-a-device-yet)
- **"No SSH server yet"** — [Ch. 2 §"I do not have an SSH server" — setup paths](/docs/ssh-devices#i-do-not-have-an-ssh-server--setup-paths)
- **Notifications (SMTP / Slack / Webhook)** — [Ch. 13 §Network](/docs/settings-themes#network)
- **Npcap (Windows Packet Capture)** — [Ch. 20 §Platform-specific notes](/docs/quick-reference#windows)
- **Notify (web link)** — *Retired. AidaIDE is now free forever; Pro ($19/mo) adds the AI suite.* See [Ch. 17 §Buying a license](/docs/licensing#buying-a-license).

## O

- **OIDC (OpenID Connect)** — [Ch. 21 §Logging in](/docs/cloud-portal-docs#logging-in) | [Ch. 21 §Terms](/docs/cloud-portal-docs#oidc-openid-connect)
- **Ollama (local AI)** — [Ch. 8 §Terms & Setup](/docs/ai-assistant#api-key) | [Ch. 8 §"I don't have an API key yet" — setup paths](/docs/ai-assistant#i-dont-have-an-api-key-yet--setup-paths)
- **Onboarding Wizard** — [Ch. 1 §First-run wizards](/docs/getting-started#first-run-wizards)
- **ONVIF discovery** — [Ch. 10 §Scanning for cameras](/docs/cameras#scanning-for-cameras)
- **Open Project Folder** — [Ch. 3 §Opening files and projects](/docs/file-browser#opening-files-and-projects)
- **OpenSSH (server setup)** — [Ch. 2 §"I do not have an SSH server" — setup paths](/docs/ssh-devices#i-do-not-have-an-ssh-server--setup-paths)
- **OS fingerprinting** — [Ch. 6 §Terms & Setup](/docs/network-tools#os-fingerprinting)
- **OTA signing keys** — [Ch. 5 §Signing keys](/docs/fleet#signing-keys)
- **OTA Update Manager** — [Ch. 5 §OTA Update Manager](/docs/fleet#ota-update-manager)
- **Owner (permission group)** — [Ch. 21 §Permission groups in plain language](/docs/cloud-portal-docs#permission-groups-in-plain-language)
## P

- **"Permission denied (publickey)"** — [Ch. 18 §"Permission denied (publickey)"](/docs/troubleshooting#permission-denied-publickey)
- **.plugin file** — [Ch. 15 §Terms & Setup](/docs/plugins#plugin-file)
- **Packet Capture** — [Ch. 6 §Packet Capture](/docs/network-tools#packet-capture)
- **Page-break-before-H1 (whole-guide PDF)** — [Ch. 14 §User Guide viewer (Help → User Guide)](/docs/shortcuts#user-guide-viewer-help--user-guide)
- **Pass (Guest)** — see *Guest Pass*
- **Patch Manager / Patch Policies** — [Ch. 12 §Patch management](/docs/sysadmin#patch-management)
- **pcap** — [Ch. 6 §Terms & Setup](/docs/network-tools#pcap)
- **PDF export of a chapter** — [Ch. 14 §User Guide viewer (Help → User Guide)](/docs/shortcuts#user-guide-viewer-help--user-guide)
- **PDF export of the whole guide (single document)** — [Ch. 14 §User Guide viewer (Help → User Guide)](/docs/shortcuts#user-guide-viewer-help--user-guide)
- **Performance Monitor** — [Ch. 13 §Performance Monitor](/docs/settings-themes#performance-monitor) | [Ch. 18 §Performance](/docs/troubleshooting#performance)
- **Permanent collaborators** — [Ch. 21 §The Access panel](/docs/cloud-portal-docs#the-access-panel)
- **Permission group** — [Ch. 21 §Permission groups in plain language](/docs/cloud-portal-docs#permission-groups-in-plain-language)
- **Permissions (widgets)** — [Ch. 15 §Widget permissions](/docs/plugins#widget-permissions)
- **Persona Portal** — [Ch. 8 §Persona Portal](/docs/ai-assistant#persona-portal)
- **Pinch (client-side zoom)** — [Ch. 22 §Gesture vocabulary](/docs/input-devices#gesture-vocabulary)
- **Pinning tabs** — [Ch. 16 §Pinning tabs](/docs/workspaces#pinning-tabs)
- **Pipeline (Hierarchy Builder)** — [Ch. 9 §Running a pipeline](/docs/hierarchy-builder#running-a-pipeline)
- **PKI Manager** — [Ch. 7 §PKI Manager](/docs/security-tools#pki-manager)
- **Platform notes (Windows / macOS / Linux)** — [Ch. 20 §Platform-specific notes](/docs/quick-reference#platform-specific-notes)
- **PLC Monitor** — [Ch. 5 §PLC Monitor](/docs/fleet#plc-monitor)
- **Plugin & Widget Manager** — [Ch. 15 §Plugin and Widget Manager](/docs/plugins#plugin-and-widget-manager)
- **Port Scanner** — [Ch. 6 §Port Scanner](/docs/network-tools#port-scanner)
- **Portal (Cloud)** — see *Cloud Portal*
- **Ports (default — SSH, DB, OTA, RTSP, etc.)** — [Ch. 20 §Default ports and endpoints](/docs/quick-reference#default-ports-and-endpoints)
- **PostgreSQL Management** — [Ch. 11 §Per-engine tabs](/docs/databases#per-engine-tabs)
- **Presence (other watchers)** — [Ch. 22 §Presence and spectate](/docs/input-devices#presence-and-spectate)
- **Preview menu** — [Ch. 1 §Menu bar](/docs/getting-started#menu-bar)
- **Pricing tiers** — [Ch. 17 §Buying a license](/docs/licensing#buying-a-license) | [Ch. 20 §Pricing tiers at a glance](/docs/quick-reference#pricing-tiers-at-a-glance)
- **Privacy notes (AI)** — [Ch. 8 §Privacy notes](/docs/ai-assistant#privacy-notes)
- **Privileges (DB safety)** — [Ch. 11 §Privileges and safety](/docs/databases#privileges-and-safety)
- **Project from Template** — [Ch. 3 §Opening files and projects](/docs/file-browser#opening-files-and-projects) | [Ch. 3 §Project templates available](/docs/file-browser#project-templates-available)
- **Project root** — [Ch. 3 §Terms & Setup](/docs/file-browser#project-root)
- **Prompt-host approval** — [Ch. 21 §Permission groups in plain language](/docs/cloud-portal-docs#permission-groups-in-plain-language) | [Ch. 21 §Terms](/docs/cloud-portal-docs#prompt-host)
- **Protocol Wizard** — [Ch. 5 §Protocol Wizard](/docs/fleet#protocol-wizard)
- **Public key vs private key** — [Ch. 2 §Terms & Setup](/docs/ssh-devices#public-key-vs-private-key)
## Q

- **Query Editor** — [Ch. 11 §Query Editor](/docs/databases#query-editor)
- **Quick Push (Git)** — [Ch. 3 §Git integration](/docs/file-browser#git-integration)
- **Quick Reference / Cheat Sheet** — [Ch. 20](/docs/quick-reference)
- **Quick Toolkit (Sysadmin)** — [Ch. 4 §Sysadmin Quick Toolkit](/docs/lcot#sysadmin-quick-toolkit)
- **QWERTZ (German keyboard)** — [Ch. 22 §International keyboard layouts](/docs/input-devices#international-keyboard-layouts)
## R

- **RD PIN** — [Ch. 21 §Remote Desktop in the browser](/docs/cloud-portal-docs#remote-desktop-in-the-browser) | [Ch. 18 §Cloud Portal — RD PIN issues](/docs/troubleshooting#cloud-portal--rd-pin-issues)
- **READ scripts (LCOT)** — [Ch. 4 §READ vs WRITE zones](/docs/lcot#read-vs-write-zones)
- **Read-Only (permission group)** — [Ch. 21 §Permission groups in plain language](/docs/cloud-portal-docs#permission-groups-in-plain-language)
- **Recent Connections** — [Ch. 16 §Recent things](/docs/workspaces#recent-things) | [Ch. 2 §Recent connections](/docs/ssh-devices#recent-connections)
- **Recent Files** — [Ch. 16 §Recent things](/docs/workspaces#recent-things)
- **Recording (cameras)** — [Ch. 10 §Recording](/docs/cameras#recording)
- **Recurring trap** — [Ch. 18 §Recurring trap](/docs/troubleshooting#recurring-trap) | [Ch. 19 Glossary](/docs/glossary#r) | [Ch. 20 §Recurring traps to be aware of](/docs/quick-reference#recurring-traps-to-be-aware-of)
- **Redis Management** — [Ch. 11 §Per-engine tabs](/docs/databases#per-engine-tabs)
- **Registry Client (Docker)** — [Ch. 12 §Containers](/docs/sysadmin#containers)
- **Remote Desktop (browser)** — [Ch. 21 §Remote Desktop in the browser](/docs/cloud-portal-docs#remote-desktop-in-the-browser)
- **Remote file browser** — [Ch. 3 §Remote file browser (SFTP)](/docs/file-browser#remote-file-browser-sftp)
- **Replace (Find/Replace)** — [Ch. 3 §Find and Find in Files](/docs/file-browser#find-and-find-in-files)
- **Reset section to defaults** — [Ch. 13 §"I changed something and it broke"](/docs/settings-themes#i-changed-something-and-it-broke)
- **Reset vault** — [Ch. 1 §Unlocking the vault](/docs/getting-started#unlocking-the-vault)
- **Revoke (Guest Pass)** — [Ch. 21 §Inviting a guest](/docs/cloud-portal-docs#inviting-a-guest)
- **Roadmap** — [Ch. 17 §Roadmap pointers (subject to change)](/docs/licensing#roadmap-pointers-subject-to-change)
- **RTSP** — [Ch. 10 §Terms & Setup](/docs/cameras#rtsp)
- **Run (file / SQL)** — [Ch. 3 §Running files](/docs/file-browser#running-files) | [Ch. 11 §Query Editor](/docs/databases#query-editor)
- **Run (Hierarchy Builder)** — [Ch. 9 §Running a pipeline](/docs/hierarchy-builder#running-a-pipeline)
- **Run panel** — [Ch. 3 §Terms & Setup](/docs/file-browser#run-panel)
## S

- **--safe-mode (launch flag)** — [Ch. 17 §"AidaIDE will not start after an update"](/docs/licensing#aidaide-will-not-start-after-an-update) | [Ch. 18 §Safe mode](/docs/troubleshooting#safe-mode)
- **SAST Scanner** — [Ch. 7 §SAST Scanner](/docs/security-tools#sast-scanner)
- **SAST vs DAST** — [Ch. 7 §Terms & Setup](/docs/security-tools#sast-vs-dast)
- **Save Chat Session** — [Ch. 8 §Saving and loading sessions](/docs/ai-assistant#saving-and-loading-sessions)
- **Save did not persist (remote)** — [Ch. 18 §Save to a remote file appears to succeed but the file did not change](/docs/troubleshooting#save-to-a-remote-file-appears-to-succeed-but-the-file-did-not-change)
- **Save layout** — [Ch. 16 §Save named layouts](/docs/workspaces#save-named-layouts)
- **Scan for Cameras** — [Ch. 10 §Scanning for cameras](/docs/cameras#scanning-for-cameras)
- **Scroll mode (touch)** — [Ch. 22 §Touch modes](/docs/input-devices#touch-modes)
- **Secret Scanner** — [Ch. 7 §Secret Scanner](/docs/security-tools#secret-scanner)
- **Security Scanner** — [Ch. 7 §Security Scanner](/docs/security-tools#security-scanner)
- **Self-hosting (Cloud Portal)** — [Ch. 21 §Self-hosting the portal](/docs/cloud-portal-docs#self-hosting-the-portal)
- **Serial Monitor** — [Ch. 5 §Serial Monitor](/docs/fleet#serial-monitor)
- **Service Detection** — [Ch. 6 §Service Detection](/docs/network-tools#service-detection)
- **Sessions (active)** — [Ch. 21 §The Access panel](/docs/cloud-portal-docs#the-access-panel)
- **Settings dialog** — [Ch. 13](/docs/settings-themes)
- **Setup Wizard** — see *First-run wizard*
- **SFTP** — [Ch. 2 §Terms & Setup](/docs/ssh-devices#sftp) | [Ch. 3 §Remote file browser (SFTP)](/docs/file-browser#remote-file-browser-sftp)
- **Shortcut bar (mobile)** — see *Mobile shortcut bar*
- **Shortcuts Editor** — [Ch. 14 §Customising shortcuts](/docs/shortcuts#customising-shortcuts)
- **Sidebar (AI)** — [Ch. 8 §AI sidebar vs AI tabs](/docs/ai-assistant#ai-sidebar-vs-ai-tabs)
- **SignalFlowEngine** — [Ch. 9 §Terms & Setup](/docs/hierarchy-builder#signalflowengine)
- **Smart Login** — [Ch. 1 §Unlocking the vault](/docs/getting-started#unlocking-the-vault)
- **SoC (System on Chip)** — [Ch. 9 §Component library](/docs/hierarchy-builder#component-library)
- **Soft-restart bypass** — [Ch. 1 §Soft-restart bypass](/docs/getting-started#soft-restart-bypass)
- **Spectate (follow another watcher)** — [Ch. 22 §Presence and spectate](/docs/input-devices#presence-and-spectate)
- **Splash screen** — [Ch. 1 §Splash screen](/docs/getting-started#splash-screen)
- **Split panes (editor)** — [Ch. 3 §Split panes](/docs/file-browser#split-panes)
- **SQLite (Beta)** — [Ch. 11 §"I do not have a database to play with"](/docs/databases#i-do-not-have-a-database-to-play-with)
- **SSH (Secure Shell)** — [Ch. 2 §Terms & Setup](/docs/ssh-devices#ssh-secure-shell)
- **SSH key manager** — [Ch. 2 §Keys vs passwords](/docs/ssh-devices#keys-vs-passwords)
- **SSH key pair (setup)** — [Ch. 2 §Setting up your first SSH key pair](/docs/ssh-devices#setting-up-your-first-ssh-key-pair)
- **SSH Port** — [Ch. 2 §Ports and the port-22 trap](/docs/ssh-devices#ports-and-the-port-22-trap)
- **Status bar** — [Ch. 1 §What you see](/docs/getting-started#what-you-see) | [Ch. 3 §Line endings](/docs/file-browser#editor-features-worth-knowing)
- **Substream (cameras)** — [Ch. 10 §Terms & Setup](/docs/cameras#substream)
- **Symptom-first lookup** — [Ch. 18 — Troubleshooting & FAQ](/docs/troubleshooting)
- **Sysadmin** — [Ch. 12](/docs/sysadmin)
## T

- **Tab (panel)** — In the workbench every tab is a panel. [Ch. 16](/docs/workspaces)
- **Tab management** — [Ch. 16 §Tab management](/docs/workspaces#tab-management)
- **Telemetry** — [Ch. 13 §General](/docs/settings-themes#general)
- **Template Manager** — [Ch. 12 §Configuration management](/docs/sysadmin#configuration-management)
- **Templates (project)** — [Ch. 3 §Opening files and projects](/docs/file-browser#opening-files-and-projects)
- **Terminal (in connection tab)** — [Ch. 2 §Anatomy of a connection tab](/docs/ssh-devices#anatomy-of-a-connection-tab)
- **Terminal type (xterm-256color)** — [Ch. 13 §SSH](/docs/settings-themes#ssh)
- **Test connection (AI)** — [Ch. 8 §Claude Agent Manager](/docs/ai-assistant#claude-agent-manager-ctrlshiftm)
- **Test Panel** — [Ch. 5 §Test Panel](/docs/fleet#test-panel)
- **Theme** — [Ch. 13 §Themes and appearance](/docs/settings-themes#themes-and-appearance)
- **Threat Intel Feeds** — [Ch. 7 §Threat Intel Feeds](/docs/security-tools#threat-intel-feeds)
- **Three-finger tap (toggle keyboard)** — [Ch. 22 §Gesture vocabulary](/docs/input-devices#gesture-vocabulary)
- **TLS (databases)** — [Ch. 11 §Terms & Setup](/docs/databases#tls)
- **Toolbar** — [Ch. 1 §Toolbar](/docs/getting-started#toolbar)
- **Touch mode pill** — [Ch. 22 §Touch modes](/docs/input-devices#touch-modes)
- **Trace mode (Hierarchy Builder)** — [Ch. 9 §Terms & Setup](/docs/hierarchy-builder#trace-mode)
- **Trackpad mode (touch)** — [Ch. 22 §Touch modes](/docs/input-devices#touch-modes)
- **Traffic Analyzer** — [Ch. 6 §Traffic Analyzer](/docs/network-tools#traffic-analyzer)
- **Troubleshooting** — [Ch. 18 — Troubleshooting & FAQ](/docs/troubleshooting)
- **Trusted (permission group)** — [Ch. 21 §Permission groups in plain language](/docs/cloud-portal-docs#permission-groups-in-plain-language)
- **Trusted authors (plugins)** — [Ch. 15 §Terms & Setup](/docs/plugins#trusted-authors)
- **Tunnel down (Cloud Portal)** — [Ch. 18 §Cloud Portal — tunnel down](/docs/troubleshooting#cloud-portal--tunnel-down)
- **Tunnel gateway** — [Ch. 21 §Terms](/docs/cloud-portal-docs#tunnel-gateway)
- **Two-finger tap (right-click)** — [Ch. 22 §Gesture vocabulary](/docs/input-devices#gesture-vocabulary)
## U

- **Uninstalling AidaIDE** — [Ch. 17 §Uninstalling](/docs/licensing#uninstalling)
- **Unlock (vault)** — [Ch. 1 §Unlocking the vault](/docs/getting-started#unlocking-the-vault)
- **Updates (check)** — [Ch. 17 §Checking for updates](/docs/licensing#checking-for-updates)
- **Update channels (stable/beta/nightly)** — [Ch. 17 §Update channels](/docs/licensing#update-channels)
- **Update history (rollback)** — [Ch. 17 §Update history & rollback](/docs/licensing#update-history--rollback)
- **Upgrade plan** — [Ch. 17 §Licensing](/docs/licensing#licensing)
- **USB camera (local webcam)** — [Ch. 10 §"I do not have a camera yet"](/docs/cameras#i-do-not-have-a-camera-yet--setup-paths)
- **User Guide (Help menu)** — [Ch. 17 §Support and feedback](/docs/licensing#support-and-feedback)

## V

- **Validate (Composer)** — [Ch. 9 §Web Composer](/docs/hierarchy-builder#web-composer-browser-version)
- **Vault** — [Ch. 1 §Unlocking the vault](/docs/getting-started#unlocking-the-vault) | [Ch. 19 §V](/docs/glossary#v)
- **Vault rotate password** — [Ch. 13 §Security](/docs/settings-themes#security)
- **Vault timeout (auto-lock)** — [Ch. 13 §Security](/docs/settings-themes#security)
- **Verbose / debug log mode** — [Ch. 18 §Verbose / debug log mode](/docs/troubleshooting#verbose--debug-log-mode)
- **Verify the vault** — [Ch. 18 §Verify the vault](/docs/troubleshooting#verify-the-vault)
- **Version (current build)** — [Ch. 17 §Checking for updates](/docs/licensing#checking-for-updates)
- **Vibrate (haptic feedback)** — see *Haptic*
- **View menu** — [Ch. 13 §General](/docs/settings-themes#general) | [Ch. 16 §Go back to tabs](/docs/workspaces#go-back-to-tabs)
- **Virtual cursor** — see *AidaVirtualCursor*
- **Virtual environment (Python)** — [Ch. 3 §Run a file](/docs/file-browser#run-a-file)
- **Visual themes (Hierarchy Builder)** — [Ch. 9 §Visual themes](/docs/hierarchy-builder#visual-themes)
- **VLAN tagging** — [Ch. 6 §Topology](/docs/network-tools#topology)
- **VM (virtual machine for SSH practice)** — [Ch. 2 §"I do not have an SSH server"](/docs/ssh-devices#i-do-not-have-an-ssh-server--setup-paths)
- **VNC** — [Ch. 19 §V](/docs/glossary#v)
- **VS Code import / keybindings** — [Ch. 14 §Importing other editor keymaps](/docs/shortcuts#shortcuts-editor)
- **Vulnerability scanner** — [Ch. 7 §Vulnerability Scanner](/docs/security-tools#vulnerability-scanner)
## W

- **Watcher pill** — [Ch. 22 §Presence and spectate](/docs/input-devices#presence-and-spectate) | [Ch. 22 §Terms](/docs/input-devices#watcher-pill)
- **Watchlist (alerts)** — [Ch. 12 §Monitoring](/docs/sysadmin#monitoring-and-alerts)
- **Web Composer** — see *Composer (Web Hierarchy)*
- **Web Dashboard** — [Ch. 5 §Web Dashboard](/docs/fleet#web-dashboard) | [Ch. 19 §W](/docs/glossary#w)
- **Web Dashboards (portal)** — [Ch. 21 §Other web dashboards](/docs/cloud-portal-docs#other-web-dashboards)
- **Web docs button** — [Ch. 17 §Support and feedback](/docs/licensing#support-and-feedback)
- **webportal/d/<id>/ path** — [Ch. 21 §Terms](/docs/cloud-portal-docs#webportaldid-path)
- **WebSocket** — [Ch. 6 §Traffic Analyzer](/docs/network-tools#traffic-analyzer)
- **WebSocket tunnel (portal)** — [Ch. 21 §What is the Cloud Portal?](/docs/cloud-portal-docs#what-is-the-cloud-portal)
- **Widget** — [Ch. 15 §Plugin vs widget](/docs/plugins#plugin-vs-widget) | [Ch. 19 §W](/docs/glossary#w)
- **Widget Palette (retired)** — Replaced by **Add panel**. [Ch. 16 §Add any panel](/docs/workspaces#add-any-panel)
- **Widget Health Dashboard** — [Ch. 15 §Widget Health Dashboard](/docs/plugins#widget-health-dashboard)
- **Widget Permissions** — [Ch. 15 §Permissions are real](/docs/plugins#permissions-are-real)
- **Win key (on-screen)** — [Ch. 22 §The mobile shortcut bar](/docs/input-devices#the-mobile-shortcut-bar)
- **Window (tear-off)** — [Ch. 16 §Tear off into a new window](/docs/workspaces#tear-off-windows)
- **Windows management** — [Ch. 12 §Windows management](/docs/sysadmin#windows-management)
- **Windows quirks** — [Ch. 20 §Windows](/docs/quick-reference#windows)
- **Windows Services** — [Ch. 12 §Windows management](/docs/sysadmin#windows-management)
- **Windows Updates** — [Ch. 12 §Windows management](/docs/sysadmin#windows-management)
- **WinRM** — [Ch. 12 §WinRM](/docs/sysadmin#winrm) | [Ch. 19 §W](/docs/glossary#w)
- **Wiring (Hierarchy Builder)** — [Ch. 9 §Wiring data flow](/docs/hierarchy-builder#wiring-data-flow)
- **Workbench** — [Ch. 16 — Workspaces and Layouts](/docs/workspaces)
- **Workflow (AI)** — [Ch. 8 §AI Workflows](/docs/ai-assistant#ai-workflows) | [Ch. 19 §W](/docs/glossary#w)
- **Workspace list** — Toolbar named layouts. [Ch. 16 §Save named layouts](/docs/workspaces#save-named-layouts) | [Ch. 3 §Workspace](/docs/file-browser#workspace)
- **Workspace vs layout** — The toolbar **Workspace** list is your named layouts. [Ch. 16 §Save named layouts](/docs/workspaces#save-named-layouts)
- **WRITE confirmations (LCOT, DB)** — [Ch. 4 §WRITE sub-groups](/docs/lcot#write-sub-groups) | [Ch. 11 §WRITE confirmations](/docs/databases#write-confirmations)
- **WSL (Windows Subsystem for Linux)** — [Ch. 2 §"I do not have an SSH server"](/docs/ssh-devices#i-do-not-have-an-ssh-server--setup-paths)
## X

- **X11 forwarding** — [Ch. 13 §SSH](/docs/settings-themes#ssh)
- **XML (config / export)** — [Ch. 13 §General](/docs/settings-themes#general)
- **XSS / HTML-escape in exports** — [Ch. 18 §Symptom-first lookup](/docs/troubleshooting#symptom-first-lookup)
- **xterm-256color (terminal type)** — [Ch. 13 §SSH](/docs/settings-themes#ssh)

## Y

- **YAML (workflows, ansible, k8s)** — [Ch. 8 §AI Workflows](/docs/ai-assistant#ai-workflows) | [Ch. 12 §Configuration management](/docs/sysadmin#configuration-management)
- **YubiKey (key passphrase)** — [Ch. 2 §Keys vs passwords](/docs/ssh-devices#keys-vs-passwords)

## Z

- **Zoom (Hierarchy Builder canvas)** — [Ch. 9 §Window layout](/docs/hierarchy-builder#window-layout) | [Ch. 19 §Z](/docs/glossary#z)
- **Zoom (User Guide viewer)** — `Ctrl+=` / `Ctrl+-` / `Ctrl+0` — see Ch. 14 §Default shortcuts
- **Zoom In/Out/Fit (Composer)** — [Ch. 21 §Web Hierarchy Composer](/docs/cloud-portal-docs#web-hierarchy-composer)
- **Zsh (remote shell)** — [Ch. 2 §Anatomy of a connection tab](/docs/ssh-devices#anatomy-of-a-connection-tab)

---

*Did not find the term you were looking for? Try **Ctrl+F** in the User Guide viewer, or open the [Glossary (Chapter 19)](/docs/glossary) for plain-language definitions.*

---

# Getting Started

Source: https://aidaide.app/docs/getting-started

This chapter walks you through the very first minutes with AidaIDE — from launching the app to recognising every part of the main window. Read it once, then keep it open as a glossary while you explore.

## What this chapter assumes

- AidaIDE is installed. If not, grab the installer from **aidaide.app** and run it.
- You have not yet entered a master password or set anything up.

If you have a license key, you can use it later — AidaIDE will launch without one.

## Launching AidaIDE

Double-click the **AidaIDE** shortcut (or run `aidaide` from a terminal). The first thing you see is the **Smart Login** window — a navy panel about 460 × 600 px, centered on screen, with the `$_` chip logo at the top.

The window is small, simple, and intentional: nothing else in the IDE will be visible until you authenticate.

## Unlocking the vault

The login window has one job: unlock (or create) your **vault**. The vault is an encrypted file on disk that holds every secret AidaIDE knows about — SSH passwords, SSH key passphrases, API keys, database credentials, and the like.

### First time (new install)

The status line reads **"Create Master Key"** and the button reads **Create**.

1. Type a master password. There is no recovery path — write it down somewhere safe.
2. Press **Enter** or click **Create**.
3. The vault is initialised, the splash plays, and the main window opens.

### Returning user

The status line reads **"Vault Locked"** and the button reads **Unlock**.

1. Type your master password.
2. Press **Enter** or click **Unlock**.

If you have genuinely forgotten the password, the small link under the password box — **Forgot password? Reset vault** — will wipe the salt and force you to create a new one. *Every secret previously stored in the vault is lost when you do this.* You will have to re-enter every SSH password and key passphrase.

### Soft-restart bypass

If AidaIDE restarted itself (because the web admin pushed a soft-restart, or because you applied an update), the login window may not appear at all. That is by design — your session is restored automatically. Lock the vault manually from **File → Exit** if you want to force a password prompt next launch.

## Splash screen

After a successful unlock, a 4-second splash plays before the main IDE appears:

- **lite** (default) — a small centered panel: the `$_` tile draws itself in, the glyphs fade, the cursor blinks, then the tile collapses to a singularity.
- **full** — full-screen with a cyan "code rain" of ~1,400 glyphs. Opt in by setting the environment variable `AIDA_SPLASH=full`.

You can skip the splash entirely with `AIDA_SPLASH=off`. The brand palette during the splash is navy `#0B1620` with cyan `#4DE4E4`.

## What you see

Once the splash clears, the main window has five named regions. Memorising these names makes the rest of the guide much easier.

```
┌───────────────────────────────────────────────────────────────────┐
│ Menu bar:  File  Edit  Tools  AI  Fleet  Network  Security ...   │
├───────────────────────────────────────────────────────────────────┤
│ Toolbar:  [+] [≡] [🔍] | Fleet ⚡ | Scan Serial Dash OTA | ★ AI ...│
├──────────┬─────────────────────────────────────┬──────────────────┤
│          │                                     │                  │
│ Sidebar  │    Notebook (tabs)                  │   LCOT panel     │
│ (left)   │    - Connection tabs (pinned left)  │   (right)        │
│          │    - Feature tabs   (pinned right)  │                  │
│          │                                     │                  │
├──────────┴─────────────────────────────────────┴──────────────────┤
│ Status bar                                                        │
└───────────────────────────────────────────────────────────────────┘
```

- **Menu bar** — the dropdowns at the top.
- **Toolbar** — icon buttons under the menu bar.
- **Sidebar (left)** — collapsible panels for Connections, Files, and AI chat.
- **Notebook (center)** — the tab strip where every workspace lives. **Connection tabs** (one per SSH host) pin to the left, **feature tabs** (Fleet Manager, Security Scanner, etc.) pin to the right.
- **LCOT panel (right)** — the **L**ocal **C**hain **o**f **T**hought one-click script library. Shows only when a connection tab is in front. See [Chapter 4](/docs/lcot).
- **Status bar** — current file, cursor position, encoding, line endings.

## Menu bar

The complete menu list. Each item is covered in its own chapter — this is the lookup table.

- **File** — New Tab, project templates, Open File, Save, Recent submenus, Workspaces, **Connection Manager**, **Settings**, Experimental Features, **Keyboard Shortcuts…**, Exit.
- **Edit** — Undo/Redo, Cut/Copy/Paste, **Find** (`Ctrl+F`), **Find in Files** (`Ctrl+Shift+F`), **Go to Line** (`Ctrl+G`).
- **Tools** — Git submenu, **Protocol Wizard**, **Board Library Manager**, **Test Panel**, Device Monitoring submenu, **Plugins & Widgets** submenu, **Check for Core Updates**.
- **AI** — Toggle AI Sidebar, **AI Chat**, **Claude Agent Manager**, **Agent Hierarchy Builder**, **Live Coding Agents**, **AI Agent Portal**, **Persona Portal**, **AI Workflows**, Toggle Inline Suggestions, Save/Load Chat Session.
- **Fleet** — Fleet Manager, Deploy Lite, Discover Devices, Device Dashboard, OTA Update Manager, Web Dashboard.
- **Network** — Port Scanner, Network Topology, Packet Capture, Traffic Analyzer, Network Diagnostics, Host Discovery, Service Detection; **Cameras** submenu.
- **Security** — Security Scanner, CVE Scanner, Dependency Scanner, Secret Scanner, SAST Scanner, Threat Intel Feeds, IOC Database, PKI Manager, Certificate Inventory, IP Access Control, Compliance Assessment.
- **Preview** — early-access groups: **Sysadmin**, **Database**, **Debug**.
- **View** — Command Palette, Feature Browser, Open Project Folder, **Workbench** (Use the workbench shell, Classic layout), **Theme**, sidebar toggles.
- **Help** — Welcome Guide, Setup Wizard, **Ask Macy** (interactive tour), About, Documentation, Check for Updates, **Enter License Key**, License Status, Bug Reports.

## Toolbar

Left to right:

1. **New Tab** (`+`) — opens a connection tab. If you have at least one saved host it shows a chooser; otherwise opens Connection Manager.
2. **Connections** (`≡`) — opens **Connection Manager**.
3. **Features** (magnifier) — opens the **Feature Browser** (every feature tab grouped by category, with search).
4. **Fleet Manager** — opens the fleet management tab.
5. **Deploy ESP32** (`⚡` orange) — shortcut to Deploy Lite scoped to ESP32 targets.
6. **Scan / Serial / Dashboard / OTA Update** — monitoring shortcuts.
7. **AI Assistant** (`★` green) — opens Claude Agent Manager.
8. **Workspace** list and **Save** — your named layouts. **+ Panel** (`Ctrl+Shift+B`) opens Add panel.
9. **Git Branch** dropdown and **Git Push** (`↑`).
10. **Settings** (gear, far right).

Every button has a tooltip; hover for a second to see its name and shortcut.

## First-run wizards

The very first session may show one (or both) wizards. They are independent:

### Onboarding Wizard

Fires when no saved connections exist *and* `config["onboarding_completed"]` is false. Seven steps:

1. **Welcome** — short description of what AidaIDE is.
2. **Theme** — pick a colour theme with live preview.
3. **AI Assistant Setup** — choose a provider (Anthropic Claude is recommended), paste an API key, set a skill level. Skipping is fine; you can do this later in **AI → Claude Agent Manager**.
4. **Editor Preferences** — font family and size.
5. **First Connection** — optional. Add one SSH host now or skip and use Connection Manager later.
6. **Navigation Guide** — quick tour of where things live.
7. **Keyboard Shortcuts** — printable reference of default bindings.

### Device Setup Wizard

Fires when `~/.aidaide/first_run_complete` is missing. Six steps focused on hardware:

1. Welcome.
2. **Device Type** — pick from cards: Raspberry Pi, ESP32, Arduino, generic Linux.
3. **Connection Method** — SSH (most common), Serial, or mDNS auto-discovery.
4. **First Connection** — validate live.
5. (Optional) deploy a sample project to your device.
6. Success — you are ready to go.

If you skip or close either wizard, AidaIDE remembers and will not re-prompt. To re-run either one, use **Help → Setup Wizard**.

## Onboarding & guided tours

Help-menu tours you can replay at any time:

- **Welcome Guide** — short overview of what each menu does.
- **Setup Wizard** — re-runs the appropriate first-run wizard.
- **Ask Macy (Interactive Guide)** — voice-narrated tour. Two flavours:
  - **General IDE tour** — every region of the main window.
  - **Hierarchy Builder tour** — 16 sections, covered in [Chapter 9](/docs/hierarchy-builder). Run it from inside the Hierarchy Builder tab.

## Exiting AidaIDE

**File → Exit** (or close the window) locks the vault. Next launch you will need your master password again.

From rc18, with the workbench shell on, the arrangement saves itself as you go — windows, splits, stacks, and floating windows — and comes back at the next start. SSH sessions do not reconnect by themselves. Save a named layout from the toolbar **Workspace** list when you want to switch setups. See [Chapter 16](/docs/workspaces).

## Terms & Setup

### Vault
The encrypted store for all your secrets — SSH passwords, SSH key passphrases, API tokens, database credentials, license info. Backed by Fernet symmetric encryption derived from your master password plus a per-install salt. Lives on your machine; never transmitted anywhere.

### Master password
The password you set on the Smart Login window. There is **no recovery path** — write it down. If you lose it, the **Forgot password? Reset vault** link nukes the vault and starts over.

### Splash
The 4-second animated reveal between vault unlock and the main IDE. Cosmetic only; the IDE is loading in the background. Disable with the `AIDA_SPLASH=off` environment variable.

### Connection tab vs feature tab
A **connection tab** is your workspace for one SSH host: terminal + file browser + editor + LCOT panel. A **feature tab** is a tool that does not belong to a single host: Fleet Manager, Security Scanner, Database Manager, AI Hierarchy Builder, etc.

### Feature Browser
A searchable list of every feature tab grouped by category. Open it from the toolbar magnifier or **View → Feature Browser**. The fastest way to find a tool when you forget which menu it lives under.

### "I do not have an SSH server yet"
You can launch AidaIDE without one, but most workflows assume at least one device you can SSH into. The quickest options:

- **Local OpenSSH on Windows** — Settings → Apps → Optional Features → Add → **OpenSSH Server**. Start the **OpenSSH SSH Server** service. Connect AidaIDE to `localhost:22` with your Windows username.
- **A Raspberry Pi** — Pi OS has SSH disabled by default since 2016. Enable it with `sudo raspi-config` → Interface Options → SSH → Enable, or by dropping an empty file named `ssh` (no extension) in the boot partition.
- **A cloud VM** — DigitalOcean, AWS, Azure all give you a Linux VM with SSH enabled in minutes.
- **WSL** — On Windows, `wsl --install` gives you a Linux environment that AidaIDE can SSH into via `localhost`.

See [Chapter 2](/docs/ssh-devices) for the full add-host walkthrough.

### Where do my settings live?
- Vault and salt: `%APPDATA%\AidaIDE\` on Windows, `~/Library/Application Support/AidaIDE/` on macOS, `~/.aidaide/` on Linux.
- Named layouts: `~/.aidaide/layouts/`. Current arrangement: `~/.aidaide/workbench_layout.json`.
- Hierarchy Builder drafts: `~/.aidaide/builder_drafts/`.
- Logs (for bug reports): `~/.aidaide/logs/`.

---

# SSH Devices and Connections

Source: https://aidaide.app/docs/ssh-devices

The primary workflow in AidaIDE is "open a connection tab, work on a remote device." This chapter walks you through getting that first tab open and keeping it organised as you accumulate hosts.

## What this chapter covers

- Opening a new SSH connection from the toolbar or menu.
- Using **Connection Manager** to add, edit, and group hosts.
- Storing passwords, key files, and key passphrases in the vault.
- The anatomy of a connection tab — what each pane does.
- Common pitfalls: non-22 ports, key permissions, host-key changes.

## Opening a new connection

There are four entry points and they all converge on the same dialog:

1. **Toolbar → New Tab** (`+`). If you have at least one saved host, you get a chooser dropdown; pick a host or click **Manage…** to open Connection Manager.
2. **File → New Tab** (`Ctrl+T`).
3. **File → Connection Manager** — full management UI.
4. **Toolbar → Connections** (`≡`) — same as the menu option.

If this is the very first time, you have no saved hosts. Click **Manage…** or open **Connection Manager** directly.

## Connection Manager

Connection Manager is the central registry of every host AidaIDE knows about. It has three columns:

- **Left** — group tree (All, Production, Lab, etc.). Right-click to add or rename a group.
- **Center** — table of hosts in the selected group with columns for Name, Host, Port, Username, Last Connected.
- **Right** — editor for the currently selected host.

### Adding a host

1. Click **Add** (or **Add Host** in the toolbar of the dialog).
2. Fill in:
   - **Name** — a friendly label (e.g. `pi-lab-01`).
   - **Host** — IP address or DNS name.
   - **Port** — `22` is the default, **change it if your server listens elsewhere**. See [Ports and the port-22 trap](#ports-and-the-port-22-trap) below.
   - **Username** — Linux user on the remote box.
   - **Authentication** — password, key file, or both.
3. Click **Save**. Your secrets go into the vault immediately, encrypted under your master password.
4. Click **Connect** (or close the dialog and use **New Tab → your host**).

### Editing a host

Select it on the right, change fields, click **Save**. AidaIDE re-encrypts any changed secret in place.

### Grouping hosts

Drag a host between groups in the left tree, or right-click → Move to Group. Groups have no functional meaning beyond making the **New Tab** dropdown easier to navigate.

### Importing existing SSH config

If you already have a `~/.ssh/config`, Connection Manager has an **Import…** button. It reads `Host`, `HostName`, `Port`, `User`, and `IdentityFile` directives and creates entries for each. Passwords and key passphrases still have to be entered manually — they are not in `~/.ssh/config`.

## Anatomy of a connection tab

A connection tab is the per-host workspace. Once connected, the tab is divided into four regions (defaults shown; you can rearrange them):

```
┌─────────────────────────────────────────────────────────┐
│ Top toolbar: file controls, run, terminal toggles       │
├──────────────────┬──────────────────────┬───────────────┤
│ File Browser     │   Editor             │  LCOT Panel   │
│  - Remote tree   │   - Tabs of opened   │   READ ▶      │
│  - Local tree    │     remote files     │   WRITE ▶     │
│                  │   - Syntax highlight │               │
├──────────────────┴──────────────────────┤               │
│ Terminal (xterm-compatible, full PTY)   │               │
│ $ _                                     │               │
└─────────────────────────────────────────┴───────────────┘
```

- **File Browser (left)** — two trees stacked: the remote filesystem over SFTP and your local filesystem. Drag-and-drop between them.
- **Editor (center, top)** — syntax-highlighted text editor with tabs for every file you have open on this host. See [Chapter 3](/docs/file-browser) for full editor details.
- **Terminal (center, bottom)** — full PTY into the remote shell. Resizes with the pane.
- **LCOT Panel (right)** — one-click READ/WRITE scripts targeted at this connection. See [Chapter 4](/docs/lcot).
- **Intel Panel** — context info about the host (uptime, OS, IP). Toggle with the panel button on the top toolbar.

The tab title is the host name (or `name@host` if multiple sessions to the same host are open). A red dot next to the tab name means the connection is down. A spinner means it is reconnecting.

## Authentication

### Password
Type it in once when adding the host. It is stored in the vault and re-supplied on every connection.

### Key file
1. Pick the private key from your filesystem (`~/.ssh/id_ed25519`, `~/.ssh/id_rsa`, etc.).
2. If the key is passphrase-protected, AidaIDE prompts for the passphrase once and stores it in the vault.
3. The public key must already be installed on the remote box in `~/.ssh/authorized_keys`. AidaIDE will not push it for you. (See [Setting up your first SSH key pair](#setting-up-your-first-ssh-key-pair) below.)

### Both / fallback
You can store both a key and a password. If the key fails (wrong key, host does not accept it), AidaIDE falls back to the password silently.

### Keys vs passwords
For anything beyond local lab use, prefer keys. They are stronger, do not transit the wire on every login, and play nicely with `sudo`. Passwords are easier to set up the first time and are fine for a single Raspberry Pi on your bench.

## Ports and the port-22 trap

AidaIDE saves a custom port the moment you set one in Connection Manager, but several places in the codebase have historically hardcoded `22`. If a connection fails with "Connection refused" on a non-default port:

1. Re-open the host in Connection Manager and verify **Port** is correct.
2. Check **Connection Method** (some scan-style tools probe port 22 regardless).
3. Try `ssh -p <port> user@host` from your terminal as a sanity check.

The intended probe order in AidaIDE is `device.ssh_port → device.port → 22`. If you suspect your custom port is being ignored anywhere, file a bug from **Help → Report a Bug** and attach the connection log — that is a known recurring trap.

## Common operations

### Run a command quickly
- Click in the terminal pane and type it. The terminal is a real PTY, not a wrapper.
- Or use **LCOT** for one-click commands (e.g. *Disk Usage*, *List Services*).

### Edit a remote file
1. In the remote File Browser tree, double-click the file.
2. It opens in the editor with the path prefixed by the host name.
3. Save with `Ctrl+S`. AidaIDE writes back over SFTP. **Save will not fall back to a local file if SFTP fails** — you will see an error dialog. This is intentional to prevent silent wrong-filesystem data loss.

### Drag a local file to the remote
1. In the local File Browser tree, click and drag the file onto a folder in the remote tree.
2. AidaIDE uploads it via SFTP. A progress notification appears in the status bar.

### Reconnect after the connection drops
The tab shows a red dot and a **Reconnect** button. Click it. If the host is genuinely gone, the reconnect button stays and the terminal pane is preserved (so you do not lose what was on screen).

### Open multiple sessions to the same host
**New Tab → same host → New Session**. Each session is independent — they do not share the working directory, environment, or terminal scrollback.

## Recent connections

**File → Recent Connections** lists the last 10 hosts you connected to with one-click reconnect. The list survives across launches.

## Terms & Setup

### SSH (Secure Shell)
An encrypted protocol for logging into another machine and running commands. AidaIDE speaks SSH (and SFTP, which rides on top of SSH) using a Python implementation, so you do not need a separate `ssh` client installed.

### SFTP
SSH File Transfer Protocol. Lets AidaIDE read and write files on the remote box without opening a shell. The remote file browser and the editor's save mechanism both use SFTP.

### Host key
The remote server's identity fingerprint. The first time you connect, AidaIDE asks you to trust it. If a host key changes on a subsequent connection (e.g. the server was reinstalled), AidaIDE refuses to connect and shows the old vs. new fingerprint. This is a security feature, not a bug — verify with the server admin before clicking **Accept New Key**.

### Public key vs private key
The **private** key stays on your machine. The **public** key (one short line ending in your email or username) goes on the remote server in `~/.ssh/authorized_keys`. Anyone with the public key can verify a signature made with the private key, but cannot forge one.

### "I do not have an SSH server" — setup paths

**Windows local (for testing AidaIDE itself):**
1. Settings → Apps → Optional Features → Add → **OpenSSH Server**.
2. Open *Services* (`services.msc`), find **OpenSSH SSH Server**, set it to **Automatic** and click **Start**.
3. Allow port 22 in Windows Firewall (a popup may appear; click Allow).
4. Connect AidaIDE to `localhost:22` with your Windows username.

**Raspberry Pi (Pi OS):**
1. Insert the SD card on your PC. In the `boot` partition, create an empty file named `ssh` (no extension). When the Pi boots it will enable SSH.
2. *Or* on the running Pi, `sudo raspi-config` → Interface Options → SSH → Enable.
3. Default username on Pi OS is whatever you set in Imager (or `pi` on older images).
4. Connect AidaIDE to the Pi's IP, port 22.

**Linux server / cloud VM:**
- The provider (DigitalOcean, AWS, GCP, Azure) usually delivers an Ubuntu/Debian VM with SSH enabled and key-only authentication preconfigured. They give you a key file and an IP — feed both into Connection Manager.

**WSL on Windows (no extra box):**
1. `wsl --install` in PowerShell as admin. Reboot.
2. Inside WSL, `sudo apt install openssh-server`, `sudo systemctl enable --now ssh`, set a password with `passwd`.
3. Find WSL's IP with `ip addr` (eth0). Connect AidaIDE there. Note: WSL2's IP changes on every Windows reboot.

### Setting up your first SSH key pair

If your remote box requires keys (or you simply want to use them), here is the shortest path:

1. **Generate a key on your local machine:**
   - Windows PowerShell or macOS/Linux terminal: `ssh-keygen -t ed25519 -C "your_email@example.com"`
   - Accept the default path (`~/.ssh/id_ed25519`).
   - Set a passphrase (recommended). AidaIDE will store it in the vault so you only type it once.

2. **Copy the public key to the server:**
   - Easiest: `ssh-copy-id user@host` (works on macOS/Linux/WSL).
   - On Windows without `ssh-copy-id`: `type %USERPROFILE%\.ssh\id_ed25519.pub | ssh user@host "mkdir -p ~/.ssh && chmod 700 ~/.ssh && cat >> ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys"`
   - Or just paste the contents of `id_ed25519.pub` into `~/.ssh/authorized_keys` on the server by hand.

3. **Tell AidaIDE about the key:** In Connection Manager, set Authentication → Key File and point at the **private** key (no `.pub`). Connect.

### Key permissions errors

If SSH refuses your key with a permissions complaint, on the remote server run:

```
chmod 700 ~/.ssh
chmod 600 ~/.ssh/authorized_keys
```

On Windows, key file permissions are checked by OpenSSH. If you see a "WARNING: UNPROTECTED PRIVATE KEY FILE" error, right-click the key in Explorer → Properties → Security → Advanced → Disable inheritance and remove all users except your own account.

### Saved credential security

Every secret stored in Connection Manager is encrypted with a multi-layer scheme (PBKDF2/Scrypt-derived keys, per-credential salts). Only your master password unlocks the chain. If you suspect compromise, **rotate the secret on the server** and update it in Connection Manager — there is no replay protection beyond the encryption itself.

### Recurring traps to know

These bugs have shipped before and may resurface. If a connection behaves oddly, suspect them first:

- **Hardcoded port 22** — even when Connection Manager has the right port. Symptom: "Connection refused" or "Connection timed out" on a non-22 port that you can clearly reach with the system `ssh`.
- **Silent SFTP fallback to local `open()`** — fixed, but if a save appears to succeed but the remote file is unchanged, check that you are not editing the local mirror.
- **Decrypt failure returning empty string** — fixed; should now surface an error dialog. If you ever see a password field that mysteriously goes blank, file a bug.

---

# File Browser and Editor

Source: https://aidaide.app/docs/file-browser

The editor is where you spend most of your time inside a connection tab. This chapter covers everything that lives in the center pane and its file-tree neighbours.

## Opening files and projects

There are several routes to getting code on screen:

- **File → Open File…** (`Ctrl+O`) — single file picker. Opens the file in the editor of the currently focused connection tab. If no connection is focused, opens in a local editor tab.
- **File → Open Project Folder…** (`Ctrl+Shift+O`) — opens an entire directory as the workspace root. The local file browser tree jumps to that folder.
- **File → New Project from Template…** (`Ctrl+Shift+N`) — scaffolds a starter project. Templates include Python script, Flask API, ESP32 firmware, Raspberry Pi script, FastAPI service, etc.
- **Double-click a file in the file browser** — opens it in the editor. Works for remote files too (over SFTP).
- **Drag a file from your OS file manager onto the editor area** — opens it.

The recently used items live under **File → Recent Files** (last 20).

## Local file browser

The local tree shows your computer's filesystem. By default it is rooted at your home directory; **Open Project Folder** changes the root.

Useful right-click items:

- **New File / New Folder** — quickly scaffold next to an existing path.
- **Rename**, **Duplicate**, **Delete** — usual file ops. Delete sends to the OS recycle bin/trash on supported platforms; otherwise prompts for hard delete.
- **Open in OS Explorer / Finder** — reveals the file outside AidaIDE.
- **Copy Path** — full absolute path to the clipboard.

## Remote file browser (SFTP)

Inside a connection tab, the **Remote** tree shows the file system on the SSH host, fetched on demand via SFTP. The columns are Name, Size, Modified.

Behaviour worth knowing:

- Right-click an empty area to refresh.
- Double-click a folder to expand; double-click a file to open it in the editor.
- Right-click a file for **Run** (calls a sensible interpreter — `python` for `.py`, `bash` for `.sh`, `node` for `.js`, `cat`/`tail` for log-like files), **Rename**, **Delete**, **Download** (copies to local), **chmod +x** (adds execute), **Properties**.
- Drag-and-drop between the local and remote trees uploads / downloads.
- Permissions stick. Renaming or moving a file does not change its mode bits.

If you delete a file by mistake, there is no remote trash. Be careful with **Delete** on the remote tree.

## The editor

The editor pane has a tab strip at the top — one tab per open file. Files open in the same editor regardless of whether they live locally or on the remote host.

### Syntax highlighting

Driven by file extension. Supported out of the box: Python, JavaScript/TypeScript, C/C++, Go, Rust, Java, HTML, CSS, Markdown, JSON, YAML, TOML, INI, Bash/Shell, PowerShell, SQL. New file types can be added via **Settings → Editor → Syntax**.

If you save a file with a different extension (Save As… `.txt` → `.py`), the highlighter re-evaluates. If for any reason highlighting does not update, close and reopen the file — this is a known minor trap.

### Cursor and selection

- Standard arrow / shift-arrow navigation.
- `Ctrl+→` / `Ctrl+←` move by word.
- `Home` / `End` jump to line start/end. Pressing `Home` twice jumps to column 1 vs. first non-whitespace, like most editors.
- `Ctrl+A` selects the whole document.
- Multi-cursor: `Alt+Click` adds a cursor at the click point.

### Split panes

Open a second editor next to the first to compare files or edit two regions of the same file:

- **Right-click an editor tab → Split Right** opens a copy in a side pane.
- The active pane has a highlighted border. Click in a pane to focus it.
- Each pane has its own cursor and scroll position; saves apply to the underlying file regardless of pane.

### Save and Save As

- `Ctrl+S` — save the current file. If it is a remote file, the save goes over SFTP and **does not** silently fall back to local on failure.
- **File → Save As…** — save under a new path. Updates the highlighter if the extension changed.
- Files with unsaved changes show an asterisk in the tab title.
- Closing an unsaved tab prompts to save first.

## Find and Find in Files

Two related dialogs:

- **Find** (`Ctrl+F`) — search inside the current file. Options: case-sensitive, whole word, regex. Replace with `Ctrl+H`. **Find next** is `F3` (or `Enter` in the find box).
- **Find in Files** (`Ctrl+Shift+F`) — search across the project root (set by Open Project Folder). Results list groups by file; double-click a result to jump to the line.
- **Go to Line** (`Ctrl+G`) — type a line number and jump. Accepts `42:10` syntax to put the cursor at column 10 of line 42.

## Running files

The editor's top toolbar has a **Run** (`▶`) button. It runs the current file using a sensible interpreter:

- `.py` → `python` on the host where the file lives. On a remote file it runs in the remote terminal; on a local file it spawns a process and pipes output to a Run panel.
- `.sh` → `bash`.
- `.js`, `.ts` → `node`.
- `.go`, `.rs`, `.c`, `.cpp` → compile + run (where toolchains are present).
- Log/data files (`.log`, `.json`, `.yaml`, `.txt`, `.md`) → opened with `cat`/`tail` so you can preview without an editor session.

If the file type has no runner, the button is disabled and the tooltip explains why.

## Git integration

**Tools → Git** holds:

- **Git Manager** — list of repos AidaIDE knows about, branches, dirty status. Click a repo to drill into a sub-window with file diffs.
- **Quick Push** — stages all, commits with a prompt for the message, pushes the current branch.
- **Git Pull** — fetches and fast-forwards.
- **Git Status** — equivalent of `git status` in a panel rather than a terminal.
- **Diff Viewer** — side-by-side diff of working tree vs. HEAD. Also reachable from the toolbar Git button on the far right.
- **Publish to GitHub** — wraps `gh repo create` if the `gh` CLI is installed. Otherwise prints instructions.

Branch selector lives on the right side of the toolbar. The `↑` button next to it is **Push** for the current branch.

## Diff Viewer

Three modes:

- **Working vs HEAD** — current uncommitted changes.
- **Two commits** — pick any two from a dropdown.
- **Two files** — compare any two open editor tabs side by side. Useful when you have a remote and local copy of the same file.

## Editor features worth knowing

- **Auto-save (optional)** — off by default. Toggle in **Settings → Editor → Save**.
- **Format on save** — off by default. When on, calls the language's default formatter (`black` for Python, `prettier` for JS, etc.).
- **Linting** — Python and JavaScript get inline lint warnings if `ruff`/`eslint` is on `PATH` of the host where the file lives.
- **Bookmark a line** — `Ctrl+F2`. Jump between bookmarks with `F2` / `Shift+F2`.
- **Multi-line edit / column edit** — `Alt+Shift+drag` to make a column selection.

## Terms & Setup

### Workspace
From rc18 the desktop window arrangement — panels, splits, stacks, and floating windows — saves itself and comes back after a restart. Named layouts are files you save from the toolbar **Workspace** list. SSH sessions do not reconnect by themselves. See [Chapter 16](/docs/workspaces).

### Local vs remote file
A **local** file lives on your computer. A **remote** file lives on the SSH host of the currently focused connection tab. The editor handles both transparently; the tab title shows the host name in front of remote paths.

### Project root
The directory passed to **Open Project Folder**. Find-in-Files and the local file tree both scope to this. Change it any time by opening a different folder.

### Run panel
The bottom panel where script output appears when you click **Run** on a local file. Auto-scrolls. Right-click for **Clear** and **Save Output As…**.

### "I am editing but my changes do not seem to save"
- Did you click in the correct pane? Saves apply to the focused editor.
- For remote files, is the connection alive? A red dot on the connection tab means SFTP saves will fail.
- If the file persists but reopens with old content, you may be looking at a stale local mirror. AidaIDE does not maintain mirrors on purpose — close the tab and re-open the file from the remote tree to verify.

### Encoding (UTF-8)
All files are read and written as UTF-8 by default. If you open a legacy CP1252 / Latin-1 file, AidaIDE will show replacement characters (�). Use **File → Reopen With…** to pick a different encoding. Save back as UTF-8 when possible — mixed encodings cause real data loss across reload cycles.

### Line endings
The status bar shows the current file's line ending mode (CRLF or LF). New files default to LF on all platforms. Change with **File → Line Endings** in the menu.

### "How do I open a file in two editors at once?"
Right-click the tab → **Split Right**, then `Ctrl+P` (Open File) in the new pane to load the same file. Edits in one pane reflect in the other after each save.

### Project templates available

- Python script (single file)
- Flask web app
- FastAPI service
- ESP32 firmware (PlatformIO layout)
- Arduino sketch
- Raspberry Pi Python project
- Node.js CLI
- Static HTML site

Pick one in **File → New Project from Template…** and AidaIDE scaffolds it into the folder you choose.

---

# LCOT Panel

Source: https://aidaide.app/docs/lcot

LCOT stands for **L**ocal **C**hain **o**f **T**hought. In practice it is a categorised library of 800+ ready-made commands you can run on the currently focused connection with a single click. Think of it as a button-driven cheat sheet that knows what kind of device you are on.

## Where it lives

The LCOT panel docks on the **right** side of every **connection tab**. It is **not** visible on feature tabs (Fleet Manager, etc.) because those tabs do not target a specific host.

If you do not see it:

1. Make sure you are looking at a connection tab, not a feature tab.
2. **View → Toggle LCOT Panel** — re-enables it if you previously hid it.
3. Drag the splitter from the right edge of the window leftward if the panel has been collapsed to zero width.

## How it works

LCOT is a tree. Top-level nodes are **zones**, then **categories**, then **subcategories**, then individual commands at the leaves. Click a leaf and the command runs in the connection's terminal pane immediately.

```
[R] READ Scripts           ← green/neutral icons
  ├ System Snapshot
  │   ├ uptime
  │   ├ kernel
  │   └ ...
  ├ Network Diagnostics
  ├ Services
  └ Hardware Health

[W] WRITE Scripts          ← red leaves
  ├ Service Control
  ├ Package Management
  ├ Filesystem Ops
  ├ Network Config
  └ Embedded Quick Ops
```

## READ vs WRITE zones

Every command in LCOT is classified as either READ or WRITE.

- **[R] READ Scripts** — safe, diagnostic. Reads state but does not modify it. Examples: `uptime`, `ps aux`, `df -h`, `ip addr`, `systemctl list-units`.
- **[W] WRITE Scripts** — modifies state. Examples: package install, service restart, firewall rule, GPIO write, reboot.

**WRITE leaves are coloured red.** Clicking one always pops up a confirmation dialog showing the exact command before it runs. You have to click **Confirm** explicitly. This is intentional — it prevents the "I meant to ping, I rebooted production" class of accident.

The classification is part of the metadata, not a per-user setting. You cannot turn off the WRITE confirmation prompt by accident.

## Command categories

The built-in library is organised by domain. Most users only see the categories relevant to the kind of device they are connected to, but everything is available everywhere:

- **Network Utilities** — ping, traceroute, dig, nmap, ip, ss, netstat, tcpdump, iperf.
- **Built-in / Linux** — basic Linux ops (file listings, processes, users, journalctl).
- **Containers** — Docker (`docker ps`, image listings, prune), Docker Compose, basic Kubernetes.
- **Databases** — MySQL, PostgreSQL, MongoDB, Redis client commands.
- **IoT** — common Pi/ESP32/Jetson commands (GPIO, I²C, SPI scans, temp/voltage probes).
- **Development** — git, build/run idioms for various toolchains.
- **Monitoring** — system / network / logging probes.
- **PLC (Industrial)** — Modbus, Ethernet/IP, S7, OPC UA snippets.
- **Manufacturer-specific** — Cisco IOS, Juniper Junos, Ubiquiti EdgeOS/UniFi, MikroTik RouterOS, Fortinet, Palo Alto PAN-OS, Netgate pfSense, Arista.
- **Bluetooth** — discovery, pairing, GATT probes.

The full count is north of 800 commands today. Searching is the way to find a specific one.

## Sysadmin Quick Toolkit

A curated set of 62 commands across 9 sub-groups designed for the "fix it in 30 seconds" sysadmin loop. Lives under its own **Quick Toolkit** category. Half the sub-groups are READ-tagged, half WRITE-tagged:

### READ sub-groups
1. **System Snapshot** — uptime, kernel, last logins, who, top CPU/MEM, ports, disk usage, big files.
2. **Network Diagnostics** — IP + routes, DNS resolvers, gateway ping, public IP, dig, nc port check.
3. **Services** — systemctl listings.
4. **Hardware Health** — temp/power/sensors.

### WRITE sub-groups
5. **Service Control** — start/stop/restart/enable systemd units.
6. **Package Management** — apt/yum/dnf install, upgrade, remove.
7. **Filesystem Ops** — mkdir, chmod, chown, rm patterns.
8. **Network Config** — ip route, iptables/ufw rules, restart networking.
9. **Embedded Quick Ops** — reboot, dmesg clear, GPIO writes.

## Searching

The search box at the top of the LCOT panel filters the tree as you type. Search matches against the command name, description, and tags. Press `Esc` to clear.

## Running a command

1. Find the command in the tree (or by search).
2. Click the leaf. For READ commands the terminal runs it immediately. For WRITE commands you get a confirmation dialog with the full text — read it, then click **Confirm**.
3. Output appears in the terminal pane of the connection tab. Scroll buffer is preserved.

Many commands include `{placeholder}` slots — when you click them, AidaIDE prompts for the placeholder values first (e.g. *port* for an `nc -z host port` probe). Recently used values are remembered per command per host.

## Adding your own command

Right-click anywhere in the LCOT tree → **Add Command…** opens **AddCommandDialog**:

- **Name** — what the leaf will say in the tree.
- **Description** — shown as tooltip.
- **Category / Subcategory** — where it lives. Pick existing or type a new one.
- **Command** — the actual text to run. Use `{placeholder}` for prompted variables.
- **WRITE checkbox** — tick this if the command modifies state. The leaf will be red and confirmation will be required.
- **Tags** — for search.

Click **Save**. The command is added to your personal LCOT library at `~/.aidaide/lcot_user_commands.json` and survives across launches and across hosts (it shows up on every connection).

## Edit / delete a custom command

Right-click the custom leaf → **Edit** or **Delete**. Built-in commands are read-only; you cannot edit them, but you can hide them via **Settings → Editor → LCOT → Hidden Commands**.

## Per-device command sets

LCOT can show different categories depending on the connected host:

- A Raspberry Pi tab gets the IoT and Linux categories highlighted.
- A Cisco router tab puts manufacturer-specific Cisco IOS commands at the top.
- A Windows-via-WinRM tab swaps out Linux commands for PowerShell equivalents.

This is driven by host detection on first connect. Override it from **Connection Manager → host → Type** if AidaIDE guesses wrong.

## Keyboard navigation

- Tab into the LCOT tree.
- Arrow keys navigate. **Enter** runs the focused leaf (with confirmation if WRITE).
- `Ctrl+F` (when LCOT panel is focused) jumps into the search box.

## Terms & Setup

### Why "Chain of Thought"?
The original intent of LCOT was to give the AI assistant a list of vetted commands to suggest, so the AI's reasoning steps were grounded in real, runnable building blocks. The library outgrew its origin; today it is also a great human cheat sheet.

### "I clicked a WRITE command and nothing seems to have happened"
Look at the terminal pane. The confirmation dialog runs, then output goes there. If output is empty, the command may have succeeded silently (e.g. `systemctl restart nginx` prints nothing on success).

### "A command is failing"
Most LCOT failures are environment, not bug:
- Missing tool on the remote (`nmap` not installed → `nmap` commands fail).
- Sudo not configured (`apt install` requires root).
- Wrong device type (a Cisco IOS command on a Linux box).

The terminal shows the actual error. Fix on the remote, retry.

### "I want a command across all my devices"
LCOT is interactive — it runs one command on one host at a time. For "do X on every device in my fleet," use **Fleet Manager** (see [Chapter 5](/docs/fleet)). Fleet Manager can ingest the same command catalogue.

### Editing the user-command file by hand
`~/.aidaide/lcot_user_commands.json` is a plain JSON file. Power users can edit it directly. AidaIDE re-reads it on next LCOT panel open. Schema:

```json
{
  "commands": [
    {
      "name": "Tail nginx error log",
      "description": "Live tail",
      "category": "Monitoring",
      "subcategory": "Web",
      "command": "tail -f /var/log/nginx/error.log",
      "write": false,
      "tags": ["nginx", "log", "web"]
    }
  ]
}
```

**Always include `encoding="utf-8"` if you edit this in another tool** — non-ASCII command names corrupt silently on Windows otherwise.

### Hidden commands
Hide built-in commands you never use via **Settings → Editor → LCOT → Hidden Commands**. Hidden commands are filtered from the tree but remain in the source library; un-hide any time.

---

# Fleet Management

Source: https://aidaide.app/docs/fleet

When you have more than two or three devices, single-host workflows stop scaling. Fleet management is AidaIDE's answer to "I have 50 Raspberry Pis on a network and need to update all of them." The whole **Fleet** menu and the orange `⚡` toolbar button live here.

The core SSH/SFTP workspace is **agentless**. Terminal, SFTP, and LCOT need only standard SSH/SFTP on the remote host — no on-device agent is required for a normal session. **Deploy Lite** is optional and additive: a Fleet menu that installs an on-device agent (**agent name TBD**) for fleet OTA and health. We don’t sell “AidaIDE Lite” as a separate product.

## What this chapter covers

- The **Fleet Command Center** — central registry of every fleet device. The device panel is a full device page.
- **Edit Device** — a device password. Leave it blank to keep the stored password. Clearing it uses `clear_password`. The audit line `DEVICE_LOGIN_SET` never carries the password.
- Devices marked **Camera** — listed and viewable on the **Cameras** screen (`from_fleet`, `device_id`, never a password). Removing one says to change its category.
- **Wi-Fi Surveys...** — on a site's Fleet-tab right-click menu. Phone **Send to PC** files surveys under the site. The desktop Wi-Fi Survey window covers bands, overlap, four heatmaps, site spectrum, and CSV. Six routes under `/api/fleet/sites/<site>/wifi-surveys`.
- **Fleet Map** — towers and devices on a map. Open it from **Wireless → Fleet Map (towers + devices)...**, the Fleet Manager toolbar **Fleet Map**, or the **Fleet Map** workbench tab. OSM device pins, USGS 3DEP terrain and line of sight, RF coverage, and LiDAR canopy when available. On the desktop map, **Offline…** downloads the area on screen for offline use.
- **Deploy Lite** — optional Fleet menu that installs an on-device agent (agent name TBD) or a custom payload. Not an AidaIDE Lite SKU, and not required for agentless SSH/SFTP.
- **Discover Devices** — scan a subnet for new candidates to add.
- **Device Dashboard** — status grid of everything in your fleet.
- **OTA Update Manager** — sign and roll out over-the-air firmware updates to devices that have the optional fleet agent.
- **Serial Monitor**, **PLC Monitor**, **Protocol Wizard**, **Board Library Manager**, **Test Panel** — supporting feature tabs.
- **Web Dashboard** — browser pages from the built-in web server (default port 5001), including `/fleet/map` and the device **Router/Firewall** tab. Router and switch reads and router actions sign in with the device's own password, falling back to the site's sign-in. A refused login answers 502 with `needs_login`.

## Fleet Manager

This tab is the **Fleet Command Center**. Open it from **Fleet → Fleet Manager** or the **Fleet Manager** toolbar button. The same toolbar has **Fleet Map**, covered in the next section.

The tab has three regions:

```
┌────────────────────────────────────────────────────────────────┐
│ Toolbar: Add Device | Import CSV | Bulk Action | Refresh       │
├──────────────────┬─────────────────────────────────────────────┤
│ Group tree       │  Device table (Name, IP, OS, Status, Last)  │
│  All             │  ─────────────────────────────────────────  │
│  ├ Production    │  pi-01    10.0.0.11   Pi OS    ●online      │
│  ├ Lab           │  pi-02    10.0.0.12   Pi OS    ○offline     │
│  └ Edge          │  esp32-A  10.0.0.40   FreeRTOS ●online      │
│                  │                                              │
│                  ├─────────────────────────────────────────────┤
│                  │  Device panel (full device page)             │
│                  │  ~550 px default; drag the left edge         │
└──────────────────┴─────────────────────────────────────────────┘
```

### Adding a device

1. Click **Add Device**. Fill in Name, IP, SSH port, username, credential reference (pulls from the Connection Manager vault), device type (Pi / ESP32 / generic Linux / Windows / network gear).
2. Click **Save**. AidaIDE attempts a connection on save and marks it online/offline.

### Importing in bulk

**Import CSV** accepts a file with columns `name,host,port,username,type`. The credentials are not in the CSV — link them after import.

### Groups

Drag devices between groups. Bulk actions (next section) scope to the selected group.

### Bulk actions

Select multiple devices in the table (Shift+click or Ctrl+click), then **Bulk Action**:

- **Run Command** — runs the same shell command on every selected device in parallel. Output is collected per-device. This uses agentless SSH.
- **Deploy Payload** — pushes a file or directory.
- **Update optional fleet agent** — bumps the optional on-device agent (agent name TBD) on every selected device to the version on disk. The bulk-action label in the app is **Update aida-lite**. That label is the implementation name, not an AidaIDE Lite SKU.
- **Restart** — `sudo reboot`.
- **Shutdown** — `sudo shutdown -h now`.

All bulk actions show a confirmation with the device count before running.

### Device panel

The device panel is a full device page. The default width is about 550 px. Drag the left edge to resize it.

It shows what AidaIDE has fetched about the device — uptime, kernel, CPU/MEM, disk free, last error in journal. Refresh with the small `↻` icon. Behind the scenes this calls `_fetch_specs` and `_refresh_status` over SSH; both use the device's configured SSH port. Specs over SSH do not require the optional fleet agent.

### Edit Device

**Edit Device** takes a device password. Leave it blank to keep the stored password. Clearing it uses `clear_password`. The audit line `DEVICE_LOGIN_SET` never carries the password.

### Camera devices

Devices marked **Camera** are listed and viewable on the **Cameras** screen (`from_fleet`, `device_id`, never a password). Removing one says to change its category.

### Cards view

**Cards** view draws one canvas per section. **Manage**, or a double-click, opens the device panel. The tab paints before the deferred load finishes.

### Wi-Fi Surveys

A site's Fleet-tab right-click menu includes **Wi-Fi Surveys...**.

Phone **Send to PC** files surveys under the site.

The desktop Wi-Fi Survey window covers bands, overlap, four heatmaps, site spectrum, and CSV.

Six routes live under `/api/fleet/sites/<site>/wifi-surveys`.

## Fleet Map

**Fleet Map** plots towers and fleet devices. Open it from any of these entry points — the names match the desktop app:

- Menubar: **Wireless → Fleet Map (towers + devices)...**
- Fleet Manager toolbar: **Fleet Map**
- Workbench opener and notebook tab: **Fleet Map**

The tab title and label are **Fleet Map**.

### OSM device pins

The default basemap is OpenStreetMap. Fleet devices are pinned where AidaIDE has a location: a GPS fix, a location you set by hand, or the wireless-cache location.

### USGS 3DEP terrain and line of sight

Switch the basemap to **Terrain** (USGS 3DEP / The National Map). **Line of Sight** opens a profile between two points and classifies the path as **CLEAR**, **GRAZING**, or **BLOCKED**.

### RF coverage and address check

**Coverage** turns the RF coverage heatmap on or off. The toolbar control is labeled **Coverage: On/Off**. Address and serviceability dialogs on the map:

- **Compute coverage**
- **Find an address**
- **Find + check service**
- **Can we serve here?**

### LiDAR canopy when available

The line-of-sight **Canopy** control uses real tree heights from USGS 3DEP point clouds (EPT) when that coverage exists for the path. When point-cloud coverage is not available, canopy heights are left out and the profile still runs on terrain. The map does not fill in a tree layer that the survey did not provide.

### Offline areas (desktop Fleet Map)

**Offline…** on the desktop Fleet Map toolbar, or a right-click **Download this area for offline…**, saves the area on screen for offline use. The dialog shows a tile count and a size estimate in MB. When the area is more than about 12,000 tiles, AidaIDE asks you to confirm before it downloads.

This download is on the desktop **Fleet Map** only. It is not on the browser map at `/fleet/map`.

## Deploy Lite

Open from **Fleet → Deploy Lite** or the orange `⚡` **Deploy ESP32** toolbar button.

We don’t sell “AidaIDE Lite” as a separate product. Deploy Lite is a Fleet menu that installs an on-device agent (agent name TBD).

That install is an **optional** on-device agent, or a custom payload. It is additive for fleet OTA and health. The core SSH/SFTP workspace stays agentless and does not need this agent.

Steps:

1. Select the target device(s) from the same group tree as the Fleet Command Center.
2. Pick **What to deploy**:
   - **Optional fleet agent** (default; agent name TBD). The picker label in the app is **aida-lite agent**. That string is the implementation name, not a separate SKU.
   - **Custom payload** — point at a local file or folder.
3. **Connection method** — SSH (Linux/Pi) or Serial (ESP32, microcontrollers via USB).
4. Click **Deploy**. Progress is per-device in a log panel.

For ESP32, Deploy Lite drives `esptool.py` under the hood. You need a USB-connected device showing up as a COM port (Windows) or `/dev/tty.usbserial*` (macOS) or `/dev/ttyUSB*` (Linux).

For SSH targets, the payload is copied via SFTP into `/opt/aida-lite/` and a systemd unit is installed and enabled. `/opt/aida-lite/` is an on-disk path, not a product name.

## Discover Devices

Open from **Fleet → Discover Devices**.

Scans the subnet for devices that respond to known protocols:

- ICMP (ping sweep).
- mDNS / Bonjour service announcements.
- SSH banner grab on port 22.
- Common embedded ports (ESP-IDF web, Pi-hole, etc.).

Found devices appear in a results table. Tick the ones you want to add and click **Add to Fleet** — they pre-fill the Add Device dialog.

You can scope the scan to a CIDR range (default: your machine's local subnet) and set per-protocol toggles.

## Device Dashboard

Open from **Fleet → Device Dashboard** (or **Tools → Device Monitoring → Device Dashboard**).

A real-time grid of cards, one per device, showing:

- Online indicator (green dot pulsing, or red).
- CPU and memory usage bars.
- Last command run.
- Quick actions: Open Terminal, Open Files, Restart.

Click a card to open a connection tab for that device. Card refresh interval is configurable in Settings → Network → Polling.

## OTA Update Manager

Deep dive: **[OTA Updates](/docs/ota-updates)** (sign, canary, history, keys).

Open from **Fleet → OTA Update Manager** or **Tools → Device Monitoring → OTA Update Manager**, or the red **OTA Update** toolbar button.

OTA pushes a signed payload to fleet devices. The optional fleet agent (agent name TBD) applies it on devices where that agent is installed. Agentless SSH/SFTP does not apply OTA and does not need the agent.

### Publishing an update

1. Click **New Release**.
2. Drag the build artefact (e.g. a `.zip`, `.tar.gz`, ESP32 firmware `.bin`) into the drop zone.
3. AidaIDE signs the artefact with your OTA private key and generates a manifest. The expected upload URL is `updates.aidaide.app` (the planned endpoint).
4. Choose roll-out scope — All / Group / Selected devices.
5. Optionally stage as **Canary** — 10% of selected first, watch metrics, then promote.
6. Click **Publish**.

Devices running the optional fleet agent poll the manifest at the configured interval (default 5 minutes). When they see a newer version targeted at their group, they download, verify the signature, and apply.

### OTA history

The Fleet Command Center device panel has an **OTA history** subtab — what version the device is on, what version it came from, and when it last applied.

### Signing keys

The OTA signing keypair is generated on first OTA Manager launch and stored in the vault. To rotate, **OTA Update Manager → Settings → Rotate Signing Key**. Old releases remain verifiable as long as the old public key is still on devices; new releases require the new key to be deployed first.

## Serial Monitor

Open from **Tools → Device Monitoring → Serial Monitor**.

A serial console for COM-port-attached devices (ESP32, Arduino, USB-to-UART debugs).

- **Port** dropdown — auto-populated with available COM ports.
- **Baud** — 9600 / 115200 / 921600 are presets; you can type any number.
- **Line ending** — None / CR / LF / CR+LF.
- **Echo local** — see what you type before it goes out.

Send commands with the input box at the bottom. Output streams to the main pane. Save the buffer with **Save Log…**.

## PLC Monitor

For industrial users. Open from **Tools → Device Monitoring → PLC Monitor**.

Connects to PLCs over **Modbus TCP/RTU**, **Ethernet/IP** (Allen-Bradley), **Siemens S7**, and **OPC UA**. Lets you read holding registers, coils, tags, and write back where allowed.

WRITE operations on PLCs are gated by a confirmation prompt (same pattern as LCOT WRITE scripts) — these can run motors and open valves.

## Protocol Wizard

**Tools → Protocol Wizard** (`Ctrl+Shift+W`).

A 4-step guided dialog that builds connection code for a given protocol against a given device library. Picks a protocol (HTTP, MQTT, CoAP, Modbus, OPC UA, BLE, etc.), a target board, an interaction (read sensor / send command / subscribe topic), and emits ready-to-run code into a new editor tab.

## Board Library Manager

**Tools → Board Library Manager**.

Browse and install board support packages. Each entry has board name, vendor, supported protocols, GPIO pin map, and a "Install Library" button which downloads stubs and example sketches into your project root.

## Test Panel

**Tools → Test Panel**.

Runs hardware-in-the-loop test suites against a connected device. Comes with starter tests for Pi GPIO, I²C/SPI, ESP32 Wi-Fi, and serial loopback.

**Related: Hardware Lab (virtual HIL).** Fleet Test Panel runs hardware-in-the-loop **test suites against a connected device**. It is not the marketing Hardware Lab workspace (virtual board, timeline scenarios, Bench, Run on Device, Record). See [Hardware Lab](/docs/hardware-lab) and the citation-ready definition [What is Hardware Lab?](/guides/hardware-lab).

## Web Dashboard

**Fleet → Web Dashboard**.

AidaIDE auto-starts the built-in web server when you launch the app. **Fleet → Web Dashboard** opens the browser at [http://localhost:5001/fleet](http://localhost:5001/fleet), or at that same path on the configured web port. The default port stays **5001**.

### Browser map (`/fleet/map`)

These tools are on the **web** map in the browser, at `/fleet/map`. They are separate from the desktop **Fleet Map** tab earlier in this chapter.

- Line of sight over USGS 3DEP.
- Coverage heatmaps.
- An address or spot check: **can we serve it?**
- Mast heights, and **Measure** from LiDAR.

### Router/Firewall (`/fleet/device`)

The device page at `/fleet/device` has a **Router/Firewall** tab.

- **RouterOS** — AidaIDE shows a plan, then applies it only after you type a confirmation.
- **EdgeOS** — read-only.

Router and switch reads, and router actions, sign in with the device's own password, falling back to the site's sign-in. A refused login answers 502 with `needs_login`.

## Terms & Setup

### "I don't have a device yet"
You can exercise the Fleet Command Center end-to-end before any real hardware arrives. Normal SSH practice stays agentless; Deploy Lite below is only for the optional fleet agent.

- **Bundled simulator.** **Tools → Protocol Wizard → Simulated Device** spins up a stand-in for the optional fleet agent (agent name TBD) that registers with the Fleet Command Center the way a real Pi would. Use it to walk the Add → Discover → Deploy Lite → OTA flow before you have a board on the desk.
- **A virtual Linux box.** Any local Linux VM (VirtualBox, VMware, QEMU, WSL2, Multipass) will accept the optional fleet agent. From the VM, run the one-liner shown in **Fleet → Deploy Lite** and it appears in your fleet within a few seconds. SSH into the VM still works with no agent installed.
- **A free Raspberry Pi OS image in QEMU.** Download the latest Raspberry Pi OS Lite image (the Raspberry Pi OS image name, not an AidaIDE product), boot it with `qemu-system-aarch64`, SSH in, then run the Deploy Lite one-liner only if you want the optional fleet agent. Same flow as a physical Pi.
- **Just the AidaIDE host itself.** As a quick smoke test, use Deploy Lite to install the optional fleet agent on your AidaIDE workstation. It registers as `localhost` and lets you exercise grouping, tagging, and OTA without leaving your desk.

When you do have hardware, see [Ch. 2 — SSH Devices §"I do not have an SSH server" — setup paths](/docs/ssh-devices#i-do-not-have-an-ssh-server--setup-paths) for getting sshd running on it, then return here for **Add Device** or **Discover Devices**. Agentless SSH is enough until you want fleet OTA or health from the optional agent.

### aida-lite
On-disk and service name of the **optional fleet agent** (agent display name TBD). It is not a product called AidaIDE Lite, and the core SSH/SFTP workspace does not require it. When installed, it reports specs and health back to the Fleet Command Center and applies OTA updates. Paths on the device — not SKUs — include `/opt/aida-lite/` and the systemd unit `aida-lite` (`journalctl -u aida-lite`).

### Fleet vs Connection Manager
**Connection Manager** is the registry of interactive SSH sessions you open by hand. **Fleet Command Center** is the registry of devices you want to manage in bulk. The two overlap — a device can be in both — and credentials are shared via the same vault, so adding a device in Fleet automatically gives you a Connection Manager entry too. Those SSH sessions are agentless.

### "Discover Devices" found nothing
- Confirm your CIDR scope matches the LAN your devices are on.
- Some routers block mDNS or ICMP across VLANs.
- Some ESP32 firmwares do not advertise via mDNS. Try a SSID-scan instead: **Tools → Protocol Wizard → BLE/Wi-Fi**.

### "OTA Update succeeded but the device did not change"
- Check the optional fleet agent's logs. Where Deploy Lite installed the systemd unit, the unit name is `aida-lite` (an implementation path, not a SKU): `journalctl -u aida-lite` on the device.
- Verify the device is in the target group on the release.
- Verify the device has the current signing public key — see **OTA Update Manager → Devices → Key Status**.

### "Deploy Lite for ESP32 cannot find my device"
- The device must be in **bootloader mode** for esptool to flash. Hold BOOT, tap RST, release BOOT.
- The USB cable must support data (not charge-only).
- On Windows, install the CP210x or CH340 driver matching your dev board.

### "Industrial PLC: how do I find my register addresses?"
Vendor docs. AidaIDE's PLC Monitor shows the canonical Modbus register layout (40001-49999 holding registers, 30001-39999 input registers, etc.) and lets you probe. Mismatched addresses = silent zeros. Always cross-check the PLC's own programming software.

---

# Network Tools

Source: https://aidaide.app/docs/network-tools

The **Network** menu collects every tool for looking at networks, traffic, and hosts. Camera-related items are split into their own submenu and have their own chapter ([Chapter 10](/docs/cameras)).

## At a glance

| Tab | Menu path | What it does |
| --- | --- | --- |
| Port Scanner | Network → Port Scanner | TCP/UDP port sweeps |
| Network Topology | Network → Network Topology | Live graph of hosts and links |
| Packet Capture | Network → Packet Capture | tcpdump-style capture and live decode |
| Traffic Analyzer | Network → Traffic Analyzer | Per-host traffic stats over time |
| Network Diagnostics | Network → Network Diagnostics | One-page ping/traceroute/dig dashboard |
| Host Discovery | Network → Host Discovery | LAN sweep with OS-fingerprinting |
| Service Detection | Network → Service Detection | Service+version banners on found hosts |

Every Network tab is a **feature tab** (pinned right of the connection tabs). They do not need a connection tab open.

## Port Scanner

Open from **Network → Port Scanner**.

The classic feature: type a host (or CIDR), tick **TCP** / **UDP**, pick a port range, click **Scan**. Results stream into a table with columns Host, Port, Protocol, State, Service.

Options worth knowing:

- **Quick / Common / All** — quick scans top 100 ports, common scans top 1000, all scans 1-65535. The first two are seconds; the last is minutes.
- **Concurrency** — default 200. Lower if your network kit drops packets under load.
- **Save Results…** — exports CSV or JSON.

Right-click a result row to:

- Open a connection tab to that host on that port.
- Send the host to Host Discovery for OS fingerprinting.
- Copy the host:port.

The scanner does **not** spoof or send malicious payloads. It is a TCP `connect()` scan plus optional UDP probes — entirely friendly traffic. Even so, do not scan networks you do not own or have written permission to.

## Network Topology

Open from **Network → Network Topology**.

Builds a live graph of devices it can see on your LAN by ARP-scanning, mDNS-scanning, and walking SNMP if community strings are set.

- **Nodes** are devices. Colour codes: green = responsive, yellow = stale, red = unreachable.
- **Edges** are inferred links (ARP neighbour, SNMP `lldpRemTable`, MAC-to-port).
- **Layout** — Force-directed (default), Hierarchical (root at your gateway), Radial.

Click a node to see its details panel — MAC, OS guess, open ports if Port Scanner has visited.

The topology tab spawns a background scanner thread. Closing the tab kills the thread (and reopening it restarts the scan from scratch).

## Packet Capture

Open from **Network → Packet Capture**.

A friendly tcpdump in a window:

- **Interface** dropdown — picks the NIC.
- **Filter** — BPF syntax (`tcp port 80`, `host 10.0.0.5`, etc.). Hints below the field.
- **Start / Stop** buttons.
- Live packet list, with per-packet decode (Ethernet → IP → TCP/UDP → payload) on click.

Capture buffer is in-memory and capped at 100k packets by default (Settings → Network → Capture Buffer). **Save as .pcap** exports for Wireshark.

Packet Capture needs admin/root to put the interface in promiscuous mode. On Windows this means launching AidaIDE elevated; on Linux either run elevated or grant `CAP_NET_RAW` to the Python interpreter.

## Traffic Analyzer

Open from **Network → Traffic Analyzer**.

Watches the same NIC over time and aggregates by host pair:

- Top talkers (sender / receiver / total).
- Per-host bandwidth chart.
- Per-protocol breakdown.
- Top destination ports.

You set the rolling window (1 min / 5 min / 15 min / 1 hr). Data is in-memory only — closing the tab loses it. **Export…** writes a CSV.

## Network Diagnostics

Open from **Network → Network Diagnostics**.

A one-page diagnostic panel for "is the internet on?" type questions:

- **Ping target** — default 8.8.8.8. Customisable.
- **DNS test** — resolves a configurable domain through your current resolver.
- **Traceroute** — to the same target.
- **Gateway test** — pings your default gateway.
- **Public IP** — fetches your apparent public IP.
- **MTU probe** — finds the largest packet size that survives end-to-end.

Each test is one button; results show in line below. Useful for handing the panel to a non-technical user so they can run the diagnostics and screenshot the result.

## Host Discovery

Open from **Network → Host Discovery**.

A more thorough version of "what is on this LAN?":

1. Enter a CIDR or single host.
2. AidaIDE pings, ARP-resolves, and (optionally) attempts OS fingerprinting via TCP/IP stack quirks.
3. Hits land in the results table.

This tab has historically rendered fabricated/demo data when no real scan is running. If you see entries that look fake (e.g. all-zero MACs, suspiciously round vendor names), confirm by running a fresh scan and watching for the spinner. Demo data is now clearly labelled, but bear it in mind if you see anything weird.

## Service Detection

Open from **Network → Service Detection**.

For each known host (from Host Discovery or a list you supply), opens common ports and grabs the service banner. Returns Service, Version, Vendor when it can.

This is what you run after Host Discovery if you want to know *what* the open ports are running, not just *that* they are open.

## Common Network workflows

### "I need to find the IP of my new Pi on the LAN"
1. **Network → Host Discovery** with your LAN CIDR (e.g. `192.168.1.0/24`).
2. Look for a hostname containing `raspberrypi` or a MAC starting with Raspberry Pi's prefix.

### "Something is hogging my upload bandwidth"
1. **Network → Traffic Analyzer** on the relevant interface.
2. Watch **Top Talkers** for a minute. The biggest sender is your culprit.

### "I need a pcap for the network team"
1. **Network → Packet Capture**.
2. Apply a BPF filter to scope the capture (e.g. `host 10.0.0.5`).
3. Start, reproduce the issue, stop, **Save as .pcap**.

### "What ports are open on this server?"
1. **Network → Port Scanner**.
2. Enter the host, **Common** preset, both TCP and UDP, **Scan**.

## Terms & Setup

### "I don't have a network to scan" — practice without disturbing real hosts
The Network tools are most fun on a real LAN, but you can try every tab on your own machine without touching anyone else's traffic. Pick the path that fits:

- **Scan your own machine (`127.0.0.1` / `localhost`).** Port Scanner accepts loopback. Spin up a quick service first — `python -m http.server 8080` in any terminal makes port 8080 visible to the scanner. Open / scanned / closed states all behave the way they do on a remote host. Stop the server with `Ctrl+C` and rescan to see the state flip to closed.
- **Scan your own subnet.** Your home LAN is fair game (you own it). Find your CIDR with **Network → Network Diagnostics → Local IP**, then point Host Discovery at e.g. `192.168.1.0/24`. You'll see your router, phones, printers, smart-home gadgets — everything that's awake.
- **A virtual lab in VirtualBox / VMware / QEMU / Multipass.** Spin up two or three small Linux VMs on a host-only network. Each one is a real, isolated target — perfect for Host Discovery, Service Detection, and Packet Capture without risking real production traffic. `multipass launch --name lab1 && multipass launch --name lab2` (with [Multipass](https://multipass.run/)) is the fastest way on macOS/Win/Linux.
- **A Docker-Compose toy network.** `docker compose up` a stack with an Nginx + a Redis + a Postgres container; every container is reachable from the host at `127.0.0.1:<published-port>`. Port Scanner sweeps the loopback range and Traffic Analyzer watches `docker0` / `vEthernet (WSL)` to see t

---

# Security Tools

Source: https://aidaide.app/docs/security-tools

The **Security** menu is the largest single menu in AidaIDE — eleven feature tabs for vulnerability hunting, dependency hygiene, certificate management, threat intelligence, and compliance. This chapter walks each one.

## Tab inventory

| Tab | Purpose |
| --- | --- |
| Security Scanner | General host scanner — ports, CVEs, weak ciphers |
| CVE Scanner | Match installed package versions against CVE feeds |
| Dependency Scanner | Project-level dependency audit (pip, npm, etc.) |
| Secret Scanner | Find leaked credentials in your code |
| SAST Scanner | Static application security testing |
| Threat Intel Feeds | Aggregated IOC + advisory feeds |
| IOC Database | Searchable indicator-of-compromise store |
| PKI Manager | Run your own CA |
| Certificate Inventory | Catalogue and monitor TLS certs |
| IP Access Control | Maintain allow/deny lists |
| Compliance Assessment | Run CIS / NIST / PCI checklists |

## Security Scanner

Open from **Security → Security Scanner**.

The general-purpose vulnerability sweep. Aim it at a host or a CIDR:

1. Enter target (host, IP, or CIDR).
2. Tick scan modules: Ports, CVEs (cross-references service banners against CVE database), Weak SSH ciphers, TLS misconfigurations.
3. Click **Scan**.

Results land in a tabbed report. Severity bands: Critical / High / Medium / Low / Info. Click any finding for context plus a suggested remediation.

**Export Report…** writes HTML, PDF, or JSON. The HTML report HTML-escapes every user-supplied field (host name, banner text) — this was a real XSS trap historically.

## CVE Scanner

Open from **Security → CVE Scanner**.

Targets a single Linux host (the focused connection tab, or one you pick). Reads `dpkg -l` / `rpm -qa` / `pip freeze` / `npm ls` and matches against the NVD CVE feed (auto-updated daily).

Findings include the CVE ID, base CVSS score, affected package + installed version + fixed version. **One-click "Apply fix"** runs the appropriate `apt upgrade <pkg>` or equivalent — counts as a WRITE operation and prompts for confirmation.

## Dependency Scanner

Open from **Security → Dependency Scanner**.

Different from CVE Scanner: this one scopes to a **project**, not a host. Reads `requirements.txt`, `package.json`, `Cargo.toml`, `go.mod`, `pom.xml`, etc. and checks each declared dependency against vulnerability databases (PyUp, npm Audit, RustSec, Snyk public feed).

Output includes vulnerable transitives, upgrade paths, and (when known) the minor/patch version that fixes the issue.

## Secret Scanner

Open from **Security → Secret Scanner**.

Walks a project folder looking for things that look like leaked secrets — AWS keys, GitHub tokens, GCP service account files, SSH private keys, generic high-entropy strings.

Configurable confidence threshold. Right-click a finding to **Mark False Positive** — the finding hash is added to a personal allow-list so you do not see it again.

**Tip:** run this before pushing to GitHub. Once a secret is in your git history, even deleting the file does not remove it from past commits.

## SAST Scanner

Open from **Security → SAST Scanner**.

Static Application Security Testing — analyses your source for vulnerability patterns without running it. Plugs into language-specific scanners:

- Python: `bandit` (+ semgrep rules).
- JavaScript/TypeScript: `eslint-plugin-security`, semgrep rules.
- Go: `gosec`.
- Java: `spotbugs` + `find-sec-bugs`.
- C/C++: `cppcheck`.

The relevant tool must be installed where AidaIDE can find it (locally, or in PATH on the host you are scanning). Settings → Security → SAST tells AidaIDE where each binary lives.

Findings are graded by severity and have remediation hints inline.

## Threat Intel Feeds

Open from **Security → Threat Intel Feeds**.

Subscribes to public + (configurable) private feeds:

- Abuse.ch URLhaus / MalwareBazaar.
- AlienVault OTX (needs an API key).
- MISP — point at your org's instance.
- CISA Known Exploited Vulnerabilities.

Aggregated indicators (hashes, IPs, domains, URLs) flow into the IOC Database (next section).

## IOC Database

Open from **Security → IOC Database**.

Searchable store of indicators of compromise. Filter by type (file hash / domain / IP / email / URL), by feed source, by date range. Manually add custom IOCs from incident reports.

Hooks into:

- **Network Topology** — if a node has an IP listed in the IOC database, the node turns red and the right-side panel calls it out.
- **Packet Capture** — packets sourcing from or destined to a flagged IP are highlighted.

## PKI Manager

Open from **Security → PKI Manager**.

Run your own certificate authority for lab and internal use.

- **Create a root CA** — generates a 4096-bit RSA or P-384 EC key plus a self-signed cert. Stored in the vault.
- **Create intermediates** — sign sub-CAs off the root.
- **Issue server certs** — SANs, lifetime, key type all configurable.
- **Revoke certs** — adds to a CRL.
- **Export trust bundle** — for installing the root CA on client devices.

Anything you issue here is **not trusted by browsers by default** — it is your private CA. Install the root cert manually on the boxes that need to trust it.

## Certificate Inventory

Open from **Security → Certificate Inventory**.

Catalogue of certs known to AidaIDE — those issued by your PKI plus any cert AidaIDE has seen in scans.

- **Import** — paste PEM/DER or point at a file. The CN, SANs, issuer, validity, fingerprint, and key info are extracted.
- **Scan host:port** — connects, grabs the cert, adds it to the inventory.
- **Expiry alerts** — set a per-cert reminder; the toolbar will warn 30 days out by default.
- **Compare two certs** — diff their subjects, SANs, key types.

Note: historically this tab has had bugs that fabricated CN values from filenames or computed fingerprints over raw file bytes instead of DER. If something looks off (CN that matches a filename rather than the subject; fingerprints that change every time you reimport the same file), reimport from a fresh source and report a bug.

## IP Access Control

Open from **Security → IP Access Control**.

Maintains allow / deny lists. These lists can be:

- Exported as iptables / nftables / Windows Firewall rule sets.
- Pushed to fleet devices that use aida-lite's firewall plugin.
- Consulted at scan time (so Port Scanner can skip known-bad ranges).

You can import community blocklists (Spamhaus DROP, Firehol, etc.) on a schedule.

## Compliance Assessment

Open from **Security → Compliance Assessment**.

Run pre-built compliance checklists against a host:

- CIS Linux Benchmark (Ubuntu, Debian, RHEL profiles).
- CIS Windows Benchmark.
- NIST 800-53 control families (selected).
- PCI-DSS host-level controls.

For each control, AidaIDE either probes via SSH commands or asks you to confirm manually. Output is a pass/fail dashboard plus an evidence trail you can export.

The compliance log is supposed to record every audit event with full audit-trail integrity. Historically some demo paths logged no-ops; expect every check to leave a row in the audit log when run for real.

## Workflows

### "I want to know if my Pi has any known vulnerabilities"
**Security → CVE Scanner**, target = your Pi's connection tab, **Scan**. Address Critical/High first.

### "Did I commit an AWS key by accident?"
**Security → Secret Scanner**, target = your project folder. Mark false positives, fix the real ones, **rotate the keys** (do not just delete the file — the leak is in git history).

### "I need an internal TLS cert for my lab"
1. **Security → PKI Manager**. Create a root CA (one time).
2. **Issue Server Cert** with the SAN matching your service hostname.
3. Install the resulting bundle on the server.
4. Install the root CA cert on each client that needs to trust the new cert.

### "I need to prove our hosts meet CIS Level 1"
**Security → Compliance Assessment → CIS Linux Benchmark → Level 1**. Run against each host. Export the report.

## Terms & Setup

### CVE
Common Vulnerabilities and Exposures. A globally unique ID for a specific bug — e.g. `CVE-2024-12345`. The CVE feed is hosted by NIST; AidaIDE mirrors a recent copy and refreshes daily.

### CVSS
Common Vulnerability Scoring System. A 0.0–10.0 score for severity. AidaIDE shows the **base** score in scan results.

### IOC
Indicator of Compromise. A piece of evidence that something bad has happened — a malicious file hash, a phishing URL, a C2 IP. Useful for detection ("alert if we ever see this IP again") and triage ("is the file the user downloaded known-bad?").

### CA, Root CA, Intermediate
A **Certificate Authority** signs certificates. The **root CA** is self-signed; **intermediates** are signed by the root and used to issue end-entity certs. Browsers ship with a list of public root CAs that they trust; private CAs (like the one PKI Manager creates) have to be installed manually on every device that needs to trust them.

### SAST vs DAST
**SAST** = Static. Reads source code without running it. **DAST** = Dynamic. Hits a running app from the outside. AidaIDE includes SAST out of the box. DAST coverage is via Security Scanner (TLS/port checks) and external tools.

### "I scanned myself and got no results"
- Scanners need either an SSH connection (for CVE Scanner / Compliance) or a project folder (for Dependency / Secret / SAST). If you launched them with no target, they bail silently.
- Some scanners need a binary on PATH (`bandit`, `gosec`, etc.) — see Settings → Security → SAST.

### "Report says I have 47 vulnerabilities, but most are Low"
That is expected. A normal Linux install has dozens of Low-severity findings (informational, theoretical, or already mitigated upstream). Focus on Critical/High first. The report's **Risk Score** is a weighted total — driving that down is the goal.

### "Certificate Inventory shows my cert's CN as something weird"
A historical bug in `_import_cert` derived the CN from the filename and computed the fingerprint over raw file bytes instead of the parsed DER. Reimport from a freshly downloaded PEM and verify against `openssl x509 -in cert.pem -noout -subject -fingerprint -sha256`. File a bug if it still misreports.

### Where the audit log lives
`~/.aidaide/audit.log`. Append-only. Each compliance check, PKI issuance, OTA publish, and bulk fleet action writes a row with timestamp + actor + action + target. Treat it as evidence; do not edit it by hand.

---

# AI Assistant and Sidebar

Source: https://aidaide.app/docs/ai-assistant

AidaIDE has two distinct ways to use AI: a **sidebar** that lives next to your code for casual back-and-forth, and a set of **AI feature tabs** for managing more complex multi-agent workflows. This chapter covers the everyday AI tools. The visual canvas for building agent pipelines is in [Chapter 9](/docs/hierarchy-builder).

## AI sidebar vs AI tabs

- **AI sidebar** — dockable panel on the left. Chat with the model, ask about the file you have open, get inline edit suggestions. One conversation at a time.
- **AI feature tabs** — full notebook tabs for purpose-built workflows: Claude Agent Manager (model setup), AI Workflows (recipe runner), AI Agent Portal / Persona Portal, Live Coding Agents, Agent Hierarchy Builder.

You can have both open. The sidebar is for "quick question," the tabs are for "this is its own task."

Toggle the sidebar with **AI → Toggle AI Sidebar** (`Ctrl+Shift+I`).

## AI Chat (`Ctrl+Shift+A`)

The simplest entry point. Opens the AI sidebar focused, with the chat composer at the bottom.

Things it can do out of the box:

- Answer general questions about your code if you have a file open and **Include current file** is ticked.
- Edit the file on request — pops up a diff preview before applying.
- Run shell commands on the focused connection if you grant permission per command.
- Reference the file tree of your project if **Include workspace context** is on.

The chat is stateful within a session. Sessions live until you close them or hit **New Chat**.

## Claude Agent Manager (`Ctrl+Shift+M`)

Open from **AI → Claude Agent Manager** or the green **★ AI Assistant** toolbar button.

The control panel for AI providers and agent presets:

- **Providers** — Anthropic Claude (recommended), OpenAI, Azure OpenAI, local Ollama. Each has its own API key field; keys are stored in the vault.
- **Model picker** — Claude Sonnet 4.6 / Opus 4.6 / Haiku 4.5 (or your provider's equivalents). Per-agent override possible.
- **Agents** — named profiles with custom system prompts. The default "Pair Programmer" agent ships ready to use. Create your own for "Embedded mentor," "Security reviewer," etc.
- **Test connection** — sends a one-token ping to verify the key.
- **Usage** — token counters per agent, per day. Helpful for cost-tracking.

You must have at least one provider configured for chat to work. The Onboarding Wizard prompts for this on first launch.

## Toggle Inline Suggestions

**AI → Toggle Inline Suggestions**.

When on, the editor shows greyed-out completion text after your cursor. Press `Tab` to accept, `Esc` to dismiss, keep typing to override. Off by default — turn it on once you have an API key configured and a model that is fast enough not to be annoying (Haiku is recommended for this use).

If suggestions are slow or wrong, narrow them with **Settings → AI → Inline Suggestions → Context window**.

## AI Workflows

Open from **AI → AI Workflows**.

A recipe runner for AI tasks that touch your filesystem or connections. Each workflow is a YAML/JSON file describing:

- Inputs (files, paths, parameters).
- A series of AI calls (with prompts).
- File-system and shell side effects.
- Output validation.

Built-in workflows include:

- **Refactor file** — propose, diff, apply.
- **Generate docstrings** — across a project.
- **Convert script to systemd unit** — for the focused connection.
- **Triage logs** — feed `journalctl` output, get a ranked list of issues.
- **Translate API client** — Python to Go, Node to Python, etc.

Click **New Workflow** to author your own. Saves to `~/.aidaide/workflows/`.

## AI Agent Portal

Open from **AI → AI Agent Portal**.

A chat-style UI where you talk to a single agent (one of the ones you defined in Claude Agent Manager). Differences from the AI sidebar:

- Each agent has its own persistent history.
- Agents can have tools attached (shell, file write, web fetch). Tool calls show inline.
- Useful for long-running "I have an assistant who knows this project" workflows.

## Persona Portal

Open from **AI → Persona Portal**.

Similar to AI Agent Portal but oriented around **personas** — pre-shaped characters with personality, tone, and lane. Ships with personas like "Wes, the patient mentor," "Macy, the interactive guide," "Astrid, the security skeptic." You can create your own.

Personas are agents plus narrative styling. Useful if you want the model to consistently sound a certain way (e.g. for documentation generation, for student-facing tutoring).

## Live Coding Agents (`Ctrl+Shift+J`)

Open from **AI → Live Coding Agents**.

An always-on "pair programmer over your shoulder" mode. Differences from chat:

- The agent watches what you do (file opens, edits, runs) and offers suggestions proactively.
- Suggestions appear as a non-modal toast in the bottom right. Click to expand, accept or dismiss.
- You can pin instructions ("I am refactoring auth.py, ask before touching anything else").

Token usage is higher than chat. Live Coding is best for focused sessions, not all-day idle.

## Saving and loading sessions

- **AI → Save Chat Session** (`Ctrl+Shift+Alt+S`) — writes the current sidebar conversation to disk. Pick a name.
- **AI → Load Chat Session** (`Ctrl+Alt+L`) — pick from saved sessions.

Saved sessions are JSON files in `~/.aidaide/chat_sessions/`. They include the model used, system prompt, every turn, and any attached files. You can share them with teammates or restore an interrupted thread.

## License gating

Some AI features are gated behind paid tiers:

- **AI Hierarchy** plan unlocks the Hierarchy Builder and the multi-agent runtime.
- **AI Agents** (basic) covers Claude Agent Manager, AI sidebar, AI Chat, Inline Suggestions, Live Coding Agents, AI Workflows.

If a feature is locked, the menu item is visible but greyed out, and clicking it pops a "Enter License Key" link → [Chapter 17](/docs/licensing).

## Tips

- **Reference a file** — paste its path with `@` in the chat composer (`@src/main.py`). The model sees the whole file in context.
- **Reference a line range** — `@src/main.py:42-58`.
- **Stop a response** — press `Esc` while it streams.
- **Branch a conversation** — right-click any message → **Branch from here**. Useful when an answer was almost right; rewind and try a different prompt.

## Terms & Setup

### API key
A long random string from your AI provider. AidaIDE stores it in the vault.

- **Anthropic Claude:** sign up at console.anthropic.com, create a key under **API Keys**. Paste into Claude Agent Manager → Anthropic → API Key.
- **OpenAI:** platform.openai.com → API Keys → Create. Same flow.
- **Azure OpenAI:** keys come from the Azure Portal; you also need the endpoint URL and the deployment name. All three go into the Azure provider config.
- **Ollama (local):** install Ollama on your machine. Point AidaIDE at `http://localhost:11434`. No API key required.

### "I don't have an API key yet" — setup paths
You can exercise the AI sidebar, AI Chat, AI Workflows, and the Hierarchy Builder before you pay any provider a cent. Pick the path that fits your situation:

- **Free local models via Ollama (recommended for tinkering).** Install Ollama from [ollama.com/download](https://ollama.com/download) (Win/macOS/Linux). On first launch it listens at `http://localhost:11434`. Pull a small model: `ollama pull llama3.2` or `ollama pull qwen2.5-coder:7b`. In **Claude Agent Manager → Providers**, pick **Ollama**, leave the API key blank, set the host to `http://localhost:11434`, hit **Test Connection** — you should see a green tick. No keys, no spend, fully offline. Slower than cloud for big prompts but fine for editor inline suggestions and chat. See [Chapter 8 §Claude Agent Manager](#claude-agent-manager-ctrlshiftm).
- **Anthropic Claude starting credits.** Sign up at [console.anthropic.com](https://console.anthropic.com) — new accounts receive a small starting credit (currently $5, may change) sufficient for hours of Haiku or Sonnet use. Create a key under **Settings → API Keys**, paste into Claude Agent Manager → Anthropic. The vault encrypts it at rest.
- **OpenAI starter credit.** [platform.openai.com](https://platform.openai.com) — same flow, occasional new-account credits. Lower-cost models (`gpt-4o-mini`) make a s

---

# AI Hierarchy Builder

Source: https://aidaide.app/docs/hierarchy-builder

The Hierarchy Builder is the visual canvas where you compose multi-agent pipelines. Drag chips, wire ports, click Run, watch data flow. This chapter walks the UI region by region.

> **Prerequisites — read these first if you're brand new:**
> - **An AI provider.** AI Agent modules call a live model. You need a working key (or a local Ollama instance) before **Run** does anything interesting. See [Ch. 8 §"I don't have an API key yet" — setup paths](/docs/ai-assistant#i-dont-have-an-api-key-yet--setup-paths).
> - **The AI Hierarchy plan.** The visual canvas is licence-gated separately from the API key. Open from **AI → Agent Hierarchy Builder** (`Ctrl+Shift+H`); if it's greyed out, see [Ch. 17 — Activating your license](/docs/licensing#activating-your-license).
> - **(Optional) Familiarity with the AI sidebar.** If everything in [Ch. 8](/docs/ai-assistant) is new to you, skim that chapter first — the building blocks here assume you've already chatted with a model once.

## Mental model

The builder is shaped like a circuit board.

- **SoC** — System on Chip. The outermost container. One canvas = one SoC.
- **IC** — Integrated Circuit. A chip you drop inside a SoC. Encapsulates a sub-workflow.
- **Module** — Leaf component inside an IC: a Supervisor, a Worker, an AI Agent, a Filter, a protocol node.

Data flows through **ports**. The SoC has SoC-level In/Out ports on its outer boundary. Each IC, when first placed, has IN-0 and OUT-0 ports. You wire them together with cyan signal lines.

```
┌────────────────── SoC ────────────────────────┐
│  ●SoC In ──────────────────► ●SoC Out         │
│                                                │
│   ┌──── IC: "Triage" ────┐                    │
│   │  IN-0 ──► [filter] ──► [agent] ──► OUT-0  │
│   └──────────────────────┘                    │
│                                                │
└────────────────────────────────────────────────┘
```

When you double-click an IC you **drill in** — the canvas zooms into that IC and shows its modules. The path is shown as breadcrumbs at the top so you can walk back out.

## Window layout

```
┌─────────────────────────────────────────────────────────────┐
│ Toolbar: Save | Load | Run | Pause | Stop | Trace | Theme   │
├──────────────┬──────────────────────────┬───────────────────┤
│ Library      │   Canvas                  │ Properties        │
│ ─ Search     │   (zoom, pan, multi-tab)  │   for selected    │
│ ─ Categories │                           │   node            │
│   (AI, Proto,│                           │                   │
│    Filter,...)│                          │                   │
│   drag from  │                           │                   │
│   library    │                           │                   │
│   onto       │                           │                   │
│   canvas     │                           │                   │
├──────────────┴──────────────────────────┤                   │
│ Minimap                                  │                   │
└──────────────────────────────────────────┴───────────────────┘
```

- **Library (left)** — searchable, collapsible sections. Drag a chip onto the canvas to place it.
- **Canvas (center)** — the actual board. Multi-tab; you can have several SoCs open at once.
- **Properties (right)** — settings for the selected node (model, prompt, parameters).
- **Minimap (bottom-left of canvas)** — bird's-eye view; click-to-jump.

## Component library

Top-level sections in the library sidebar:

- **SoC** — outer containers.
- **IC** — chip containers (drop into a SoC).
- **Agent Modules** — Supervisor, Worker, Critic, Planner, Retriever, AI Agent (generic with custom prompt).
- **Protocol Components** — HTTP request, MQTT publish/subscribe, WebSocket, SSE, Modbus query, OPC UA tag read.
- **Data / Filter** — Filter, Splitter, Joiner, Map, Reduce, JSON path, Regex extract.
- **IO** — File read/write, Database query, Stdout sink.

Search by name. Drag onto the canvas to place.

## Wiring data flow

1. Hover over a port on the source chip — the port becomes a target.
2. Click and drag to a port on the destination chip.
3. Release. A cyan line connects the two.

A few rules:

- Output ports connect to input ports. Input → input or output → output are rejected.
- You can branch one output to multiple inputs.
- Joining many outputs into one input requires a **Joiner** module (the runtime picks one signal otherwise).
- Click a wire and press `Delete` to remove it.

In-flight wires (mid-drag) can be cancelled with `Esc`.

## Properties panel

Click a node to populate the right-side panel. Common fields:

- **Name** — human label.
- **Description** — free-text, for documentation.
- **Model** (on AI Agents) — which Claude/OpenAI model.
- **System Prompt** — the agent's instructions.
- **Tools** — checkboxes for shell, file, web, MCP servers.
- **Retry / Timeout / Cost limit** — runtime guardrails.

Changes save automatically when you click off the field.

## Running a pipeline

The Execution Toolbar across the top of the canvas:

- **Run (▶)** — starts the SignalFlowEngine. Signals flow from SoC In, through every wired chip, out SoC Out.
- **Pause (⏸)** — stops new signals; in-flight modules finish.
- **Stop (■)** — cancels everything immediately.
- **Trace mode** — overlays per-message data on the wires as they fire. Slower; useful when debugging.

A running pipeline shows pulsing cyan on active wires. Each module shows a status badge: idle / running / waiting / errored.

Errors raise a non-modal toast at the bottom right with the module name and the exception. Click the toast to jump to that module on canvas and see the full trace in the properties panel.

## Autosave & crash recovery

Every 30 seconds, the current SoC is autosaved to `~/.aidaide/builder_drafts/` with a timestamp. If AidaIDE crashes mid-edit, the next launch prompts you to restore the most recent draft.

Manual save: **Save** in the toolbar. **Save As…** to give the file a permanent name. Pipelines you intend to keep should be saved under a name; drafts are auto-cleaned after 7 days.

## Pipeline & Teams

The "Pipelines" dropdown above the canvas has:

- **Create New** — scaffolds a fresh SoC with two-level ports (SoC In/Out plus a starter IC with IN-0/OUT-0).
- **AI Army Team** — a starter team-style pipeline (supervisor + 3 workers + critic).
- **Load Saved** — pick a previously saved SoC.

The chip library is extensible via the **Marketplace** (Tools → Plugins & Widgets → Marketplace Store) — installed chips show up in the library after a **Refresh Library** click. A `<<ChipLibraryChanged>>` event makes this happen automatically when the marketplace finishes.

## Navigation and tools

- **Zoom** — mouse wheel, or `Ctrl++` / `Ctrl+-`. Clamped at min/max per tier (you cannot zoom out of a SoC by scrolling).
- **Pan** — middle-click drag, or hold space + drag.
- **Drill in** — double-click an IC. Breadcrumbs at the top show the path.
- **Walk out** — click a breadcrumb, or press `Esc` (when nothing else is focused).
- **Minimap** — click anywhere in the minimap to pan the main view.
- **Select multiple** — drag a rubber-band, or `Ctrl+click` individual nodes.
- **Cut / Copy / Paste** — standard shortcuts.
- **Delete** — selected nodes and incident wires.

## Visual themes

The canvas honours the global AidaIDE theme. The brand defaults are navy `#0B1620` background and cyan `#4DE4E4` signals. Switch theme from **View → Theme** or the Hierarchy Builder toolbar's small palette icon.

## The guided tour

**Help → Ask Macy → Hierarchy Builder Tour** opens a 16-section voice-narrated walkthrough that highlights each region in turn. Useful first-pass for new users. You can dismiss any step early with **Skip**.

The 16 sections:

1. Welcome
2. Window Layout
3. Component Library
4. Canvas Workspace
5. Execution Toolbar
6. Agent Modules
7. Protocol Components
8. Wiring & Data Flow
9. Properties Panel
10. Control Panel
11. Pipeline & Teams
12. Advanced Features
13. Visual Theme
14. Navigation & Tools
15. Power User Features
16. Finish

## Worked example — "Triage support tickets"

A minimal pipeline that demonstrates the workflow:

1. **Create New** — fresh SoC scaffolded with SoC In/Out and one starter IC.
2. Rename the IC to "Triage."
3. **Drill in** to the IC.
4. Drag from library: a **JSON path** filter, an **AI Agent**, a **Joiner**.
5. Wire: `IN-0 → JSON path (extract subject+body) → AI Agent (classify into [bug, feature_request, billing]) → Joiner → OUT-0`.
6. On the AI Agent, set Model = Sonnet, System Prompt = "Classify the message…".
7. **Walk out** of the IC.
8. Wire `SoC In → IC IN-0` and `IC OUT-0 → SoC Out`.
9. **Run**. The Properties panel of SoC In has a manual-trigger field — paste a ticket JSON, click **Send**, watch the signal pulse through to SoC Out where the classification appears.

That is the whole shape. Pipelines that read from a Slack source, fan out to multiple workers, and write to a database are built the same way with more chips and more wires.


## Web Composer (browser version)

A browser version of the Hierarchy Builder ships with the Cloud Portal. Open it from a device's web dashboard via the **Composer** button. It mirrors the desktop builder's modes (flat / IC / SoC / hierarchy) and shares its document format — drafts in `~/.aidaide/builder_drafts/` round-trip between the two.

The web toolbar has **Zoom In / Out / Fit**, **Auto Layout**, **Auto Wire**, **Validate**, and **Run / Stop**. See [Ch. 21 §Web Hierarchy Composer](/docs/cloud-portal-docs#web-hierarchy-composer) for the full walkthrough and known parity gaps (animated trace, right-click menus, Macy tour are desktop-only as of 2026-05-29).

## Terms & Setup

### SignalFlowEngine
The in-process runtime that walks the graph and executes modules. Each wired connection becomes a queue; each module is an async coroutine driven by `_chip_module_executor`. Runs in the AidaIDE process, no external orchestrator.

### Trace mode
A run option that emits per-message snapshots into the canvas overlay. Adds overhead — turn off for benchmark runs.

### Drafts
Autosave files in `~/.aidaide/builder_drafts/`. Auto-clean after 7 days. Drafts you want to keep should be **Save As**-ed into your own folder.

### "My wire will not connect"
- Both endpoints must be ports. Hover until the port turns highlighted before clicking.
- Direction matters: output → input.
- One input usually accepts one wire (Joiner is the exception).

### "My pipeline runs but produces nothing"
- Check the SoC's Out port. If the chain inside ends at an IC whose OUT-0 is not wired to SoC Out, nothing leaves.
- Use **Trace mode** to see which wire stops carrying messages.

### "A module errors out repeatedly"
- Properties → click the module → look at the **Last error** field.
- For AI Agents: bad API key, rate limited, or the system prompt asks for a tool the age

---

# Cameras

Source: https://aidaide.app/docs/cameras

AidaIDE includes a small suite of IP-camera tools — discovery, single-camera viewing, and grid wall views. Useful for lab/workshop monitoring, simple security setups, and dev/test against ONVIF cameras.

## Menu layout

The camera tools live under **Network → Cameras**:

- **Camera Manager** — list, configure, and connect to known cameras.
- **Scan for Cameras** — ONVIF/RTSP discovery sweep of your LAN.
- **Camera Grid Viewer** — a customisable wall of feeds (3 × 3 or N × M).
- **Camera Feed Grid** — quick grid of all known cameras at once.

## Camera Manager

Open from **Network → Cameras → Camera Manager**.

Three regions, same shape as Fleet Manager:

```
┌────────────────────────────────────────────────────┐
│ Toolbar: Add | Scan | Connect All | Save           │
├──────────┬─────────────────────────────────────────┤
│ Groups   │ Camera table                            │
│  All     │   Name      IP           Type   Status  │
│  ├ Lab   │   front-door 10.0.0.31   ONVIF  ●live   │
│  └ Shop  │   shop-cam2 10.0.0.32    RTSP   ○off    │
│          ├─────────────────────────────────────────┤
│          │ Detail panel — preview + settings        │
└──────────┴─────────────────────────────────────────┘
```

### Adding a camera

1. Click **Add**.
2. Fill:
   - **Name** — friendly label.
   - **IP / host** — camera's address.
   - **Type** — ONVIF, RTSP, HTTP MJPEG, USB.
   - **Stream URL** — auto-filled for ONVIF, manual for the rest (e.g. `rtsp://user:pass@10.0.0.31:554/stream1`).
   - **Username / password** — credentials saved in the vault.
3. **Save**. AidaIDE pings the camera and a thumbnail appears in the detail panel if it can connect.

### Detail panel

Per-camera config: stream URL, resolution, framerate, snapshot interval. **Snapshot now** grabs a still. **Live preview** opens the feed in a separate detail subtab.

## Scanning for cameras

Open from **Network → Cameras → Scan for Cameras**.

Probes the LAN for cameras using two methods:

1. **ONVIF WS-Discovery** — broadcasts a WS-Discovery probe; ONVIF cameras reply with their endpoint.
2. **RTSP banner grab** — connects to TCP 554 on each host in the scope and checks for an RTSP banner.

Results table shows each discovered camera. Tick the ones you want and **Add to Manager** — pre-fills the Add Camera dialog.

Some cameras require authentication before they will respond. If a candidate appears with no name/model, you may need to provide credentials and re-probe.

## Feed Grid vs Grid Viewer

Two similar but distinct tabs:

- **Camera Feed Grid** — auto-populated wall of every camera in Camera Manager. Best for a quick "are they all alive?" glance.
- **Camera Grid Viewer** — manually arranged wall. You pick which cameras go where, set the grid size (2×2, 3×3, 4×3, custom), and AidaIDE remembers the layout.

Both tabs:

- Click any cell to expand to full-screen.
- Right-click → **Snapshot** to grab a still.
- Right-click → **Open in Browser** to view the raw stream URL.

## Workflows

### "I just installed an ONVIF camera and need to add it"
1. **Scan for Cameras**. Wait for results.
2. Find your camera in the list. Tick it.
3. **Add to Manager**. Fill in credentials.
4. The detail panel preview confirms the feed works.

### "I want a grid of 6 cameras on a second monitor"
1. Add all 6 to Camera Manager.
2. **Camera Grid Viewer** → set grid to 3×2.
3. Drag camera names into the cells.
4. **Save Layout**.
5. Drag the tab out of the main window onto your second monitor. AidaIDE remembers the placement.

### "RTSP feed will not connect"
- Test the URL with VLC (`Media → Open Network Stream → rtsp://...`). If VLC fails, the camera is the problem.
- Some cameras serve substreams at separate paths — try `stream1`, `stream2`, `Streaming/Channels/101`, `cam/realmonitor`.
- Authentication: most RTSP cameras require credentials. Embed them in the URL or use the Camera Manager username/password fields.

## Performance

Camera tabs run a decoder thread per visible feed. Eight or more concurrent 1080p H.264 feeds will use noticeable CPU. To lower load:

- **Settings → Network → Cameras → Default Substream** = `low`. Most cameras have a sub-stream at lower resolution; AidaIDE will prefer it.
- Reduce framerate per camera in its detail panel.
- Use **Camera Manager** for monitoring (decodes only the focused camera) rather than the grids when CPU matters.

## Terms & Setup

### ONVIF
Open Network Video Interface Forum — the SOAP-based standard for IP cameras. Lets you discover, configure, and stream from any compliant camera with one client. AidaIDE supports ONVIF Profile S (live streaming) and Profile T (advanced video).

### RTSP
Real-Time Streaming Protocol. The transport most IP cameras actually use to deliver video, often discovered via ONVIF.

### Substream
Many cameras encode two simultaneous video streams — a high-quality main stream and a lower-resolution sub-stream. Use the sub-stream for grid views to save CPU.

### "I do not have a camera"
- USB webcams work — pick **Type = USB** in Add Camera. The dropdown lists available USB video devices.
- Smartphone IP-camera apps (DroidCam, IP Webcam on Android, iCam on iOS) expose RTSP/HTTP MJPEG streams. Point AidaIDE at the URL the app gives you.
- For testing without hardware, [FFmpeg can act as an RTSP server](https://trac.ffmpeg.org/wiki/StreamingGuide#Pointtopointstreaming): `ffmpeg -re -i file.mp4 -c copy -f rtsp rtsp://localhost:8554/test` then connect AidaIDE to `rtsp://localhost:8554/test`.

### Recording
The current camera tabs are live-only. There is no built-in recorder. For continuous recording, point a separate NVR (Frigate, ZoneMinder, Shinobi) at your cameras and use AidaIDE for ad-hoc viewing.

### "The camera grid is laggy or stuttering"
- Confirm the network path — wifi cameras at the edge of range will drop frames.
- Switch to substream feeds.
- Reduce framerate (most cameras default to 25-30 fps; 10 fps is fine for monitoring).
- Close the tab when you are not actively looking at it; the decoder thread suspends.

---

# Databases

Source: https://aidaide.app/docs/databases

The Database section gives you a basic admin UI for the four most common engines and a generic Query Editor for ad-hoc work. It lives in the **Preview → Database** submenu (some features may be marked Beta).

## Menu layout

- **Database Manager** — central registry; pick a connection and drill in.
- **MySQL Management** — per-engine tab with MySQL-specific tools.
- **PostgreSQL Management** — same, for Postgres.
- **MongoDB Management** — same, for Mongo.
- **Redis Management** — same, for Redis.
- **Query Editor** — multi-tab SQL workspace.
- **DB Connection Manager** — saved connection registry.

## Database Manager

Open from **Preview → Database → Database Manager**.

The hub. Left panel lists saved connections by engine; click one to open it on the right with the engine-appropriate UI (table browser for SQL engines, key browser for Redis, collection browser for Mongo).

Buttons across the top:

- **New Connection** — adds a connection of any supported engine.
- **Query** — opens the Query Editor pointed at the selected connection.
- **Disconnect / Reconnect** — toggle the current connection.

## Saving connections

**Preview → Database → DB Connection Manager** is the central registry.

Each connection has:

- **Name** — friendly label.
- **Engine** — MySQL, PostgreSQL, MongoDB, Redis.
- **Host / Port** — engine defaults (3306 / 5432 / 27017 / 6379) are pre-filled. Override as needed.
- **Username / Password** — saved in the vault.
- **Default database** — optional.
- **TLS** — enable for hosted DBs that require it.

## Per-engine tabs

### MySQL Management
Open from **Preview → Database → MySQL Management** or via Database Manager.

- **Databases / Tables** tree.
- **Structure** view — columns, types, indexes, foreign keys.
- **Data** view — paged table editor. Inline edits write back as `UPDATE`.
- **SQL** view — drop straight into the Query Editor scoped to this connection.
- **Users & Privileges** — list current users, grant/revoke. WRITE operations require confirmation.
- **Status** — `SHOW STATUS`, `SHOW PROCESSLIST`.

### PostgreSQL Management
Equivalent to MySQL but with Postgres-specific extras:

- Schemas separate from databases.
- **Roles** in place of MySQL users.
- **Extensions** browser — install/remove with confirmation.
- `EXPLAIN ANALYZE` button on any SELECT in the data view.

### MongoDB Management
NoSQL — different vocabulary:

- **Databases → Collections → Documents** tree.
- Document view in JSON. Edit inline; save with `Ctrl+S`.
- **Indexes** subtab — create/drop.
- **Aggregation** — pipeline builder with JSON stages.

### Redis Management
Key-value:

- Key browser, scoped by pattern (`user:*`, `session:*`).
- Per-type editors: String, Hash, List, Set, ZSet, Stream.
- TTL editor on every key.
- **CLI** subtab — interactive Redis CLI in a pane.

## Query Editor

Open from **Preview → Database → Query Editor** or from any per-engine tab.

A multi-tab SQL workspace:

- One tab = one query buffer.
- Top of each tab: **Connection** dropdown (pick which saved DB), **Run** (`F5`), **Run Selection** (`F8`), **Explain**.
- Results in a paged table at the bottom.
- **Export Results…** writes CSV / JSON / Excel.

Syntax highlighting honours the engine. Autocomplete suggests tables, columns, and keywords.

Keyboard shortcuts (when the editor is focused):

| Action | Shortcut |
| --- | --- |
| Run all | `F5` |
| Run selection or current statement | `F8` |
| Explain (analyzes plan) | `Shift+F5` |
| New query tab | `Ctrl+T` |
| Save query | `Ctrl+S` |
| Save query as… | `Ctrl+Shift+S` |
| Format SQL | `Ctrl+Shift+F` |

Saved queries land in `~/.aidaide/sql/` by default.

## WRITE confirmations

The same READ/WRITE classification used in LCOT applies here:

- `SELECT` — runs immediately.
- `INSERT / UPDATE / DELETE / DROP / TRUNCATE / ALTER / CREATE` — confirmation dialog showing the SQL and an estimated affected-row count (when AidaIDE can derive one from `EXPLAIN`).

`Run Selection` (`F8`) runs only what is highlighted, useful when you have a destructive statement next to a SELECT and only want the SELECT.

## Workflows

### "I need to peek at production data without breaking anything"
1. Add a read-only DB user on the server.
2. **DB Connection Manager → New** with those credentials.
3. Open in **Query Editor**. The WRITE confirmations will fail anyway because of permissions, but the principle is "least privilege at the credential layer."

### "Quickly find a column across all tables"
1. **MySQL/PostgreSQL Management → connection → schema → Search…** (top-right magnifier).
2. Search matches table names, column names, and column comments.

### "Export a query result to my team"
1. Run the query in Query Editor.
2. **Export Results… → Excel** (or CSV).
3. The file lands wherever you point. UTF-8 encoded by default.

## Terms & Setup

### Connection vs database
A **connection** is an authenticated session to a database server. A **database** (or schema, or namespace) is a logical container inside that server. One connection → many databases/schemas/collections.

### TLS
Transport Layer Security. Encrypts traffic between AidaIDE and the database server. Required by most cloud-hosted DBs (RDS, Cloud SQL, Atlas, Upstash). Enable in the connection's TLS tab; provide CA cert if the server uses a private CA.

### "I do not have a database to play with"
- **SQLite** — bundled with Python; create a file with `sqlite3 mydb.db`. AidaIDE's Database Manager will pick it up if you set Engine = SQLite (Beta — limited features).
- **Docker** — `docker run -e MYSQL_ROOT_PASSWORD=root -p 3306:3306 mysql:8` gives you MySQL in 30 seconds. Add `postgres:16`, `mongo:7`, or `redis:7` for the others.
- **Cloud free tiers** — PlanetScale (MySQL), Supabase (Postgres), MongoDB Atlas, Upstash (Redis) all have generous free tiers.

### "My password worked yesterday and not today"
- Server-side password change is the usual cause.
- Some hosted DBs rotate IPs and require allow-listing yours — check the provider's network policy.
- Re-enter the password in DB Connection Manager — if the vault entry got corrupted, this fixes it.

### Performance tips
- Use `Run Selection` for large scripts so you can step through.
- The result grid pages 1,000 rows at a time by default — change in Settings → Database → Page Size.
- Closing the per-engine tab closes its connection. For long-running scripts, prefer Query Editor (its connections persist).

### Privileges and safety
WRITE confirmation is in the UI; it is not a substitute for proper DB user permissions. For anything connected to a production DB:

- Use a read-only account in the connection if you only need to view.
- Use a read-write account *only* in a dedicated connection labelled clearly.
- Never paste production credentials into a connection named "dev."

### "The MongoDB Document editor will not save"
- Documents are validated as JSON before save. A missing comma kills it.
- Numeric IDs (`_id` set as int) get coerced. If you have `ObjectId(...)`, keep it in the `$oid` shorthand.
- If you replace a doc, Mongo replaces the *whole* doc (not just changed fields). Use the **Update Fields** button for a partial update instead.

---

# Sysadmin Tools

Source: https://aidaide.app/docs/sysadmin

The **Preview → Sysadmin** submenu collects everything aimed at IT operations — Windows management, patch management, configuration management, containers, monitoring, alerting, backup, and disaster recovery. The tools share a feature-tab layout and most can be driven against a single host or a fleet group.

## Menu layout

```
Preview
└── Sysadmin
    ├── Windows Management ▶
    │   ├── WinRM Client
    │   ├── Active Directory
    │   ├── Windows Services
    │   └── Windows Updates
    ├── Patch Manager
    ├── Patch Policies
    ├── Configuration Management ▶
    │   ├── Ansible Runner
    │   ├── Desired State Configuration
    │   ├── Config Drift Detection
    │   └── Template Manager
    ├── Containers ▶
    │   ├── Docker Manager
    │   ├── Docker Compose
    │   ├── Kubernetes Client
    │   └── Registry Client
    ├── Monitoring Dashboard
    ├── Alert Manager
    ├── Metrics Collector
    ├── Backup Manager
    └── Disaster Recovery
```

## Windows management

### WinRM Client
Open from **Preview → Sysadmin → Windows Management → WinRM Client**.

Connects to Windows hosts via WinRM (HTTP 5985, HTTPS 5986). The remote box needs WinRM enabled — on the target, run `Enable-PSRemoting -Force` in an elevated PowerShell.

Once connected, you get a PowerShell-like terminal. WinRM is the Windows analogue of SSH; commands run as the authenticated user.

### Active Directory
**Preview → Sysadmin → Windows Management → Active Directory**.

Browse and search AD objects:

- Users — list, find, view memberOf, disable/enable (WRITE).
- Groups — membership view, add/remove members (WRITE).
- Computers — list, OS, last logon.
- OUs — tree view.

Needs an LDAP bind credential. AD ports: 389 LDAP, 636 LDAPS. Use LDAPS for anything beyond a lab.

### Windows Services
**Preview → Sysadmin → Windows Management → Windows Services**.

Equivalent of `services.msc` over WinRM. List services, start/stop/restart, change startup type. All WRITE actions confirm.

### Windows Updates
**Preview → Sysadmin → Windows Management → Windows Updates**.

Inventory of pending updates on a remote Windows host. Approve and install via `Install-WindowsUpdate` (requires the PSWindowsUpdate module on the target — install with `Install-Module PSWindowsUpdate`).

## Patch management

### Patch Manager
**Preview → Sysadmin → Patch Manager**.

Cross-platform patch inventory. Targets a host or a fleet group:

- **Linux**: aggregates `apt list --upgradable` / `dnf check-update` / `yum check-update` output.
- **Windows**: pulls pending updates via WinRM.
- **Container hosts**: image vulnerability counts via Trivy if available.

Per-host findings table: package, current, available, severity (security/normal). Bulk **Approve & Apply** runs the appropriate package manager command in parallel.

### Patch Policies
**Preview → Sysadmin → Patch Policies**.

Per-group rules: when to auto-approve (e.g. security-only auto-approve, normal patches require human approval), maintenance windows, reboot policy.

Policies are JSON files in `~/.aidaide/patch_policies/`. Editable in the UI or directly.

## Configuration management

### Ansible Runner
**Preview → Sysadmin → Configuration Management → Ansible Runner**.

A friendly UI on top of `ansible-playbook`:

- Pick or write a playbook (top pane).
- Pick an inventory (or use Fleet group as inventory).
- Variables (key=value list).
- Run.

Output streams below with per-task status. Failures highlighted. `ansible` and `ansible-playbook` must be installed locally; AidaIDE shells out to them.

### Desired State Configuration
**Preview → Sysadmin → Configuration Management → Desired State Configuration**.

For Windows: leverages PowerShell DSC. Pick a `.ps1` configuration, target hosts, push. Compliance results in a table.

For Linux: a thin wrapper around chosen DSC-style tools (your install) — useful if your team standardised on something other than Ansible.

### Config Drift Detection
**Preview → Sysadmin → Configuration Management → Config Drift Detection**.

Captures a baseline snapshot of a host (selected config files, package set, service states) and periodically re-snapshots to detect drift. Drift summary highlights what changed and when.

Default baseline paths: `/etc/`, `/usr/local/etc/`, plus per-service add-ons (nginx, postgres, etc.). Configurable.

### Template Manager
**Preview → Sysadmin → Configuration Management → Template Manager**.

Library of config templates (Jinja2) with per-host variable sets. Render → preview → push.

## Containers

### Docker Manager
**Preview → Sysadmin → Containers → Docker Manager**.

Docker desktop UI for a single host (local or remote):

- **Containers** — list, start/stop, logs, exec.
- **Images** — list, pull, build, prune.
- **Volumes / Networks** — basic management.

Connects via the Docker socket. For remote hosts, that means either Docker context (`docker context create`) or socket-over-SSH (the Docker Manager UI sets it up).

### Docker Compose
**Preview → Sysadmin → Containers → Docker Compose**.

Project-level UI: open a `docker-compose.yml`, get a graphical view of services and dependencies, up/down/restart per-service or all.

### Kubernetes Client
**Preview → Sysadmin → Containers → Kubernetes Client**.

Read-friendly kubectl-on-rails:

- Namespace + resource tree.
- Pods → describe / logs / exec.
- Deployments → rolling restart.
- Apply YAML from an editor pane.

Uses your `~/.kube/config`. Context switcher at the top.

### Registry Client
**Preview → Sysadmin → Containers → Registry Client**.

Browse Docker registries (Docker Hub, GHCR, ECR, GCR, private). Search images, view tags, pull. Push requires login (Docker CLI must be configured on your machine).

## Monitoring & alerts

### Monitoring Dashboard
**Preview → Sysadmin → Monitoring Dashboard**.

A grid of host health cards (CPU, memory, disk, load, network). Each card pulls from aida-lite metrics if installed, else from on-demand SSH probes.

Configurable refresh interval. Click a card to drill into a per-host metrics page with line charts.

### Metrics Collector
**Preview → Sysadmin → Metrics Collector**.

Configures what AidaIDE collects from each host: which metrics, what interval. Metrics are stored locally in a TSDB (`~/.aidaide/metrics.db`) and queried by Monitoring Dashboard.

For larger setups, point AidaIDE at Prometheus or InfluxDB instead of using the local TSDB.

### Alert Manager
**Preview → Sysadmin → Alert Manager**.

Rules engine on top of collected metrics:

- IF `cpu_load > 90% for 5 min` THEN webhook / email / Slack.
- IF `disk_free < 10%` THEN email + open a Fleet Manager flag.

Channels configured in **Settings → Network → Notifications**. Each rule has a per-channel routing.

## Backup & disaster recovery

### Backup Manager
**Preview → Sysadmin → Backup Manager**.

Per-host backup jobs:

- **Source** — paths on the remote host.
- **Destination** — local archive directory, S3-compatible bucket, or rsync target.
- **Schedule** — one-shot, daily, weekly, custom cron.
- **Retention** — keep N days / N copies.

Jobs run on the AidaIDE host (your machine), pulling from remotes over SFTP or running remote `tar`/`rsync` as appropriate.

### Disaster Recovery
**Preview → Sysadmin → Disaster Recovery**.

Restoration side of Backup Manager. Pick a backup snapshot, pick a destination host, push the contents. Useful for "the SD card died, here is the replacement Pi, make it look like the old one."

DR also documents your runbooks — a per-host page with notes, contact info, snapshot history.

## Workflows

### "Patch every Pi in the lab"
1. **Patch Manager**.
2. Target = Fleet group "Lab."
3. Filter to security updates only.
4. **Approve & Apply**. AidaIDE runs `apt upgrade <pkg>` per host in parallel.
5. Watch the per-host status table.

### "Drift hunt — what changed on prod-web-01 this week?"
1. **Config Drift Detection** → prod-web-01.
2. **Snapshot history** → last 7 days.
3. Click a diff row to see file-level changes.

### "Spin up a new microservice on my k8s cluster"
1. **Kubernetes Client → Apply YAML**.
2. Paste/import the Deployment + Service.
3. Apply. Watch pod status in the tree.

### "Set up nightly backups of /etc on every Pi"
1. **Backup Manager → New Job**.
2. Source = `/etc`, destination = local archive directory.
3. Schedule = daily at 03:00.
4. Retention = 30 days.
5. **Add** all Pis from the fleet group.

## Terms & Setup

### WinRM
Windows Remote Management. The Microsoft protocol for running PowerShell on remote Windows boxes. Two ports — 5985 (HTTP, lab only) and 5986 (HTTPS). Disabled by default; enable with `Enable-PSRemoting -Force` on the target.

### LDAP / LDAPS
Lightweight Directory Access Protocol. How you talk to Active Directory. LDAPS is LDAP-over-TLS — use it.

### DSC (Desired State Configuration)
PowerShell's "make the system look like X" framework. Configurations are PowerShell scripts that compile to MOF files; nodes pull or push their configurations.

### Ansible
A Python tool that runs YAML playbooks over SSH. AidaIDE wraps the CLI; the actual Ansible must be installed locally.

### Container vs image
An **image** is a snapshot of a filesystem. A **container** is a running instance of an image. `docker pull` fetches an image; `docker run` creates a container from it.

### Kubernetes — quick orientation
- **Pod** — one or more containers running together.
- **Deployment** — declarative spec that maintains N pods.
- **Service** — stable network endpoint in front of pods.
- **Namespace** — logical partition for scoping.

### "I do not have any Windows boxes to manage"
The Windows tabs are no-ops without targets. Skip them and use the Linux/container tools.

### "I do not have Ansible installed"
Install: `pip install ansible` (or use your package manager). On Windows, use WSL — Ansible's control machine is Linux-only.

### Alert delivery setup
- **Email** — SMTP creds in Settings → Network → Notifications → SMTP.
- **Slack** — a webhook URL from your Slack workspace's "Incoming Webhooks" app.
- **Generic webhook** — a URL AidaIDE will POST a JSON body to. Useful for routing into PagerDuty, Opsgenie, n8n.

### "My backup job hangs"
- SFTP over slow links is the usual culprit. Use `rsync` with compression instead (set in the job's transport field).
- Some files are unreadable by your SSH user. Check the error log; either skip them in the source spec or switch to a privileged user.

---

# Settings, Themes, Preferences

Source: https://aidaide.app/docs/settings-themes

The **Settings** dialog is the single place where you configure how AidaIDE looks and behaves. Open with **File → Settings** (`Ctrl+,`) or the gear icon at the far right of the toolbar.

## Layout

The Settings panel is a Toplevel window with categories down the left and the active category's controls on the right. Each category has its own "Reset to Defaults" link in the lower-right.

```
┌─────────────────────────────────────────────────────────────┐
│ ┌──────────────┐ │ Active panel                             │
│ │ General      │ │   ─ control                              │
│ │ Appearance ★ │ │   ─ control                              │
│ │ Workspace    │ │   ─ control                              │
│ │ Editor       │ │   ─ control                              │
│ │ SSH          │ │                                          │
│ │ Security     │ │                                          │
│ │ Network      │ │                                          │
│ │ Plugins      │ │                                          │
│ └──────────────┘ │                                          │
│                  │  Reset this section to defaults          │
└─────────────────────────────────────────────────────────────┘
```

Changes save automatically when you click off a field. Closing the dialog never asks "save changes?" because everything is already saved.

## General

- **Startup behaviour** — open with last workspace / open empty / show launcher.
- **Confirm on exit** — toggle.
- **Telemetry** — opt-in anonymous usage data. Off by default.
- **Locale** — language and date format (en-US is the only fully translated locale at present).
- **Working directory** — where AidaIDE's data dir lives (vault, logs, workspaces). Move with care; restart required.

## Appearance

The heaviest section.

### Themes and appearance

- **Theme** — drop-down of available colour themes. The brand defaults are **AidaIDE Dark** (navy + cyan) and **AidaIDE Light**. Add-on themes ship via plugins or live in `~/.aidaide/themes/`.
- **Accent colour** — overrides cyan with another. Useful for branding a deployment.
- **Font size (UI)** — base size in points.
- **Window opacity** — 100% on by default; reduce for see-through windows on supported platforms.

### Layout

- **Workbench shell** — **View → Workbench → Use the workbench shell**, on by default. Uncheck it and restart for the classic tabbed window. There is no Classic Tabs vs Grid setting. See [Chapter 16](/docs/workspaces).
- **Side panel positions** — left / right / hidden for each panel (Files, AI, LCOT).
- **Status bar** — visible / hidden.
- **Tab bar style** — Top / Side.

### Animations

- Toggle splash, toolbar hover effects, sidebar slide animations. All cosmetic; off if you find them distracting.

## Workspace

**Settings → Workspace** lists your named layouts (rc18, desktop app):

- **Open** — switch to a saved layout. Connections stay connected.
- **Save current as...** — save the current arrangement under a name.
- **Delete** — remove a named layout.

The same list is the toolbar **Workspace** control and **Save**, and **View → Workbench**. Each layout is a file in `~/.aidaide/layouts/`. A layout that names a missing widget opens without it and says so. Layouts are not in the Marketplace. See [Chapter 16](/docs/workspaces).

## Editor

### Font and spacing

- **Editor font family** — Consolas, JetBrains Mono, Fira Code, etc. (whatever is installed on your system).
- **Editor font size**.
- **Line spacing**.
- **Tab size** — width of `\t` and indent. Default 4.
- **Insert spaces** — convert Tab key to spaces. Default on.

### Behaviour

- **Auto-save** — off / on save loss / every N seconds.
- **Format on save** — runs the language formatter when you save.
- **Highlight current line**, **Show line numbers**, **Show whitespace**, **Wrap long lines** — all toggles.
- **Default encoding** — UTF-8 (do not change unless you know exactly why).
- **Default line endings** — LF / CRLF / platform.

### Syntax

- Add custom highlight rules per file extension.
- Toggle inline lint warnings (Python / JS).

### LCOT

- **Hidden commands** — list of built-in LCOT command IDs to suppress in the tree.
- **Custom command file** — path to your `lcot_user_commands.json`. Defaults to `~/.aidaide/lcot_user_commands.json`.

## SSH

- **Default port** — 22.
- **Connection timeout** — seconds.
- **Keepalive interval** — seconds. 0 disables.
- **Default key path** — pre-fills the Add Host dialog.
- **Auto-accept new host keys** — off by default and recommended off. On is convenient but kills the host-key-change warning that catches MITM.
- **Known hosts file** — defaults to `~/.aidaide/known_hosts`. Separate from `~/.ssh/known_hosts` to keep AidaIDE's history isolated.
- **Terminal type** — `xterm-256color` by default.

## Security

- **Vault timeout** — re-lock the vault after N minutes of inactivity. 0 disables.
- **Require password on resume** — pop the unlock dialog when the OS resumes from sleep.
- **Encryption profile** — Standard (AES-GCM via Fernet) or Strong (Scrypt + AES-GCM with longer derivation). Strong is slower on first unlock.
- **Audit log path** — `~/.aidaide/audit.log` by default.
- **SAST scanner paths** — per-language binary locations (bandit, gosec, eslint, etc.).
- **CVE feed refresh** — interval (daily by default).

## Network

- **DNS resolver** — system / Cloudflare / Google / custom.
- **HTTP proxy** — for outbound requests (CVE feed updates, plugin marketplace).
- **Capture buffer** — max packets retained by Packet Capture.
- **Notifications** — SMTP server for email alerts, Slack webhook URL, generic webhook URL.
- **Polling** — Fleet Manager / Monitoring Dashboard refresh interval.

## Plugins

- **Marketplace URL** — defaults to AidaIDE's hosted store.
- **Enabled plugins** — toggle each on/off. Disabled plugins remain installed but inert until re-enabled (restart required).
- **Trusted authors** — list of publishers whose plugins do not require per-install confirmation.
- **Plugin install location** — defaults to `~/.aidaide/plugins/`.
- **Widget Permissions** — per-widget allow/deny for shell, network, file system. See [Chapter 15](/docs/plugins).

## Experimental Features

A separate **File → Experimental Features…** dialog hosts beta toggles. Things flagged here are off by default and may change or disappear. Today's list includes early-access bits of the Hierarchy Builder (multi-port agents), expanded AI workflow primitives, and beta DB engines (SQLite, Cassandra).

## Debug Console (`Ctrl+Shift+D`)

Not in Settings but conceptually adjacent — open from **Preview → Debug → Debug Console**.

A live log of internal AidaIDE events: API calls, SSH commands, plugin loads, errors. Useful when filing a bug. Right-click → **Copy All** to grab the buffer for attaching to a bug report.

## Performance Monitor

**Preview → Debug → Performance Monitor**.

Real-time charts of CPU / memory / threads / file handles inside the AidaIDE process. Useful when something feels slow. The recent fix to the truncation issue is in main now; if you see numbers cut off again, file a bug.

## Keyboard Shortcuts editor

Reachable from **File → Keyboard Shortcuts…** (`Ctrl+K, Ctrl+S`) and detailed in [Chapter 14](/docs/shortcuts).

## Display settings

For multi-monitor setups: **File → Settings → Appearance → Display Settings…** opens a sub-panel for:

- DPI scaling per monitor.
- Default monitor for new windows.
- Per-monitor theme overrides (rare; useful for a dim secondary monitor).

## Terms & Setup

### Theme vs accent
A **theme** is the full palette (background, foreground, sidebar, accents). The **accent** is the single highlight colour overlaid on whatever theme is active. Override the accent without changing the theme.

### "I changed something and it broke"
Every section has **Reset this section to defaults** at the bottom. If the IDE will not start because of a setting, the file lives at `~/.aidaide/settings.json` — delete it (lose all settings) or open in a plain editor and hand-fix.

### Where settings persist
- `~/.aidaide/settings.json` — all settings above.
- `~/.aidaide/themes/` — custom theme files.
- `~/.aidaide/known_hosts` — accepted SSH host keys.
- `~/.aidaide/audit.log` — audit log.
- `~/.aidaide/logs/` — diagnostic logs (used by bug reports).

### "Settings dialog will not open"
Run from a terminal so you can see the traceback. Usually the cause is a corrupt theme file in `~/.aidaide/themes/`. Move it out and retry.

### "I want a smaller font everywhere"
- **Appearance → Font size (UI)** lowers menu, tabs, panels.
- **Editor → Editor font size** lowers code font.
- Both are independent.

### Multi-monitor + DPI
- Each monitor's DPI is detected on startup. If you plug in a monitor after launching, restart AidaIDE so it picks up the new geometry.
- Mixed-DPI setups sometimes draw fuzzy text on the lower-DPI monitor. The display panel has a "Force per-monitor DPI" toggle that re-renders cleanly at the cost of slightly slower window moves.


## Cloud Portal

Cloud Portal access (browser remote access via <https://aidaide.app>) is enabled in **Settings → Cloud Portal**. Toggle **Enable Cloud Access** on; AidaIDE generates a per-device certificate and starts an outbound WebSocket tunnel. No router port forwarding is required.

Full walkthrough — including guest passes, permission groups, and the in-browser Remote Desktop — lives in [Ch. 21 — Cloud Portal and Web Access](/docs/cloud-portal-docs).

---

# Shortcuts and Command Palette

Source: https://aidaide.app/docs/shortcuts

You can drive almost every feature in AidaIDE from the keyboard. This chapter covers the defaults, the Command Palette, the Feature Browser, and how to remap any binding.

## Command Palette (`Ctrl+Shift+P`)

The fastest path to anything in the IDE. Press `Ctrl+Shift+P`, start typing.

- Matches against menu items, feature tabs, settings, plugin commands.
- Fuzzy match — "scn host" finds "Network → Host Discovery."
- `Enter` runs the focused item. `Esc` closes.
- The palette shows the keyboard shortcut on the right for items that have one — useful for learning bindings.

## Feature Browser

**View → Feature Browser** or the toolbar magnifier.

A pane listing every feature tab grouped by category (Fleet, Network, Security, AI, etc.) with a search box. Better than the Command Palette when you do not yet know what something is called and want to browse.

Each entry has:

- Icon.
- Name.
- One-line description.
- "Open" button.
- License lock icon if gated.

## Default shortcuts (selected)

### Global
| Action | Shortcut |
| --- | --- |
| Command Palette | `Ctrl+Shift+P` |
| Settings | `Ctrl+,` |
| Keyboard Shortcuts editor | `Ctrl+K, Ctrl+S` |
| New Connection Tab | `Ctrl+T` |
| New Project from Template | `Ctrl+Shift+N` |
| Open File | `Ctrl+O` |
| Open Project Folder | `Ctrl+Shift+O` |
| Save | `Ctrl+S` |
| Add panel | `Ctrl+Shift+B` |
| Exit | `Alt+F4` (Win) / `Cmd+Q` (Mac) |

### Edit
| Action | Shortcut |
| --- | --- |
| Undo | `Ctrl+Z` |
| Redo | `Ctrl+Y` / `Ctrl+Shift+Z` |
| Find | `Ctrl+F` |
| Find Next | `F3` |
| Find Previous | `Shift+F3` |
| Replace | `Ctrl+H` |
| Find in Files | `Ctrl+Shift+F` |
| Go to Line | `Ctrl+G` |
| Toggle line comment | `Ctrl+/` |
| Indent / Outdent | `Tab` / `Shift+Tab` |

### AI
| Action | Shortcut |
| --- | --- |
| Toggle AI Sidebar | `Ctrl+Shift+I` |
| AI Chat | `Ctrl+Shift+A` |
| Claude Agent Manager | `Ctrl+Shift+M` |
| Agent Hierarchy Builder | `Ctrl+Shift+H` |
| Live Coding Agents | `Ctrl+Shift+J` |
| Save Chat Session | `Ctrl+Shift+Alt+S` |
| Load Chat Session | `Ctrl+Alt+L` |

### Tools / Plugins
| Action | Shortcut |
| --- | --- |
| Protocol Wizard | `Ctrl+Shift+W` |
| Marketplace Store | `Ctrl+Alt+M` |
| Plugin & Widget Manager | `Ctrl+Alt+P` |
| Create New Plugin/Widget | `Ctrl+Shift+K` |
| Debug Console | `Ctrl+Shift+D` |

### Editor
| Action | Shortcut |
| --- | --- |
| Run current file | `F5` |
| Toggle breakpoint | `F9` |
| Bookmark current line | `Ctrl+F2` |
| Jump to next bookmark | `F2` |
| Jump to previous bookmark | `Shift+F2` |

(Some `F5` paths in connection tab editors double-fire — known minor issue if you bind a second action to `F5`.)

### User Guide viewer (Help → User Guide)

These shortcuts only apply while the in-app User Guide window is focused. In the main window, `Ctrl+Shift+B` is Add panel (rc18), not this bookmarks picker. `Ctrl+Shift+A` is AI Chat.

| Action | Shortcut |
| --- | --- |
| Focus search box | `Ctrl+F` |
| Next match | `Enter` or `F3` |
| Previous match | `Shift+F3` |
| Clear search | `Esc` |
| Previous chapter | `Alt+◂` or `Ctrl+PgUp` |
| Next chapter | `Alt+▸` or `Ctrl+PgDn` |
| Font zoom in / out / reset | `Ctrl+=` / `Ctrl+-` / `Ctrl+0` |
| Bookmark current section | `Ctrl+B` |
| Open bookmarks picker | `Ctrl+Shift+B` |
| Toggle light/dark theme | `Ctrl+Shift+L` |
| Toggle Reader / focus mode | `F11` |
| Jump to Keyword Index | `Ctrl+I` |
| Copy current chapter to clipboard | `Ctrl+P` |
| Export current chapter as PDF | `Ctrl+Shift+E` |
| Export the whole guide as one PDF | `Ctrl+Shift+G` |

The PDF lands under `~/.aidaide/exports/<chapter>_<timestamp>.pdf` (or `docs/user_guide/_exports/` when running from source, or your system temp dir if neither is writable). If `reportlab` is missing the viewer falls back to writing the raw markdown alongside where the PDF would have gone.

`Ctrl+Shift+G` (📚 Full PDF) writes a single file `AidaIDE_User_Guide_<timestamp>.pdf` containing every chapter in TOC order. The first two pages are a title page and an auto-generated table of contents whose entries are clickable links to each chapter and major heading. Each chapter starts on a fresh page (page-break-before-H1). Cross-chapter links inside the prose — for example `[see Ch.2 §"I don't have an SSH server"](/docs/ssh-devices#i-do-not-have-an-ssh-server--setup-paths)` — resolve to in-PDF anchors, and `https://` URLs in chapter prose become clickable. The footer carries a global "Page N of M". Without `reportlab`, the fallback writes one concatenated `.md` file instead.

Chapters that include screenshots use Markdown's standard `![alt text](path/to/image.png)` syntax — the viewer renders these inline (via Pillow) up to a 720px width ceiling. Captions appear in dim italic below the image. PDF export embeds the same images at page width.

These bindings are hard-coded in the viewer (not user-rebindable from **File → Keyboard Shortcuts…**) — the viewer is a small Toplevel and intentionally keeps its bindings local. If you want different keys, the source is `ui/user_guide_viewer.py`.

## Customising shortcuts

**File → Keyboard Shortcuts…** (`Ctrl+K, Ctrl+S`) opens the shortcuts editor:

- Searchable list of every command in AidaIDE.
- Each row shows current binding, command ID, default binding, and a category.
- Click a row → press the new key combo → it is bound. `Esc` cancels.
- Conflicts highlight in red. The previous binding is unbound automatically when you confirm.

Saved bindings live in `~/.aidaide/keybindings.json` and persist across launches.

### Resetting
- Right-click a row → **Reset to Default**.
- Bottom of the dialog → **Reset All to Defaults** wipes the file.

### Importing / exporting
- Export — saves your binding file. Share with teammates for consistency.
- Import — overlays an imported file onto current bindings.

## Recurring binding traps

If a shortcut does not seem to do anything, check the following — these are known patterns:

- **Multiple bindings to the same command** — kbm-level and widget-level can both bind, and one returns None while the other handles. Re-bind through the editor; conflicts surface in red.
- **Binding declared but never wired** — a small set of `edit.*` / `selection.*` / `go.*` commands are declared in the default shortcuts file but not actually registered to handlers (about 41 are known). They show up as customisable but pressing the key does nothing. File a bug if you depend on one.
- **`Ctrl+Shift+H` confusion** — opens the Hierarchy Builder, but the default shortcut declaration calls it `edit.replaceInFiles` in some builds. The Settings UI label may lie until this is sorted. H

---

# Plugins, Widgets, Marketplace

Source: https://aidaide.app/docs/plugins

Plugins and widgets are how AidaIDE extends itself. A plugin can add menu items, feature tabs, LCOT command catalogues, theme files, chip libraries for the Hierarchy Builder, anything. Widgets are smaller, embedded UI components (a status badge, a chart, a quick-action button).

## Menu layout

Under **Tools → Plugins & Widgets**:

- **Marketplace Store** (`Ctrl+Alt+M`)
- **Plugin & Widget Manager** (`Ctrl+Alt+P`)
- **Create New Plugin/Widget** (`Ctrl+Shift+K`)
- **Widget Permissions**
- **Widget Health Dashboard**
- **Run Widget Tests**

## Marketplace Store

The hub for discovering and installing third-party (and Anthropic-published) plugins.

Layout:

- Top: featured, new, popular.
- Search box.
- Categories: Themes, Chip Libraries, Connectors, Workflows, Tools.
- Each plugin card shows name, author, version, install count, rating.

Click a card to see details: description, screenshots, permissions requested, dependencies, changelog.

**Install** downloads and unpacks into `~/.aidaide/plugins/<plugin-id>/`. Restart is usually required for menu/toolbar changes; widgets and themes typically take effect immediately.

## Plugin and Widget Manager

The installed-side companion to the Marketplace. Lists everything you have, whether enabled, version, and update availability.

Per-row controls:

- **Enable / Disable** — toggle without uninstalling. Disabled plugins still occupy disk space; they just do not load.
- **Update** — if a newer version is in the Marketplace.
- **Uninstall** — removes the plugin directory.
- **Open in Editor** — for plugin developers; jumps to the source.

## Creating a plugin or widget

`Ctrl+Shift+K` opens **Create New Plugin/Widget** — a scaffolder. Pick:

- **Plugin** or **Widget**.
- **Language** (Python is the default for AidaIDE plugins).
- **Template**:
  - Plugin: adds menu items, feature tabs, LCOT catalogue, theme.
  - Widget: status badge, chart, table, custom panel.

Fill in metadata (name, id, author), click **Generate**, and the scaffold lands in your projects folder. Editing it live and reloading via **Plugin Manager → Reload Plugin** lets you iterate without restarting the whole IDE.

Plugin SDK docs live in `~/.aidaide/plugins/_sdk/README.md` after install.

## Widget permissions

Widgets can request access to:

- **Network** — outbound HTTP. Required for anything fetching data.
- **Filesystem read** — your local files.
- **Filesystem write** — modifying files.
- **Shell** — running commands.
- **MCP** — calling registered MCP servers.

Each capability is granted explicitly the first time the widget asks for it. The grants are persisted per widget in `~/.aidaide/widget_permissions.json` and editable in **Widget Permissions**.

## Widget Health Dashboard

A status grid for installed widgets:

- Last load time.
- Last error (if any).
- Memory footprint.
- Per-widget action: Reload, Disable, Pin to toolbar.

Useful when something visually breaks. If a widget is causing the IDE to hang, **Disable** here unblocks the load path on next launch.

## Run Widget Tests

For plugin authors: runs the test harness against every installed widget. Reports pass/fail per widget with stack traces on failure.

## Workflows

### "I want a darker theme than the bundled ones"
1. **Marketplace Store** → search "theme."
2. Pick something dark.
3. Install.
4. **Settings → Appearance → Theme** → pick the new theme.

### "I built a chip library for the Hierarchy Builder"
1. Scaffold a plugin with template "Chip Library."
2. Develop locally.
3. Package with `aidaide-plugin pack` (CLI tool installed with the SDK).
4. Submit to the Marketplace (or share the `.plugin` file directly).
5. After install, **Hierarchy Builder → Refresh Library** picks up the new chips.

### "A plugin is making AidaIDE slow"
1. **Widget Health Dashboard** — sort by memory or load time.
2. If one widget is clearly bad, **Disable** it.
3. If you still feel sluggishness, **Plugin Manager** → Disable all third-party plugins, restart, re-enable one at a time.

## Terms & Setup

### Plugin vs widget
- **Plugin** — bigger, can add menus / tabs / catalogues / themes / chip libraries.
- **Widget** — smaller, lives inside a panel. A clock, a metric, a button.

### .plugin file
A zip with a manifest at the root. Easy to inspect and easy to ship. Drag a `.plugin` onto AidaIDE's main window to install.

### Trusted authors
Marketplace plugins from listed authors install without per-install confirmation. Anthropic-published is trusted by default. Add your own teammates in **Settings → Plugins → Trusted authors**.

### Permissions are real
A widget cannot read your filesystem, run shell, or hit the network unless you grant it. Treat permission prompts the way you would treat an iOS app asking for the camera — say no if the widget does not need the capability.

### "Install failed: signature invalid"
Marketplace plugins are signed; an invalid signature means the package was tampered with or the publisher's key rotated. Re-download.

### "I want to write a plugin but do not know where to start"
- `Ctrl+Shift+K` → Plugin → "Hello World" template.
- The generated `README.md` walks the API.
- AidaIDE source is open-source friendly — the bundled built-in plugins are good examples (look in the SDK README for paths).

### Updating plugins
Plugins do not auto-update. **Plugin Manager** shows a small icon next to anything with an update available. Click to update, then restart if asked.

### Removing all plugins
Quit AidaIDE. Delete or rename `~/.aidaide/plugins/`. Next launch starts with only the built-in features.

### "The marketplace is empty / will not load"
- Network — check **Settings → Network → HTTP proxy** if you are behind one.
- AidaIDE may have flipped the marketplace URL during an update; **Settings → Plugins → Marketplace URL** has the default.
- If you are running entirely offline, the marketplace is unreachable. Use `.plugin` files directly.

---

# Workspaces and Layouts

Source: https://aidaide.app/docs/workspaces

**Ships in the current Windows download, 1.0.0-rc19.** The Workbench has been in the desktop app since 1.0.0-rc18. Windows is the primary supported path. macOS and Linux builds are in progress. Linux experimental (soft peer). This chapter describes the Workbench in the desktop app. Android stays a separate Lite-class app, not a desktop host download. The Cloud Portal is unchanged.

AidaIDE's window is a workbench: every tab is a panel you can split, stack, or tear off into its own window, and your setups save by name. **View → Workbench → Use the workbench shell** is on by default. The Workbench is not a Pro feature. Pro tools stay Pro inside it. Existing tools open as they are. Plugins need no changes; the plugin API did not change for this.

## Split the view

Drag a tab to the left, right, top, or bottom edge of another panel. A compass shows where it will land. Drop it on that edge to split the view.

## Stack panels

Drop a tab on the middle of another panel to stack them.

## Tear off into a new window

Drag a tab outside the window, double-click it, or right-click and choose **Float**. Drop more tabs into that window and move it to a second monitor. Close the window and its tabs come back.

A connection tab, and that connection's Sidebar, Editor, and Intelligence panels, stay in the main window. The connection's Terminal can leave. See [Take the terminal anywhere](#take-the-terminal-anywhere).

## Add any panel

Open the list with `Ctrl+Shift+B`, the toolbar's **+ Panel**, or the `+` on any tab strip. One searchable list holds every built-in tab, installed marketplace widgets, the Dashboard, panel tools, and the pages of running plugins. They dock the same way as the built-in panels.

`Ctrl+Shift+A` is AI Chat, not Add panel.

A layout that names a widget you do not have installed opens without that widget and says so. AidaIDE does not install the missing widget for you. Running plugins reopen their own pages; a saved layout does not restore plugin pages.

## Pick up where you left off

The arrangement saves itself as you go: windows, splits, stacks, floating windows, and their positions. After a restart the arrangement comes back. SSH sessions do not reconnect by themselves. Connections start fresh.

The current arrangement autosaves to `~/.aidaide/workbench_layout.json`.

## Save named layouts

The toolbar **Workspace** list holds layouts you name yourself. **Save** writes the current arrangement. Right-click any strip for **Save layout as...** or **Open layout**. The same commands are under **View → Workbench** and **Settings → Workspace**.

Switching layouts keeps connections connected. Each layout is a file under `~/.aidaide/layouts/` that you can copy to another PC. Layouts are not in the Marketplace.

**Settings → Workspace** lists those layouts:

- **Open**
- **Save current as...**
- **Delete**

There is no bundled set of presets, and no Layout Wizard.

## Take the terminal anywhere

Press **Pop** in a connection's terminal header. The live shell becomes a panel you can dock anywhere, including another window, with its scrollback, the shell switcher, and the AI agent's bash attached. Close the panel and it returns to the tab.

The connection's live SSH session stays registered with the connection service, which hands the shell to wherever the Terminal panel is docked. That is why the terminal can leave the tab and keep running.

## Pop out Sidebar, Editor, and Intelligence

**Add panel → "Sidebar - user@host"** (Editor and Intelligence the same way). Their icon bars travel with them. These panels stay in the main window.

## Classic layout

**View → Workbench → Classic layout for this connection** lays out a toolbar row, then Sidebar, Editor, Intelligence, and Terminal below. They are panels you can move later. A second connection joins the same stacks.

**Classic layout on connect** is off by default.

## Go back to tabs

**View → Workbench**, then uncheck **Use the workbench shell**, and restart. You get the classic tabbed window. **Reset layout** clears the arrangement.

The per-tab Grid Layout mode, the Layout Wizard, Layout Presets, and the Widget Palette do not come back. Old grid layouts are not carried over. Save a named layout instead.

## Where layouts live

Layouts are plain files on your PC:

- Named layouts: `~/.aidaide/layouts/`
- Current arrangement: `~/.aidaide/workbench_layout.json`

Copy or back them up. On Windows the AidaIDE user-data directory is `%APPDATA%\AidaIDE\` (see [Chapter 20](/docs/quick-reference#file-and-directory-paths)).

---

# Updates, Licensing, Support

Source: https://aidaide.app/docs/licensing

The last chapter covers everything outside the main workflow loop: getting AidaIDE up to date, activating your plan, filing bugs, and finding help.

## Help menu

The bottom item on the menu bar.

- **Welcome Guide** — short overview tour.
- **Setup Wizard** — re-runs first-run flow ([Chapter 1](/docs/getting-started)).
- **Ask Macy (Interactive Guide)** — voice-narrated walkthrough of the IDE; also the entry point to the 16-section Hierarchy Builder tour.
- **About** — version, build number, OS, attribution.
- **Documentation** — opens this guide and the online docs at aidaide.app.
- **Check for Updates** — manual update check.
- **Enter License Key** — paste a key to activate.
- **License Status** — what plan you are on and how many seats/devices remain.
- **Bug Reports** — list of recent bug-report packages.
- **Report a Bug** — opens the bug-report dialog.

## Checking for updates

**Help → Check for Updates** queries the manifest at `updates.aidaide.app`. The response lists:

- Latest available version.
- Your current version.
- Release notes for everything in between.

If an update is available:

- **Download** — pulls the installer (or, in dev/portable installs, the patch bundle).
- **Install Later** — keeps you on the current version.
- **Install Now** — runs the installer and prompts to restart AidaIDE.

The installer bucket is `aidaide-downloads` on R2. If you ever see a 403 from `updates.aidaide.app`, that is normally R2 returning 403-instead-of-404 for a missing bucket name, not an auth problem — wait for the next manifest publish.

### Auto-update
**Settings → General → Auto-check for updates** controls whether AidaIDE checks on launch. Default is on (weekly cadence). Auto-install is off by default; you always confirm.

## Activating your license

AidaIDE runs without a license, but several features (AI sidebar, AI Hierarchy Builder, Live Coding Agents, Hierarchy Builder) are gated. To activate:

1. **Help → Enter License Key**.
2. Paste the key from your purchase email.
3. Click **Activate**.

The activation call goes to AidaIDE's licensing endpoint, which verifies the key and binds it to this machine. From now on AidaIDE checks the license locally on launch; periodic re-verification happens in the background.

### Device binding

Licenses are bound to a per-machine fingerprint.

The fingerprint is `SHA-256(MAC | hostname)`. Swapping out hardware changes it; AidaIDE will refuse to launch the second-most-recent device beyond your cap.

If you replace a machine, **Help → License Status → Devices** lists currently-bound devices. Right-click → **Revoke** to free a slot. Revoke takes effect within a few minutes (soft-revoke from admin UI).

### License Status

A small panel:

- Plan name.
- Seats used / max.
- Devices bound / cap.
- Renewal date.
- "Open Customer Portal" — link to manage billing.

## Buying a license

The pricing page lives at aidaide.app/pricing. Current tiers (July 2026):

- **Free** — $0 forever. Full IDE, SSH/SFTP engine, terminal, file browser, OTA. No license key.
- **Pro** — $19/month or $190/year. Full AI suite, Hierarchy Builder, advanced network scans, cameras.
- **Teams Pro** — $70/month or $700/year. 5 users.
- **Enterprise** — custom.

AidaIDE is free forever — Pro adds the AI suite whenever you want it.

## Filing a bug

**Help → Report a Bug** opens the bug-report dialog:

- **Summary** — one line.
- **Description** — what you were doing, what happened, what you expected.
- **Attach logs** — auto-included by default (`~/.aidaide/logs/` from the last hour).
- **Attach screenshots** — drag-and-drop into the dialog.
- **Include redacted vault contents** — off by default. Turn on if the bug is vault-related and the redactor will strip secrets.

Submitting bundles everything into a `.tar.gz` and uploads to AidaIDE's bug-collection endpoint. You get a ticket ID in return. Track at **Help → Bug Reports**.

If your machine is offline, the bug report saves to `~/.aidaide/bug_reports/` and uploads on the next successful launch.

## Logs

Three files / directories matter when debugging:

- `~/.aidaide/logs/aidaide.log` — main app log (rotates daily).
- `~/.aidaide/logs/ssh.log` — per-connection SSH transcripts.
- `~/.aidaide/audit.log` — security-relevant events (vault unlock, license activation, PKI events).

Logs are sized-capped; old rotations are compressed.

## Getting human help

- **AidaIDE community Discord** — link from **Help → Documentation**.
- **Email** — `support@aidaide.app`.
- **GitHub issues** — for open-source-tracked bugs.
- **Twitter/X** — `@aidaide` (community-tipped).

When reaching out, include your AidaIDE version (from **Help → About**), OS, and the bug ticket ID if you have one.

## Updating Marketplace plugins

Plugins update independently of core AidaIDE. **Tools → Plugins & Widgets → Plugin & Widget Manager** shows what is updatable. See [Chapter 15](/docs/plugins).

## Uninstalling

- **Windows** — Settings → Apps → AidaIDE → Uninstall.
- **macOS** — drag AidaIDE.app to the Trash.
- **Linux** — package manager (`apt remove aidaide` etc.) or remove the AppImage.

The uninstaller does **not** touch `~/.aidaide/` (your vault, settings, workspaces). Remove manually if you want a fresh start. **Back up the vault first if you have credentials you need.**

## Terms & Setup

### License key format
A long base64-ish string. Treat as a secret — anyone with your key can use your seats until you rotate.

### "I lost my license key"
Sign into the customer portal (linked from License Status) — your keys are listed there. Resend by email if needed.

### "My license stopped working"
- Verify the renewal date in License Status.
- Check that this machine is still in your bound-devices list.
- Network — license verification needs outbound HTTPS to AidaIDE's licensing endpoint. Behind a strict proxy? Configure under Settings → Network → HTTP proxy.

### "AidaIDE will not start after an update"
- Start with the `--safe-mode` flag (no plugins, default settings).
- If safe mode launches, the culprit is a plugin or a custom theme. Disable plugins, swap themes, retry.
- If safe mode also fails, file a bug from another machine and include `~/.aidaide/logs/aidaide.log`.

### "I want an air-gapped install"
- Run the installer on a network-connected machine first to validate.
- Disable auto-update.
- Pre-install required plugins via `.plugin` files.
- Vault and license activation both work offline if you can ship one verification round-trip during initial setup. After that, periodic re-verification only happens when network is available.

### EU/data-residency note
EU-jurisdiction R2 buckets are on the roadmap. Until they exist, downloads come from the global bucket which transits multiple regions. Talk to support if this matters for your compliance posture.

### Roadmap pointers (subject to change)
- Multi-port agents in the Hierarchy Builder.
- Scoped context per agent.
- Better Web Dashboard out-of-the-box experience.
- Per-window AI sidebar.
- EU-region installer mirror.

---

# Troubleshooting & FAQ

Source: https://aidaide.app/docs/troubleshooting

A symptom-first lookup. Each entry starts with what you actually see on screen (or what is missing), then explains what to try in order from cheapest to most invasive. If nothing in here works, the bottom of the chapter explains how to file a useful bug report.

Use `Ctrl+F` on this page to jump straight to your symptom. Entries are grouped by where the symptom shows up, not by the underlying subsystem.

## How to use this chapter

1. **Look up the symptom** in the table of contents or with `Ctrl+F`.
2. **Try the fixes in order.** Each list is sorted cheapest-first; if step 1 works, you do not need step 2.
3. **If still broken,** the relevant chapter has deeper context — every entry cross-links to it.
4. **If it looks like a bug,** jump to [Filing a useful bug report](#filing-a-useful-bug-report) at the bottom.

## Contents

- [Launch and login](#launch-and-login)
- [SSH and connections](#ssh-and-connections)
- [File browser, editor, save](#file-browser-editor-save)
- [LCOT panel](#lcot-panel)
- [Fleet Manager and OTA](#fleet-manager-and-ota)
- [Network tools](#network-tools)
- [Security tools](#security-tools)
- [AI Assistant and Hierarchy Builder](#ai-assistant-and-hierarchy-builder)
- [Cameras](#cameras)
- [Databases](#databases)
- [Settings, themes, layout](#settings-themes-layout)
- [Updates and licensing](#updates-and-licensing)
- [Performance](#performance)
- [Diagnostics you can run yourself](#diagnostics-you-can-run-yourself)
- [Filing a useful bug report](#filing-a-useful-bug-report)

---

## Launch and login

### AidaIDE will not launch at all

1. Launch from a terminal so you can see startup errors: `aidaide` on Linux/macOS, `"C:\Program Files\AidaIDE\aidaide.exe"` on Windows.
2. Try **safe mode**: `aidaide --safe-mode`. This skips plugins and uses default settings. If safe mode works, the culprit is a plugin or a custom theme — disable them one at a time.
3. If safe mode also fails, capture `~/.aidaide/logs/aidaide.log` and file a bug from another machine. See also [Ch. 17 §"AidaIDE will not start after an update"](/docs/licensing#aidaide-will-not-start-after-an-update).

### Login window appears but typing does nothing

The Smart Login window owns keyboard focus on launch. If it does not:

1. Click directly on the password field.
2. If you have a non-English keyboard layout and the field stays blank, swap input methods (Win+Space on Windows; some IMEs swallow the keystrokes).
3. As a last resort, close (X) and relaunch; the focus bug is timing-related.

### "Vault Locked" but I never set a master password

You did, on a previous install. The vault file at `%APPDATA%\AidaIDE\` (Windows) or `~/.aidaide/` (Linux/macOS) survives uninstalls. Either:

- Remember and enter the password, or
- Click **Forgot password? Reset vault** under the password field. **This wipes every saved secret.** See [Ch. 1 §Unlocking the vault](/docs/getting-started#unlocking-the-vault).

### Splash plays forever / window never appears

Background loading is stuck. Wait 30 seconds; if still hung:

1. Skip the splash next launch: set `AIDA_SPLASH=off` as an environment variable.
2. Kill the process and relaunch.
3. If it recurs, capture the log — startup tasks are time-stamped there.

### "Soft restart" — login skipped, did something change?

By design — see [Ch. 1 §Soft-restart bypass](/docs/getting-started#soft-restart-bypass). To force a password prompt next launch, **File → Exit** explicitly.

---

## SSH and connections

### "Connection refused" or "Connection timed out"

The single most common cause is a wrong port. AidaIDE has historically had a few callsites that hardcode port 22:

1. **Re-open the host in Connection Manager** and verify **Port** is set to your server's listening port.
2. Test from a real terminal: `ssh -p <port> user@host`. If that fails too, the problem is the server or network, not AidaIDE.
3. Check that the device is reachable: `ping host`.
4. If you can SSH from a terminal but AidaIDE cannot, file a bug and attach `~/.aidaide/logs/ssh.log` — that is the port-22 trap resurfacing. See [Ch. 2 §Ports and the port-22 trap](/docs/ssh-devices#ports-and-the-port-22-trap).

### "Host key has changed!"

Genuine security feature. Either:

- The server was reinstalled / rekeyed (benign — verify with the server admin, then click **Accept New Key**).
- Someone is intercepting your traffic (do not accept; contact whoever runs the server).

See [Ch. 2 §Host key](/docs/ssh-devices#host-key).

### "Permission denied (publickey)"

1. Connection Manager → host → **Authentication**. Is the right key file selected? It should point at the **private** key, not `.pub`.
2. On the server, verify `~/.ssh/authorized_keys` contains the matching **public** key.
3. Check permissions on the server: `chmod 700 ~/.ssh && chmod 600 ~/.ssh/authorized_keys`.
4. On Windows, the private key file itself must be readable only by your user — see [Ch. 2 §Key permissions errors](/docs/ssh-devices#key-permissions-errors).

### Save to a remote file appears to succeed but the file did not change

A legacy bug: silent fall-through from SFTP to local `open()`. Should be fixed.

1. Reopen the file from the remote tree (not from Recent Files) to confirm.
2. Check `~/.aidaide/logs/ssh.log` for an SFTP error around the save time.
3. If the local-file mirror is being edited, the tab title shows the local path; if it is the remote, the title is prefixed with the host name. See [Ch. 2 §Edit a remote file](/docs/ssh-devices#common-operations).

### A password field mysteriously goes blank

The vault decrypt step failed silently in the past. Should now surface as an error dialog.

1. Re-enter the password in Connection Manager and **Save**.
2. If the field blanks again on next launch, file a bug — that is a recurrence and we need the log.

### "I just changed my SSH port and now nothing connects"

1. Update the **Port** in every Connection Manager entry pointing at that host.
2. If you have devices in Fleet Manager, update `device.ssh_port` there too.
3. Restart any open connection tabs (they cache the port for the session).

### Drag-and-drop upload silently does nothing

1. Confirm the destination pane has focus (click into the remote tree first).
2. Check the status bar — uploads show a progress line there.
3. Look at `~/.aidaide/logs/ssh.log` — SFTP permission errors usually mean the remote user cannot write to the target directory.

---

## File browser, editor, save

### Editor will not show a file even though it opens

Check the file size; very large logs trigger AidaIDE's read cap. There is no unbounded read by design.

- Open with `tail -n 5000 logfile | nl` in the terminal pane instead.
- Or use **Find in Files** scoped to the directory.

See [Ch. 3 — File Browser and Editor](/docs/file-browser).

### Find in Files returns wrong file names

Older bug: result-click was stripping the directory and opening the wrong file. Re-test after updating; if it still happens, file a bug with the search term, the result list, and which file actually opened.

### Auto-save did nothing

**Settings → Editor → Behaviour → Auto-save** has three modes: Off, On Focus Change, On Idle (delay). If you expected to see changes on disk, check that the mode you expected is selected. See [Ch. 13 §Behaviour](/docs/settings-themes#behaviour).

### Ctrl+S re-prompts Save As… every time

You opened the file from **File → Recent Files** when its path was unknown (legacy bug). Work around by closing and reopening from the file tree. If it recurs on freshly opened files, that is a bug — capture the log.

### Split-pane editor: second pane has stale status bar / no lint

Known issue with the secondary editor pane in some builds. The primary pane is canonical for status. Most code-intel features (lint, format, autocomplete) are wired to the primary editor.

### Non-ASCII filename or content shows mojibake (`é` instead of `é`)

UTF-8 encoding mismatch on read or write. AidaIDE specifies UTF-8 explicitly in most paths; if you hit this in a specific tab, capture the file and file a bug — these are tracked and patched as found.

### "Recent Files" / "Recent Connections" do not survive a restart

Either the JSON file under `~/.aidaide/` is unwritable, or a save was interrupted. Delete `~/.aidaide/recent_files.json` (or the corresponding connections file) and start fresh. The vault and your saved hosts in Connection Manager are not affected.

---

## LCOT panel

### LCOT panel is missing

1. You are on a feature tab. LCOT only shows on connection tabs — see [Ch. 4 §Where it lives](/docs/lcot#where-it-lives).
2. **View → Toggle LCOT Panel** — turn it back on.
3. The splitter has been dragged to the right edge. Drag it back left.

### I clicked a WRITE command and nothing happened

Look at the terminal pane — output went there. A WRITE command may print nothing on success (e.g. `systemctl restart nginx`). See [Ch. 4 §"I clicked a WRITE command and nothing seems to have happened"](/docs/lcot#i-clicked-a-write-command-and-nothing-seems-to-have-happened).

### A command fails with "command not found"

The tool is not installed on the **remote** device. LCOT runs commands in the remote shell; install the missing tool there (`apt install nmap`, etc.). See [Ch. 4 §"A command is failing"](/docs/lcot#a-command-is-failing).

### My custom command disappeared

Custom commands live in `~/.aidaide/lcot_user_commands.json`. If it was deleted or corrupted, AidaIDE silently re-creates an empty one. If you have an older copy, drop it back in and reopen the panel.

### The WRITE confirmation popup is annoying

It is not configurable per command — by design. It exists because clicking next to "Status" and hitting "Reboot" by accident is exactly the failure mode it prevents.

---

## Fleet Manager and OTA

### A device shows as "Offline" but I can SSH to it

The Fleet status thread probes on its own schedule. Force a refresh: right-click the device → **Refresh Status**. If it still shows offline:

1. Confirm the saved port matches the device's actual SSH port.
2. Check `~/.aidaide/logs/aidaide.log` for `fleet.status` lines around the timestamp.
3. The Fleet status check defaults to port 22 in some legacy paths. Workaround: re-save the device in Fleet Manager from scratch.

See [Ch. 5 — Fleet Management](/docs/fleet).

### Deploy Lite says "Success" but the binary did not land

Older bug had Deploy Lite fall through to fabricated success messages when no real callback was wired (CLAUDE.md rule #4 violation, tracked). Confirm by checking the device's filesystem manually. If the bug is reproducible, capture the log — that is one of the recurring traps we want to know about.

### OTA Update Manager says "No updates available" but I know there is one

1. **Refresh** in the OTA Update Manager. The endpoint cache TTL is a few minutes.
2. Check that the manifest URL in **Settings → Network → OTA** points at `updates.aidaide.app`.
3. R2 returns HTTP 403 instead of 404 for a missing manifest — if you see a 403 in the log, the bucket name is wrong, not your auth.

### "Web Dashboard" link from Fleet menu doesn't open anything

Fall back to running it manually: `python web_server.py` from the AidaIDE repo root. Then browse to `http://localhost:5001/fleet`. Known limitation; an auto-launch fix is on the roadmap.

### Discover Devices uses `root` as the username

Legacy default. **Cancel** the discovery, edit the username, retry. The default has been corrected in newer builds.

---

## Network tools

### Port Scanner / Host Discovery returns hosts I have never seen

If results look fabricated (consistent vendor strings like `2.4.1`, `3.0.0`, `7.4.1`, `8.0.26` across unrelated hosts), the tab fell through to demo data. This is a known recurring trap (CLAUDE.md rule #4). File a bug and label demo output explicitly.

### Packet Capture shows no traffic

1. Are you running AidaIDE as a user with permission to capture? On Linux you usually need `sudo setcap cap_net_raw,cap_net_admin=eip $(which python3)` on the interpreter.
2. Pick the right interface in the dropdown (the default may be a loopback).
3. Some BPF filters block everything if mistyped — clear the filter and verify packets flow.

See [Ch. 6 — Network Tools](/docs/network-tools).

### Network Topology shows "Refreshed" but nothing changed

The `Refresh` button on the Topology tab only re-reads bookmarks in some builds; it does not re-discover the LAN. To do a real refresh, run a fresh **Host Discovery** sweep.

### "Cisco IOS" / "Cisco Network Analyzer" — which tab is correct?

The menu label, the tab title, and the underlying class name disagree in some places. They all refer to the same feature; trust the menu path you came in from.

### An exported HTML report contains my private data verbatim

For private deployments only. If you see un-escaped user-supplied strings in the report (e.g. a packet payload rendered as raw HTML), do not share that file — it is an XSS vector and the underlying bug is being tracked. Stick to JSON exports until the next patch.

---

## Security tools

### PEM contents under "View Certificate" look fake

You are seeing a known fabrication bug — the PEM tab generated a SHA-512 placeholder. Real cert inspection should use `openssl x509 -in cert.pem -text -noout` until the next patch lands. See [Ch. 7 — Security Tools](/docs/security-tools).

### Cert/Vuln scans return zero findings

1. Confirm the scope (a folder, a host, the whole project). The scan honours what is selected.
2. Several Security tabs ship with **simulated data** unless real scanners are configured. The tab heading shows "Simulation" when this is the case. To run against real CVE feeds, configure a feed under **Threat Intel Feeds** first.
3. Some tabs have right-click context menus that pop on empty rows — that is a UX bug, not a missing tool.

### An exported security report has raw `<script>` in a field

HTML escape on user-supplied values is enforced in newer builds. If you see it, do not share the report and file a bug with the input that triggered it (CLAUDE.md rule #3 — recurring trap).

### Some tabs have right-click menus, others don't

Inconsistency across Security tabs. PKI Manager, IOC Database, Certificate Inventory have menus that pop on empty area (cosmetic bug). IP Access Control has no right-click at all (missing). Workaround: use the tab toolbar buttons instead.

---

## AI Assistant and Hierarchy Builder

### AI sidebar / chat takes forever to respond

1. Check the network indicator in the sidebar — slow first-byte usually means provider latency.
2. **Claude Agent Manager → Test Connection** — verifies the key and reachability.
3. Try a smaller model: Haiku is the speed-tier; switch in the Agent Manager.
4. Uncheck **Include workspace context** if your project is large.

See [Ch. 8 §"AI Sidebar takes forever to respond"](/docs/ai-assistant#ai-sidebar-takes-forever-to-respond).

### "Invalid API key"

1. Re-paste the key — trailing whitespace from copy/paste is the most common cause.
2. Try **Test Connection**; the error message is more specific.
3. Confirm the key is for the right provider (Anthropic keys do not work with OpenAI's endpoint).
4. If you store via env var (`ANTHROPIC_API_KEY`), the vault overrides it — clear the vault field or set Provider → "Use environment variable".

### Inline suggestions appear in unrelated files

Disable on file types where it does not help: **Settings → AI → Inline Suggestions → Disabled file types** → add `*.html`, `*.md`, etc. See [Ch. 8 §"Inline suggestions are wrong"](/docs/ai-assistant#inline-suggestions-are-wrong).

### Hierarchy Builder canvas is blank after I open a SoC

1. **View → Reset Zoom** — you may have zoomed past the canvas bounds.
2. Drill back out with the breadcrumb at the top of the canvas — you may have drilled into an empty IC.
3. Check the autosave: `~/.aidaide/builder_drafts/`. If the draft file is empty, the canvas truly is empty (start placing chips from the library).

### "Run" in Hierarchy Builder does not produce output

1. Confirm the SoC has a wired path from SoC In → some module → SoC Out. Loose modules with no input or output are silently skipped by the runtime.
2. Open the Trace panel (toolbar) — every signal that fires is logged there. Empty trace = nothing fired = wiring problem.
3. Make sure every Agent module has a model selected in its Properties panel; un-set models fail silently in some builds.

See [Ch. 9 — Hierarchy Builder](/docs/hierarchy-builder).

### Live Coding Agents burns through tokens

It is supposed to — that is the "watching over your shoulder" model. Use it for focused 1–2 hour sessions, not all day. To slow it down:

- **AI → Live Coding Agents → Settings → Suggestion frequency** → lower it.
- Pin instructions ("only act on auth.py") to narrow scope.
- Close the tab when you walk away.

### Ghost text appears in the wrong place

There is a known off-by-one on the first click of **Toggle Ghost Text**. Click it twice to settle.

---

## Cameras

### Camera grid is laggy or drops frames

1. Confirm network path — wifi cameras at the edge of range will drop frames regardless.
2. **Settings → Network → Cameras → Default Substream** = `low`.
3. Reduce framerate per camera (10 fps is fine for monitoring).
4. Close the grid tab when you are not actively watching — decoder threads suspend.

See [Ch. 10 §"The camera grid is laggy or stuttering"](/docs/cameras#the-camera-grid-is-laggy-or-stuttering).

### RTSP feed will not connect

1. Test the URL in VLC first (`Media → Open Network Stream`). If VLC fails too, it is the camera.
2. Try alternate sub-paths: `stream1`, `stream2`, `Streaming/Channels/101`, `cam/realmonitor`.
3. Embed credentials in the URL or use Camera Manager's username/password fields.

### Scan for Cameras finds nothing on a LAN with known cameras

Some cameras require authentication before they respond to WS-Discovery. Add the camera manually in Camera Manager with credentials, then re-scan — it should now be picked up.

---

## Databases

### "Connection refused" to MySQL/Postgres

1. Confirm the server is actually listening (`netstat -tnlp | grep 3306` for MySQL, 5432 for Postgres).
2. Check the bind address — many distros default to `127.0.0.1`. Edit `bind-address` in `my.cnf` or `listen_addresses` in `postgresql.conf` to allow LAN connections.
3. Firewall: open the relevant port.

See [Ch. 11 — Databases](/docs/databases).

### "Query is taking forever"

1. Cancel with the **Stop** button (returns to the editor).
2. Check `EXPLAIN` on the query — missing index is the usual cause.
3. The Query Editor has a per-query timeout under **Settings → Database → Query timeout**. Raise it temporarily for slow analytical queries.

### WRITE confirmations are blocking my workflow

INSERT/UPDATE/DELETE always confirm before running. There is no global "trust me, do not ask" because the prior failure mode (deleted production by accident) was worse than the friction. Tick **Remember for this connection** to skip the prompt for the rest of the session.

---

## Settings, themes, layout

### Theme change does not apply

1. Some panels render with cached colours until they redraw. Switch tabs and back, or `View → Reload UI`.
2. If a plugin shipped a hard-coded colour, only the plugin author can fix it. File a plugin bug.

### Settings → Accessibility (Font Scale / High Contrast / Focus Indicators) does nothing

Known issue: these toggles wire through the main window but the editor tabs do not always pick them up. Workaround: change the font scale in **Settings → Editor → Font size** directly.

See [Ch. 13 — Settings, Themes](/docs/settings-themes).

### Layout did not restore after restart

From rc18 the workbench arrangement saves itself as you go: windows, splits, stacks, floating windows, and their positions. It comes back after a restart. SSH sessions do not reconnect by themselves.

A named layout that refers to a widget you do not have installed opens without that widget and says so. Old grid layouts are not read. See [Ch. 16 §Pick up where you left off](/docs/workspaces#pick-up-where-you-left-off).

### A panel is missing after restart

The arrangement of panels comes back. Running plugins reopen their own pages; a saved layout does not restore plugin pages. Re-open a missing tool from **Add panel** (`Ctrl+Shift+B`). See [Ch. 16 §Add any panel](/docs/workspaces#add-any-panel).

### Command Palette does not find what I expect

1. Try shorter or different words — the matcher is fuzzy but biased toward initials.
2. Some commands are declared in the shortcut registry but not bound (legacy mass-declare cleanup pending). Use the **Feature Browser** (toolbar magnifier) as a fallback.

---

## Updates and licensing

### License will not activate

1. Verify network: license verification needs outbound HTTPS to AidaIDE's licensing endpoint. If you are behind a strict proxy, set **Settings → Network → HTTP proxy**.
2. Confirm the key matches the plan you bought (legacy base keys do not unlock the Hierarchy Builder; Pro keys do).
3. Check the renewal date in the customer portal (linked from **License Status**).

See [Ch. 17 §"My license stopped working"](/docs/licensing#my-license-stopped-working).

### "You have exceeded your device cap"

1. **Help → License Status → Devices** — review currently bound machines.
2. Right-click → **Revoke** the one you no longer use. Takes effect within a few minutes.
3. If you cannot revoke (the old machine is gone), email support with your key — they can free a slot manually.

### Update check returns 403

R2 returns 403 instead of 404 for missing buckets. Wait an hour and retry — the manifest is occasionally republished mid-day. If 403 persists past 24 hours, file a bug.

### I bought a license but AidaIDE still says unlicensed

1. **Help → Enter License Key** — paste it again.
2. Some email clients break long keys at the wrap point. Open the email in plaintext mode or copy directly from the customer portal.

---

## Performance

### AidaIDE is using a lot of memory

The biggest contributors, ranked:

1. **Camera grids** — one decoder thread per visible feed. Close the tab when not watching.
2. **Packet Capture** with a large in-memory buffer. Lower the buffer under **Settings → Network → Capture buffer**.
3. **Live Coding Agents** keeps a long context. Close the tab to release it.
4. **A connection tab with megabytes of terminal scrollback.** Right-click the terminal → **Clear scrollback**.
5. **Plugins.** Disable them one at a time to identify a leaker.

The Performance Monitor at **Settings → Performance → Open Performance Monitor** shows per-subsystem RSS in real time. See [Ch. 13 §Performance Monitor](/docs/settings-themes#performance-monitor).

### AidaIDE is using a lot of CPU when idle

1. Inline AI suggestions — disable if you are not actively coding.
2. A scan/probe tab left running — check the Network and Fleet menus for active background tasks.
3. Live Coding Agents in idle.

### The UI freezes for a few seconds at a time

Most often a slow off-thread Tk read or a synchronous SFTP probe. The Debug Console (`Ctrl+Shift+D`) shows blocked-main-thread warnings — capture them and file a bug.

---

## Diagnostics you can run yourself

These help us help you faster — please include their output when filing a bug.

### Capture the latest logs

```
~/.aidaide/logs/aidaide.log       — main app log
~/.aidaide/logs/ssh.log           — per-connection SSH transcripts
~/.aidaide/audit.log              — vault unlock, license events, PKI
```

On Windows substitute `%USERPROFILE%\.aidaide\logs\`.

### Run the bug-report bundler

**Help → Report a Bug** auto-collects the last hour of logs, your config (with secrets redacted), and your AidaIDE version. See [Ch. 17 §Filing a bug](/docs/licensing#filing-a-bug). This is the preferred path.

### Run AidaIDE in verbose mode

`aidaide --log-level=DEBUG` on Linux/macOS, equivalent shortcut on Windows. Re-creates the symptom and writes a much fuller log.

### Run in safe mode

`aidaide --safe-mode` disables plugins and uses default settings. If a bug disappears in safe mode, the cause is a plugin or a custom theme.

### Show the Debug Console

`Ctrl+Shift+D`. Real-time event stream. Useful for "this just happened, what did the IDE think happened?"

### Probe a connection from outside AidaIDE

```
ssh -vv -p <port> user@host           # full SSH handshake trace
nc -zv host port                      # tcp reachability
ping host                             # network reachability
```

If any of these fail, the problem is not AidaIDE.

### Verify the vault

The vault file is `vault.enc` under `%APPDATA%\AidaIDE\` (Windows) or `~/.aidaide/` (Linux/macOS). If it has gone to zero bytes, restore from your backup — without a backup, the only recovery is **Forgot password? Reset vault** on the login screen.

Back up the vault file periodically. Copying it to another machine + restoring is fully supported (your master password is portable).

---

## Filing a useful bug report

Run **Help → Report a Bug**. The dialog already collects most of what we need; please add:

1. **What you were trying to do.** One sentence is fine.
2. **Exactly what you clicked / typed.** "Opened Fleet → Discover Devices → Start" is enough.
3. **What you expected vs. what happened.**
4. **Whether it is reproducible.** Always, sometimes, once?
5. **Your environment.** AidaIDE version (Help → About), OS, network constraints (corporate proxy?).
6. **Logs.** Attached automatically. If the symptom is older than an hour, grab the rotated logs from `~/.aidaide/logs/` manually.
7. **A screenshot** if the bug is visual. Drag-and-drop into the dialog.

Submitting returns a ticket ID. Track in **Help → Bug Reports**. If your machine is offline, the report saves under `~/.aidaide/bug_reports/` and uploads on the next successful launch.

### What you do *not* need to include

- Your master password. Ever.
- Your raw vault file. The bundler redacts vault contents automatically when you tick **Include redacted vault contents**.
- Source code from your project unless directly relevant. Reference the file path instead.

## Terms & Setup

### Safe mode
`aidaide --safe-mode` launches with no plugins, default theme, and default settings. Used to isolate whether a bug is in core or in third-party code.

### Verbose / debug log mode
`aidaide --log-level=DEBUG` writes far more detail to `~/.aidaide/logs/aidaide.log`. Use for one reproduction, then revert (the log gets large).

### "Demo mode" vs real data
Several scanner-style tabs (Host Discovery, Service Detection, Threat Intel) ship with simulated data when no real backend is configured. Newer builds label this in the tab header; older builds may not. If a result list looks too clean to be true (consistent vendor versions, evenly distributed times), it probably is demo data.

### Bug report bundle
The `.tar.gz` produced by **Help → Report a Bug**. Contains your last hour of logs, your config (redacted), your AidaIDE version, and any screenshots you attached. Uploaded to AidaIDE's bug-collection endpoint. Tracked under your account if you have a license.

### `~/.aidaide/`
The AidaIDE user-data directory. On Windows it is `%APPDATA%\AidaIDE\`. Contains the vault, workspaces, Hierarchy Builder drafts, LCOT user commands, logs, bug reports. Not touched by the uninstaller. Back up before reinstalling if you want to preserve state.

### Recurring trap
Engineering shorthand for a class of bug that has shipped more than once. Common ones called out in this guide: hardcoded port 22, fabricated demo data presented as real, UTF-8 mismatch on read/write, HTML-escape miss on exports, silent SFTP-to-local fallback on save. If you suspect a recurring trap, say so in the bug report — we will check the relevant tracker.


## Composer (web vs desktop) parity

The Web Hierarchy Composer is a strict subset of the desktop builder at the moment. If a feature works in the desktop builder but the web composer is missing it, the most likely candidate is one of these (as of 2026-05-29):

- **Animated signal trace** — desktop only. The web composer can `Validate` and `Run` a hierarchy but does not animate the flow on the canvas.
- **Right-click context menu** — the web canvas supports a subset of the desktop right-click options.
- **Macy tour overlay** — the 16-section interactive walkthrough is desktop-only.
- **Per-IC keyboard shortcuts** — global canvas shortcuts work; some per-IC shortcuts are still desktop-only.

Work in progress in scheduled task `ai-hierarchy-builder-gui-parity`. If you find a parity gap not listed here, file a bug from the Help menu (Ch. 17 §Bug reports).

## Cloud Portal — tunnel down

If a device shows offline at <https://aidaide.app/web/devices> when AidaIDE is running:

1. **Settings → Cloud Portal** on the device. Is the **Tunnel up** badge green?
2. If red, click **Reconnect**. Watch the status line for an error.
3. Most common cause: outbound TCP 443 is blocked by a firewall to `aidaide.app`. Allow the host.
4. Stale cert: **Settings → Cloud Portal → Rotate device certificate**, then **Reconnect**.
5. Check **Help → Open log directory** for `cloud_portal.log` — connection failures get a single line with the underlying socket error.

## Cloud Portal — RD PIN issues

The 6-digit Remote Desktop PIN is shown on the host's desktop the first time a browser opens Remote Desktop. If it never appears:

- Confirm the host is currently logged in (the PIN dialog is a Tk popup; it needs an active session).
- Confirm the requesting user has at least Collaborator permission on the device.
- The PIN expires after 60 seconds — retry from the browser to trigger a new one.
- If you have lost network at the host, the PIN dialog will not refresh; restart the **Settings → Cloud Portal** toggle once connectivity returns.

## Guest pass claim fails

When clicking a Guest Pass URL takes you to an error page:

- **Not found** — the URL is mistyped or the pass was issued against a different account.
- **Expired** — the duration has elapsed. Ask the owner to issue a new one.
- **Revoked** — the owner revoked it manually. Ask for a new one.
- **Already claimed** — guest passes are single-use. Ask for a new one.


## Touch / mobile RD glitches

If the Remote Desktop tab behaves weirdly on a phone or tablet:

- **No mode-switch pill** — the page may have failed to load `touch_modes.js`. Hard-refresh (`Ctrl+Shift+R` on desktop; pull-to-refresh on mobile). On corporate networks check whether `web/static/js/touch_modes.js` is being blocked.
- **Stray right-clicks while scrolling** — long-press timer fires when a slow drag stalls for 500ms. Switch to **Scroll** mode while scrolling long content.
- **The mobile shortcut bar will not dismiss** — three-finger tap toggles it; if your phone has a gesture conflict, swipe up from the bottom of the bar instead.
- **The wrong characters appear when typing on QWERTZ/AZERTY** — confirm the **layout** chooser in the RD toolbar matches the host's keyboard config, not your physical keys. See [Ch. 22 §International keyboard layouts](/docs/input-devices#international-keyboard-layouts).
- **Pinch zoom does not affect the host** — by design. Pinch is client-side only; the host has no idea you pinched.

---

# Glossary

Source: https://aidaide.app/docs/glossary

A consolidated alphabetical lookup of every term defined in the user guide. Each entry gives a short plain-language definition and links to the chapter that explains it in context. If you want to look up the UI element by name instead of the concept, use the [Keyword Index](/docs/keyword-index) — it covers menu items, button labels, and tab names too.

Conventions:

- A term in **bold** is the canonical name used in the UI.
- *Italic* cross-references point at related glossary entries.
- "→ Ch. N" links to the chapter that goes deeper.

---

## A

**aida-lite** — The lightweight agent on a fleet device. It reports health and applies OTA updates. Fleet OTA updates for connected devices are included. → [Ch. 5 §aida-lite](/docs/fleet#aida-lite)

**Agent** — A named profile in *Claude Agent Manager*: model + system prompt + (optional) tool list. The atomic unit used by the AI sidebar, AI Workflows, and the Hierarchy Builder. → [Ch. 8 §Agent vs persona vs workflow](/docs/ai-assistant#agent-vs-persona-vs-workflow)

**Air-gapped install** — Running AidaIDE on a machine with no internet. Supported; requires offline license activation, disabled auto-update, and pre-installed `.plugin` files. → [Ch. 17 §"I want an air-gapped install"](/docs/licensing#i-want-an-air-gapped-install)

**Animation toggle** — Setting that disables UI motion (splash, drawer slides, hover transitions) for accessibility or low-end hardware. → [Ch. 13 §Animations](/docs/settings-themes#animations)

**Ansible / Ansible Runner** — Configuration-management tool. AidaIDE wraps `ansible-playbook` with a UI for inventory selection, playbook picking, and live output. → [Ch. 12 §Ansible](/docs/sysadmin#ansible)

**API key** — A long random string identifying you to an AI provider (Anthropic, OpenAI, Azure). Stored in the *vault*. Never transmitted to AidaIDE servers. → [Ch. 8 §API key](/docs/ai-assistant#api-key)

**Audit log** — Append-only log of security-relevant events: vault unlock, license activation, PKI cert operations. Lives at `~/.aidaide/audit.log`. → [Ch. 7 §Where the audit log lives](/docs/security-tools#where-the-audit-log-lives) | [Ch. 13 §Security](/docs/settings-themes#security)

**Auto-save (editor)** — Settings option to write the active file to disk on focus change or after an idle delay. Off by default. → [Ch. 13 §Behaviour](/docs/settings-themes#behaviour)

**Auto-save (arrangement)** — From rc18 the workbench saves windows, splits, stacks, and floating windows as you go. The arrangement comes back after a restart. SSH sessions do not reconnect by themselves. → [Ch. 16 §Pick up where you left off](/docs/workspaces#pick-up-where-you-left-off)

**Auto-update** — Setting under General that controls whether AidaIDE polls `updates.aidaide.app` on launch. Auto-install is always opt-in even when auto-check is on. → [Ch. 17 §Auto-update](/docs/licensing#auto-update)

**AidaVirtualCursor** — The on-screen crosshair shown in Trackpad touch mode; rendered as a DOM overlay so it stays smooth without round-tripping to the host. → [Ch. 22 §Trackpad mode](/docs/input-devices#trackpad-mode-and-the-virtual-cursor)

**AZERTY** — The French keyboard layout (A/Q and Z/W swapped; digits require Shift). Layout ID `fr`. → [Ch. 22 §International keyboard layouts](/docs/input-devices#international-keyboard-layouts)

## B

**Backup Manager** — Sysadmin tab that schedules backups (file-based, snapshot, rsync) across fleet devices. → [Ch. 12 §Backup Manager](/docs/sysadmin#backup--disaster-recovery)

**BPF filter** — Berkeley Packet Filter syntax. The expression you give Packet Capture to limit what gets captured. Example: `tcp port 80`. → [Ch. 6 §BPF filter](/docs/network-tools#bpf-filter)

**Breadcrumb (Hierarchy Builder)** — Path display at the top of the canvas showing the current SoC / IC stack as you drill in and out. → [Ch. 9 §Mental model](/docs/hierarchy-builder#mental-model)

**Bug Reports / Report a Bug** — The bundler under Help that captures recent logs, your config (secrets redacted), and screenshots into a `.tar.gz` and uploads it. → [Ch. 17 §Filing a bug](/docs/licensing#filing-a-bug) | [Ch. 18 §Filing a useful bug report](/docs/troubleshooting#filing-a-useful-bug-report)

## C

**CA (Certificate Authority)** — The entity (real or self-hosted) that signs TLS certificates. AidaIDE's PKI Manager can act as a small internal CA. → [Ch. 7 §CA, Root CA, Intermediate](/docs/security-tools#ca-root-ca-intermediate)

**Camera Feed Grid** — Auto-populated wall of every camera in Camera Manager. Good for at-a-glance "are they all alive?" → [Ch. 10 §Feed Grid vs Grid Viewer](/docs/cameras#feed-grid-vs-grid-viewer)

**Camera Grid Viewer** — Manually arranged camera wall — you pick which cameras go where and AidaIDE remembers the layout. → [Ch. 10 §Feed Grid vs Grid Viewer](/docs/cameras#feed-grid-vs-grid-viewer)

**Camera Manager** — Registry of all known cameras: name, IP, type (ONVIF/RTSP/HTTP MJPEG/USB), credentials. → [Ch. 10 §Camera Manager](/docs/cameras#camera-manager)

**Chain of Thought (LCOT)** — Original framing for the LCOT panel: a curated list of vetted commands the AI could suggest as reasoning steps. Today, more of a button-driven cheat sheet for humans too. → [Ch. 4 §Why "Chain of Thought"?](/docs/lcot#why-chain-of-thought)

**CIDR notation** — `192.168.1.0/24` form for IP ranges. Used in scanner scopes. → [Ch. 6 §CIDR notation](/docs/network-tools#cidr-notation)

**CIS benchmark** — Center for Internet Security hardening checklists. Compliance Assessment scans against CIS Level 1 / Level 2 profiles. → [Ch. 7 §Compliance Assessment](/docs/security-tools#compliance-assessment)

**Classic layout** — **View → Workbench → Classic layout for this connection**: toolbar row, then Sidebar, Editor, Intelligence, and Terminal, as panels you can move. The old Classic Tabs vs Grid setting is retired. → [Ch. 16 §Classic layout](/docs/workspaces#classic-layout)

**Claude Agent Manager** — The control panel for AI providers, API keys, model choice, and named agent presets. The ★ green toolbar button. → [Ch. 8 §Claude Agent Manager](/docs/ai-assistant#claude-agent-manager-ctrlshiftm)

**Command ID** — Stable string identifier for an action that can be bound to a shortcut. Used in the keyboard shortcut import/export format. Example: `edit.findInFiles`. → [Ch. 14 §Command ID](/docs/shortcuts#command-id)

**Command Palette** — `Ctrl+Shift+P`. Type a few letters of anything (menu items, tabs, settings) and it jumps you there. The fastest navigation method in AidaIDE. → [Ch. 14 §Command Palette](/docs/shortcuts#command-palette-ctrlshiftp)

**Compliance Assessment** — Security tab that runs CIS / NIST checks against the local box or connected hosts and produces a pass/fail report. → [Ch. 7 §Compliance Assessment](/docs/security-tools#compliance-assessment)

**Config Drift Detection** — Sysadmin feature that compares a host's current config to a baseline and flags differences. → [Ch. 12 §Configuration management](/docs/sysadmin#configuration-management)

**Connection Manager** — The central registry of every SSH host AidaIDE knows about. Lives under File → Connection Manager (or the ≡ toolbar button). → [Ch. 2 §Connection Manager](/docs/ssh-devices#connection-manager)

**Connection tab** — A per-host workspace inside the notebook: terminal + file browser + editor + LCOT panel. Pinned to the left of the notebook. → [Ch. 1 §Connection tab vs feature tab](/docs/getting-started#connection-tab-vs-feature-tab) | [Ch. 2 §Anatomy of a connection tab](/docs/ssh-devices#anatomy-of-a-connection-tab)

**Container / Image** — Docker terms. An **image** is a packaged filesystem + metadata; a **container** is a running instance of an image. → [Ch. 12 §Container vs image](/docs/sysadmin#container-vs-image)

**CVE (Common Vulnerabilities and Exposures)** — A public identifier for a security vulnerability. CVE Scanner cross-references software inventories against the NVD feed. → [Ch. 7 §CVE](/docs/security-tools#cve)

**CVSS (Common Vulnerability Scoring System)** — 0-10 score quantifying a CVE's severity. AidaIDE shows the score next to every finding. → [Ch. 7 §CVSS](/docs/security-tools#cvss)

**Cloud Portal** — Hosted service at <https://aidaide.app> that proxies authenticated browser sessions through a secure WebSocket tunnel to your local AidaIDE. No router port forwarding. → [Ch. 21 — Cloud Portal](/docs/cloud-portal-docs)

**Composer (Web)** — The browser version of the AI Hierarchy Builder. Same modes + persistence as the desktop builder; some advanced features are still desktop-only. → [Ch. 21 §Web Hierarchy Composer](/docs/cloud-portal-docs#web-hierarchy-composer)

## D

**Debug Console** — `Ctrl+Shift+D`. Live event stream useful for "this just happened — what did the IDE think happened?" → [Ch. 13 §Debug Console](/docs/settings-themes#debug-console-ctrlshiftd)

**Demo mode / simulation** — Several scanner-style tabs ship with fabricated data when no real backend is configured. Newer builds label this in the tab header; older builds may not. → [Ch. 18 §"Demo mode" vs real data](/docs/troubleshooting#demo-mode-vs-real-data)

**Deploy Lite** — Lightweight push of a binary / script / config to a fleet member. The ⚡ orange toolbar button. → [Ch. 5 §Deploy Lite](/docs/fleet#deploy-lite)

**Device binding** — License mechanism that ties an activation to one machine via a `SHA-256(MAC | hostname)` fingerprint. → [Ch. 17 §Device binding](/docs/licensing#device-binding)

**Device Dashboard** — Per-device live view: uptime, CPU/MEM, disk, network, running services. → [Ch. 5 §Device Dashboard](/docs/fleet#device-dashboard)

**Device Setup Wizard** — First-run hardware-focused wizard (Pi, ESP32, Arduino, generic Linux). Re-run from **Help → Setup Wizard**. → [Ch. 1 §Device Setup Wizard](/docs/getting-started#first-run-wizards)

**Diff Viewer** — Side-by-side diff for any two file versions. Available from Git submenu and from the editor for any unsaved changes. → [Ch. 3 §Diff Viewer](/docs/file-browser#diff-viewer)

**Discover Devices** — Fleet wizard that probes the LAN (mDNS / ARP / SSH banner) for new candidate fleet members. → [Ch. 5 §Discover Devices](/docs/fleet#discover-devices)

**Docker Compose** — Multi-container Docker definition format. The Docker Manager tab has a Compose section that lists and starts/stops compose stacks. → [Ch. 12 §Docker Compose](/docs/sysadmin#docker-compose)

**Docker Manager** — Containers tab for listing/starting/stopping/pruning Docker resources on a host. → [Ch. 12 §Docker Manager](/docs/sysadmin#containers)

**DSC (Desired State Configuration)** — Microsoft's configuration-management framework. AidaIDE wraps PowerShell DSC for Windows fleet members. → [Ch. 12 §DSC](/docs/sysadmin#dsc-desired-state-configuration)

## E

**Encoding (UTF-8)** — All AidaIDE file IO is UTF-8 by default — both reads and writes. Don't open a UTF-8 file as cp1252 elsewhere or you'll get mojibake. → [Ch. 3 §Encoding (UTF-8)](/docs/file-browser#encoding-utf-8)

**Experimental Features** — File-menu submenu listing features that are stable enough to expose but explicitly labelled "things may change." Per-feature opt-in. → [Ch. 13 §Experimental Features](/docs/settings-themes#experimental-features)

## F

**Feature Browser** — Searchable list of every feature tab, grouped by category. The fastest way to find a tool when you forget which menu it lives under. Open from the toolbar magnifier. → [Ch. 1 §Feature Browser](/docs/getting-started#feature-browser)

**Feature tab** — A tab inside the notebook that is not bound to a single SSH host: Fleet Manager, Security Scanner, Database Manager, Hierarchy Builder, etc. Pinned to the right of the notebook. → [Ch. 1 §Connection tab vs feature tab](/docs/getting-started#connection-tab-vs-feature-tab)

**Filter / Splitter / Joiner / Map / Reduce** — Data-flow modules in the Hierarchy Builder library. → [Ch. 9 §Component library](/docs/hierarchy-builder#component-library)

**Fleet Manager** — The central tab for managing many devices at once: inventory, groups, bulk actions, status, deployment. → [Ch. 5 §Fleet Manager](/docs/fleet#fleet-manager)

**Fleet vs Connection Manager** — Fleet is for managing *many* devices in aggregate (push, monitor, group). Connection Manager is for *one* SSH session at a time. → [Ch. 5 §Fleet vs Connection Manager](/docs/fleet#fleet-vs-connection-manager)

## G

**Ghost text** — The greyed-out inline AI suggestion that appears after your cursor. Press `Tab` to accept, `Esc` to dismiss. → [Ch. 8 §Toggle Inline Suggestions](/docs/ai-assistant#toggle-inline-suggestions)

**Git Branch dropdown / Git Push** — Toolbar shortcuts for the current branch and push action. The full Git submenu lives under Tools. → [Ch. 3 §Git integration](/docs/file-browser#git-integration)

**Grid Layout (retired)** — The per-tab Grid Layout mode, Layout Wizard, Layout Presets, and Widget Palette. rc18 replaced them with the Workbench. Old grid layouts are not carried over. → [Ch. 16 §Go back to tabs](/docs/workspaces#go-back-to-tabs)

**Groups (Connection Manager / Fleet)** — Folder-like organisation in the left tree of either manager. Purely organisational. → [Ch. 2 §Grouping hosts](/docs/ssh-devices#grouping-hosts) | [Ch. 5 §Groups](/docs/fleet#groups)

**Guest Pass** — Single-use, time-bound invitation URL that grants a teammate a role-scoped session on your device through the Cloud Portal. → [Ch. 21 §Inviting a guest](/docs/cloud-portal-docs#inviting-a-guest)

## H

**Hierarchy Builder** — The SoC/IC visual canvas for composing multi-agent pipelines. Requires the AI Hierarchy plan. `Ctrl+Shift+H` (in builds where bound). → [Ch. 9 — AI Hierarchy Builder](/docs/hierarchy-builder)

**Host key** — The remote SSH server's identity fingerprint. AidaIDE asks you to trust it on first connect and refuses if it changes. → [Ch. 2 §Host key](/docs/ssh-devices#host-key)

## I

**IC (Integrated Circuit)** — A chip you drop inside a *SoC* in the Hierarchy Builder. Encapsulates a sub-workflow. Double-click to drill in. → [Ch. 9 §Mental model](/docs/hierarchy-builder#mental-model)

**Inline AI suggestions** — Greyed *ghost text* completions in the editor. Toggle via **AI → Toggle Inline Suggestions**. → [Ch. 8 §Toggle Inline Suggestions](/docs/ai-assistant#toggle-inline-suggestions)

**Intel Panel** — Optional context strip on a connection tab showing host facts (uptime, OS, IP). Toggle from the connection tab's top toolbar. → [Ch. 2 §Anatomy of a connection tab](/docs/ssh-devices#anatomy-of-a-connection-tab)

**IOC (Indicator of Compromise)** — A signal that a system has been attacked (a malicious IP, hash, domain, TTP). The IOC Database collects and matches them. → [Ch. 7 §IOC](/docs/security-tools#ioc)

**IP Access Control** — Security tab for managing IP allow/deny lists applied at firewall / host level. → [Ch. 7 — Security Tools](/docs/security-tools)

## K

**Keyboard shortcuts** — Default bindings + Command Palette + customisation surface. See the whole chapter for the master list. → [Ch. 14 — Shortcuts and Command Palette](/docs/shortcuts)

**Keybinding context** — Some shortcuts only fire when a specific tab/panel has focus. Hints for "shortcut works in one tab but not another." → [Ch. 14 §Keybinding context](/docs/shortcuts#keybinding-context)

**Kubernetes Client** — Sysadmin tab that wraps `kubectl` against a configured kubeconfig context. Pods, deployments, services, logs, exec. → [Ch. 12 §Kubernetes Client](/docs/sysadmin#containers)

## L

**Layout** — A named arrangement of panels, splits, stacks, and floating windows. A file under `~/.aidaide/layouts/` you can copy to another PC. Not a Marketplace listing. → [Ch. 16 §Save named layouts](/docs/workspaces#save-named-layouts)

**Layout Mode (retired)** — Classic Tabs or Grid. Removed in rc18. Use **View → Workbench → Use the workbench shell** (on by default), or uncheck it and restart for a plain tabbed window. → [Ch. 16 §Go back to tabs](/docs/workspaces#go-back-to-tabs)

**Layout Wizard (retired)** — The toolbar sparkle wizard. Removed in rc18. Name a layout from the toolbar **Workspace** list instead. → [Ch. 16 §Save named layouts](/docs/workspaces#save-named-layouts)

**LCOT (Local Chain of Thought)** — The right-side one-click command panel on every connection tab. 800+ READ/WRITE commands, plus your own. → [Ch. 4 — LCOT Panel](/docs/lcot)

**LDAP / LDAPS** — Lightweight Directory Access Protocol; LDAPS is the TLS-wrapped version. Active Directory talks LDAPS. → [Ch. 12 §LDAP / LDAPS](/docs/sysadmin#ldap--ldaps)

**License key** — A long base64-ish string that activates AidaIDE. Stored in the vault after activation. Treat as a secret. → [Ch. 17 §License key format](/docs/licensing#license-key-format)

**Line endings** — CRLF vs LF. Editor shows the current setting in the status bar and lets you swap per-file. → [Ch. 3 §Line endings](/docs/file-browser#line-endings)

**Live Coding Agents** — "Pair programmer over your shoulder" mode. Always on, watches what you do, offers proactive suggestions. Token-hungry. `Ctrl+Shift+J`. → [Ch. 8 §Live Coding Agents](/docs/ai-assistant#live-coding-agents-ctrlshiftj)

**Local vs remote file** — Editor distinguishes by tab title prefix. A remote file's tab title is prefixed with the host name; a local file's tab is just the filename. → [Ch. 3 §Local vs remote file](/docs/file-browser#local-vs-remote-file)

## M

**Macy (Ask Macy)** — Voice-narrated interactive guided tour. General IDE tour or the 16-section Hierarchy Builder tour. Replay from **Help → Ask Macy**. → [Ch. 1 §Onboarding & guided tours](/docs/getting-started#onboarding--guided-tours)

**Master password** — The password you set on the Smart Login window that unlocks the *vault*. No recovery — write it down. → [Ch. 1 §Master password](/docs/getting-started#master-password)

**Menu bar** — The dropdowns at the top of the main window. Listed in full at [Ch. 1 §Menu bar](/docs/getting-started#menu-bar).

**Minimap (Hierarchy Builder)** — Bird's-eye view of the canvas; click-to-jump. Bottom-left of the canvas. → [Ch. 9 §Window layout](/docs/hierarchy-builder#window-layout)

**Module (Hierarchy Builder)** — Leaf component inside an IC: Supervisor, Worker, AI Agent, Filter, protocol node. → [Ch. 9 §Mental model](/docs/hierarchy-builder#mental-model)

**Monitoring Dashboard** — Sysadmin tab that visualises metrics gathered by Metrics Collector (CPU/MEM/disk/net per host). → [Ch. 12 §Monitoring & alerts](/docs/sysadmin#monitoring--alerts)

## N

**Notebook** — The central tabbed region of the main window. Connection tabs pin to the left, feature tabs to the right. → [Ch. 1 §What you see](/docs/getting-started#what-you-see)

## O

**Onboarding Wizard** — First-run, software-focused wizard (theme, AI provider, font, first connection). Re-run from **Help → Setup Wizard**. → [Ch. 1 §Onboarding Wizard](/docs/getting-started#first-run-wizards)

**ONVIF** — Open Network Video Interface Forum. The standard most IP cameras speak for discovery and stream configuration. → [Ch. 10 §ONVIF](/docs/cameras#onvif)

**OS fingerprinting** — Probing a host to guess its operating system from response idiosyncrasies. Done by the Port Scanner and Host Discovery tabs. → [Ch. 6 §OS fingerprinting](/docs/network-tools#os-fingerprinting)

**OTA (Over The Air) Update Manager** — Fleet feature that signs, distributes, and tracks aida-lite updates across devices. → [Ch. 5 §Publishing an update](/docs/fleet#publishing-an-update)

**OIDC** — OpenID Connect, the federated login protocol used by the Cloud Portal. Same identity as your AidaIDE license. → [Ch. 21 §Logging in](/docs/cloud-portal-docs#logging-in)

## P

**Packet Capture** — Network tab that wraps `tcpdump`-style capture and decoding. Saves to standard pcap. → [Ch. 6 — Network Tools](/docs/network-tools)

**Patch Manager / Patch Policies** — Sysadmin pair that scans for missing OS patches across the fleet and applies them by policy (window, retry, ring). → [Ch. 12 §Patch management](/docs/sysadmin#patch-management)

**pcap** — Packet capture file format. AidaIDE reads/writes standard pcap so Wireshark and the network team can open the file directly. → [Ch. 6 §pcap](/docs/network-tools#pcap)

**Performance Monitor** — Diagnostic tab under **Settings → Performance** that shows per-subsystem CPU/RSS in real time. → [Ch. 13 §Performance Monitor](/docs/settings-themes#performance-monitor)

**Persona** — An *agent* with character — tone, voice, personality. Shipped examples: "Wes, the patient mentor," "Macy, the interactive guide," "Astrid, the security skeptic." → [Ch. 8 §Agent vs persona vs workflow](/docs/ai-assistant#agent-vs-persona-vs-workflow)

**Persona Portal** — Tab for chatting with a configured persona. Distinct from AI Agent Portal in that the persona has narrative styling baked in. → [Ch. 8 §Persona Portal](/docs/ai-assistant#persona-portal)

**PKI Manager** — Security tab that acts as a small internal CA: generate keys, sign certs, manage revocation. → [Ch. 7 — Security Tools](/docs/security-tools)

**Plugin** — Installable extension that adds menu items, tabs, themes, or behaviour. Distributed as a `.plugin` file. → [Ch. 15 §.plugin file](/docs/plugins#plugin-file)

**Plugin & Widget Manager** — Where installed plugins and widgets live. Enable/disable, configure, remove, update. → [Ch. 15 — Plugins, Widgets, Marketplace](/docs/plugins)

**PLC (Programmable Logic Controller)** — Industrial control device. AidaIDE's PLC-related menus speak Modbus / Ethernet-IP / S7 / OPC UA. → [Ch. 5 §Protocol Wizard](/docs/fleet) | [Ch. 4 §Command categories](/docs/lcot#command-categories)

**Port Scanner** — Network tab for TCP/UDP port discovery against a target or range. → [Ch. 6 — Network Tools](/docs/network-tools)

**Privileges (database)** — User-level RW/RO grants. The Database Manager shows the current user's privileges per connection. → [Ch. 11 §Privileges and safety](/docs/databases#privileges-and-safety)

**Project root** — Folder treated as the working directory for Find in Files, Run, and Git operations. Set via **File → Open Project Folder** or per-workspace. → [Ch. 3 §Project root](/docs/file-browser#project-root)

**Protocol Wizard** — Tool under Tools → Protocol Wizard for scaffolding integrations against common embedded protocols (Modbus, S7, OPC UA). → [Ch. 5 §Protocol Wizard](/docs/fleet)

**Public key / Private key** — Asymmetric cryptography pair. The **private** key stays on your machine; the **public** key (one short line) goes on the remote in `~/.ssh/authorized_keys`. → [Ch. 2 §Public key vs private key](/docs/ssh-devices#public-key-vs-private-key)

**Permission group** — Read-Only / Collaborator / Trusted / Owner. Bundle of capability flags applied to a Cloud Portal session. → [Ch. 21 §Permission groups in plain language](/docs/cloud-portal-docs#permission-groups-in-plain-language)

**Prompt-host** — The interactive approval flow: a Collaborator action that needs Owner approval pauses with an Allow/Deny popup on the host. → [Ch. 21 §Terms](/docs/cloud-portal-docs#prompt-host)

## Q

**Quick Toolkit (LCOT)** — Curated 62-command, 9-subgroup "fix it in 30 seconds" sysadmin loop inside LCOT. Half READ, half WRITE. → [Ch. 4 §Sysadmin Quick Toolkit](/docs/lcot#sysadmin-quick-toolkit)

**QWERTZ** — The German keyboard layout (Y/Z swapped; `ß` on `-`). Layout ID `de`. → [Ch. 22 §International keyboard layouts](/docs/input-devices#international-keyboard-layouts)

## R

**READ vs WRITE zones (LCOT)** — Every LCOT command is classified. READ is safe diagnostic; WRITE modifies state and the leaf is red with a confirmation prompt. → [Ch. 4 §READ vs WRITE zones](/docs/lcot#read-vs-write-zones)

**Recent Connections** — File menu submenu listing the last 10 hosts you connected to. Survives restarts. → [Ch. 2 §Recent connections](/docs/ssh-devices#recent-connections)

**Recurring trap** — Engineering shorthand for a class of bug that has shipped more than once. Common ones called out in this guide: hardcoded port 22, fabricated demo data, UTF-8 mismatch, HTML-escape miss on exports, silent SFTP-to-local fallback on save. → [Ch. 18 §Recurring trap](/docs/troubleshooting#recurring-trap)

**Registry Client** — Sysadmin tab for browsing and editing remote Docker registries. → [Ch. 12 §Registry Client](/docs/sysadmin#containers)

**RTSP (Real-Time Streaming Protocol)** — The transport most IP cameras actually use, typically discovered via ONVIF. → [Ch. 10 §RTSP](/docs/cameras#rtsp)

**Run panel** — Editor sidebar that runs the active file in a language-aware way (Python: `python file.py`, Node: `node file.js`, etc.). → [Ch. 3 §Run panel](/docs/file-browser#run-panel)

**RD PIN** — Six-digit Remote Desktop pairing code that pops up on the host the first time a browser opens Remote Desktop. 60-second expiry. → [Ch. 21 §Remote Desktop in the browser](/docs/cloud-portal-docs#remote-desktop-in-the-browser)

**Remote Desktop (browser)** — Live Socket.IO mirror of your AidaIDE window inside a browser tab on the Cloud Portal. → [Ch. 21 §Remote Desktop in the browser](/docs/cloud-portal-docs#remote-desktop-in-the-browser)

## S

**Safe mode** — `aidaide --safe-mode` launches with no plugins, default theme, default settings. Used to isolate whether a bug is in core or in third-party code. → [Ch. 18 §Safe mode](/docs/troubleshooting#safe-mode)

**SAST vs DAST** — **S**tatic Application Security Testing analyses source code at rest. **D**ynamic AST runs the app and probes it. AidaIDE ships SAST; pair with external DAST tools. → [Ch. 7 §SAST vs DAST](/docs/security-tools#sast-vs-dast)

**Secret Scanner** — Security tab that scans a repo (or directory) for accidentally committed secrets (AWS keys, GitHub tokens, etc.) using regex + entropy heuristics. → [Ch. 7 — Security Tools](/docs/security-tools)

**Settings panel** — Seven-section UI under **File → Settings** for everything not exposed in a menu. → [Ch. 13 — Settings, Themes, Preferences](/docs/settings-themes)

**SFTP (SSH File Transfer Protocol)** — File transfer riding on SSH. AidaIDE uses SFTP for the remote tree and for editor saves to remote files. → [Ch. 2 §SFTP](/docs/ssh-devices#sftp)

**Sidebar (left)** — The dock on the left containing Connections, Files, and AI panels. Toggleable. → [Ch. 1 §What you see](/docs/getting-started#what-you-see)

**SignalFlowEngine** — The in-process runtime that executes a Hierarchy Builder SoC: walks the graph, fires modules, routes signals. → [Ch. 9 — Hierarchy Builder](/docs/hierarchy-builder)

**Smart Login** — The startup vault-unlock window. Single-purpose. The file behind it is `smart_login.py` (`login_dialog.py` is legacy). → [Ch. 1 §Unlocking the vault](/docs/getting-started#unlocking-the-vault)

**SoC (System on Chip)** — The outermost container in the Hierarchy Builder. One canvas tab = one SoC. → [Ch. 9 §Mental model](/docs/hierarchy-builder#mental-model)

**Soft-restart bypass** — Login window is skipped when AidaIDE restarted itself (admin push or post-update). Session is restored automatically. **File → Exit** to force a password prompt next launch. → [Ch. 1 §Soft-restart bypass](/docs/getting-started#soft-restart-bypass)

**Splash** — The 4-second `$_` reveal between vault unlock and the main IDE. Cosmetic. Disable with `AIDA_SPLASH=off`. → [Ch. 1 §Splash screen](/docs/getting-started#splash-screen)

**Split panes (editor)** — Side-by-side or top/bottom editors inside one tab. Each pane can hold any open file. → [Ch. 3 §Split panes](/docs/file-browser#split-panes)

**SSH (Secure Shell)** — The encrypted protocol for logging into another machine. AidaIDE speaks SSH and SFTP using a Python implementation — no system `ssh` required. → [Ch. 2 §SSH](/docs/ssh-devices#ssh-secure-shell)

**Status bar** — The bottom strip showing current file path, cursor position, encoding, line endings. → [Ch. 1 §What you see](/docs/getting-started#what-you-see)

**Substream** — Cameras often encode two simultaneous streams — a high-quality main and a low-resolution sub. Use the sub for grid views to save CPU. → [Ch. 10 §Substream](/docs/cameras#substream)

**Syntax highlighting** — Per-language colouring of code in the editor, driven by file extension. Override per-file from the language picker in the status bar. → [Ch. 3 §Syntax highlighting](/docs/file-browser#syntax-highlighting)

**Spectate** — Read-only follow mode where your viewport mirrors another watcher's scroll. Cancels the moment you scroll independently. → [Ch. 22 §Presence and spectate](/docs/input-devices#presence-and-spectate)

**Shortcut bar (mobile)** — Two-row on-screen keypad (Esc / Tab / modifiers / arrows / F1-F12) summoned by a three-finger tap on the Remote Desktop tab. → [Ch. 22 §The mobile shortcut bar](/docs/input-devices#the-mobile-shortcut-bar)

## T

**Template Manager** — Sysadmin tab for managing configuration templates (Jinja2) used by Ansible Runner and DSC. → [Ch. 12 §Configuration management](/docs/sysadmin#configuration-management)

**Theme** — Colour scheme for the IDE. Live preview in **View → Theme**. Brand defaults to navy `#0B1620` + cyan `#4DE4E4`. → [Ch. 13 §Themes and appearance](/docs/settings-themes#themes-and-appearance)

**Threat Intel Feeds** — Security tab that pulls and matches threat intelligence (IOC lists, CVE feeds). Configurable per feed. → [Ch. 7 — Security Tools](/docs/security-tools)

**TLS (Transport Layer Security)** — Encryption layer used by HTTPS, LDAPS, secure database connections. AidaIDE's PKI Manager issues TLS certs for internal use. → [Ch. 11 §TLS](/docs/databases#tls)

**Toolbar** — The icon strip under the menu bar. Listed left to right at [Ch. 1 §Toolbar](/docs/getting-started#toolbar).

**Trace (Hierarchy Builder)** — Per-run log of every signal that fired in the SoC. Toolbar button on the canvas. → [Ch. 9 — Hierarchy Builder](/docs/hierarchy-builder)

**Tunnel gateway** — Hosted WebSocket endpoint that brokers traffic between aidaide.app and your local AidaIDE Flask. Mutual TLS using a per-device cert. → [Ch. 21 §Terms](/docs/cloud-portal-docs#tunnel-gateway)

**Touch mode** — Trackpad / Direct Touch / Scroll. The bottom-screen pill on the Cloud Portal Remote Desktop tab. → [Ch. 22 §Touch modes](/docs/input-devices#touch-modes)

## U

**UTF-8** — See *Encoding (UTF-8)*. The required encoding for every read and write inside AidaIDE.

## V

**Vault** — Encrypted local file holding every secret AidaIDE knows about — SSH passwords, key passphrases, API keys, database credentials, license activation. Unlocked by the *master password*. → [Ch. 1 §Vault](/docs/getting-started#vault)

## W

**Web Dashboard** — Browser-served Fleet status page at `http://localhost:5001/fleet`. Launch from the Fleet menu (or `python web_server.py` as a workaround). → [Ch. 5 — Fleet Management](/docs/fleet)

**Widget** — A small, embeddable UI element (chart, gauge, status pill) that can be placed on the Dashboard or in a connection tab. → [Ch. 15 §Plugin vs widget](/docs/plugins#plugin-vs-widget)

**Widget Permissions** — Capability model that limits what a widget can read/write (filesystem, network, vault). → [Ch. 15 §Permissions are real](/docs/plugins#permissions-are-real)

**Windows Services / Windows Updates** — Sysadmin tabs that surface `services.msc` and `wsus`-style functionality across managed Windows boxes. → [Ch. 12 §Windows management](/docs/sysadmin#windows-management)

**WinRM (Windows Remote Management)** — Microsoft's remote-command protocol. The Windows-management tabs use WinRM where SSH would be used on Linux. → [Ch. 12 §WinRM](/docs/sysadmin#winrm)

**Workflow (AI)** — A deterministic, multi-step recipe that calls one or more agents, with file/shell side effects. YAML/JSON files in `~/.aidaide/workflows/`. → [Ch. 8 §AI Workflows](/docs/ai-assistant#ai-workflows)

**Workbench** — The desktop window (since rc18; current Windows download is 1.0.0-rc19): every tab is a panel you can split, stack, or tear off. On by default. Not in the Cloud Portal. Android stays a separate Lite-class app, not a desktop host download. Linux experimental (soft peer). → [Ch. 16 — Workspaces and Layouts](/docs/workspaces)

**Workspace list** — Toolbar control for your named layouts (**Open**, **Save**). Also **Settings → Workspace**. → [Ch. 16 §Save named layouts](/docs/workspaces#save-named-layouts)

**Watcher pill** — Header widget that lists everyone currently looking at this device; click a name to spectate. → [Ch. 22 §Presence and spectate](/docs/input-devices#presence-and-spectate)

## Z

**Zoom (Hierarchy Builder canvas)** — Mouse wheel to zoom; clamped to the current tier's min/max. **View → Reset Zoom** if you wander past the canvas bounds. → [Ch. 9 — Hierarchy Builder](/docs/hierarchy-builder)

---

## See also

- [Main TOC](/docs/user-guide)
- [Keyword Index](/docs/keyword-index) — alphabetical lookup including UI labels and menu items
- [Chapter 18 — Troubleshooting & FAQ](/docs/troubleshooting) — symptom-first lookup
- [Chapter 20 — Quick Reference (Cheat Sheet)](/docs/quick-reference) — single printable page: CLI flags, env vars, file paths, ports, full shortcut table

---

# Quick Reference (Cheat Sheet)

Source: https://aidaide.app/docs/quick-reference

A single printable page. Every CLI flag, environment variable, file path, default port, and shortcut consolidated. The rest of the guide explains *why*; this chapter tells you *what to type*.

**Windows is the primary host OS.** The packaged desktop download is Windows. macOS and Linux builds are in progress. Linux is a soft peer — experimental builds are available to try while first-class Linux support ships. macOS and Linux notes on this page are path and quirk details for those builds. They are not current packaged downloads.

Tip: press `Ctrl+P` in your browser to print just this page. The tables below render cleanly to A4 / Letter.

---

## Command-line flags

Pass these when you launch the packaged Windows build from a terminal. The same flags apply on an in-progress macOS build or an experimental Linux build. Those builds are not current packaged downloads.

| Flag | What it does | See |
| --- | --- | --- |
| `--safe-mode` | Skip plugins, default theme, default settings. Use to isolate whether a bug is in core or in third-party code. | [Ch. 18 §Safe mode](/docs/troubleshooting#safe-mode) |
| `--log-level=DEBUG` | Verbose logging to `logs/aidaide.log` under the user-data directory. Packaged Windows: `%APPDATA%\AidaIDE\logs\`. In-progress macOS and experimental Linux: `~/.aidaide/logs/`. Use for one reproduction; revert (the log gets large). | [Ch. 18 §Verbose / debug log mode](/docs/troubleshooting#verbose--debug-log-mode) |
| `--no-splash` | Skip the 4-second `$_` reveal. Same effect as `AIDA_SPLASH=off`. | [Ch. 1 §Splash screen](/docs/getting-started#splash-screen) |
| `--workspace <path>` | Open AidaIDE pre-loading a saved workspace JSON. | [Ch. 16 §Opening a workspace](/docs/workspaces#opening-a-workspace) |
| `--project <path>` | Open AidaIDE with the given folder as the project root. | [Ch. 3 §Opening files and projects](/docs/file-browser#opening-files-and-projects) |
| `--reset-vault` | Force the vault reset prompt on launch (equivalent to **Forgot password? Reset vault**). Destructive — every stored secret is wiped. | [Ch. 1 §Unlocking the vault](/docs/getting-started#unlocking-the-vault) |

Launch from a terminal so you can see startup errors. The packaged Windows executable is `"C:\Program Files\AidaIDE\aidaide.exe"`. An in-progress macOS build or an experimental Linux build — including a Linux install built on the device itself — may use a binary named `aidaide`. That name is not a current packaged macOS or Linux download.

---

## Environment variables

| Variable | Values | Effect |
| --- | --- | --- |
| `AIDA_SPLASH` | `lite` *(default)*, `full`, `off` | Splash animation mode. `full` enables the 1,400-glyph code rain; `off` skips the splash. |
| `ANTHROPIC_API_KEY` | a long random string | Used by **Claude Agent Manager** if no key is set in the vault. The vault always wins when both are present. |
| `OPENAI_API_KEY` | a long random string | Same as above, for OpenAI provider. |
| `AIDA_LOG_DIR` | absolute path | Overrides the default logs directory: `%APPDATA%\AidaIDE\logs\` on the packaged Windows build, or `~/.aidaide/logs/` on an in-progress macOS or experimental Linux build. |
| `AIDA_NO_TELEMETRY` | `1` | Disables anonymous usage telemetry. Same as **Settings → General → Telemetry → Off**. |
| `AIDA_THEME` | theme name | Forces a theme on launch, overriding the saved preference. |
| `AIDA_DISABLE_PLUGINS` | `1` | Equivalent to `--safe-mode`. Useful when you cannot pass CLI flags (e.g. launched by a desktop shortcut). |

Environment variables apply per shell session. On the packaged Windows build, set them in a PowerShell profile (`$PROFILE`) or under System Properties → Environment Variables. Bash `~/.bashrc` and zsh `~/.zshrc` apply only on an in-progress macOS build or an experimental Linux build. They are not how you configure a current packaged download.

---

## File and directory paths

All locations are under the AidaIDE user-data directory. On the packaged Windows build this is `%APPDATA%\AidaIDE\`. On an in-progress macOS build, most state is `~/.aidaide/`, with some auxiliary files in `~/Library/Application Support/AidaIDE/`. On an experimental Linux build it is `~/.aidaide/`. Those macOS and Linux paths describe in-progress and experimental builds, not current packaged downloads.

| Path | Contents |
| --- | --- |
| `vault.enc` | The encrypted secret store. Back this up. |
| `salt` | Per-install salt for the master password KDF. Back up with `vault.enc`. |
| `config.json` | Top-level settings: theme, splash mode, telemetry, startup behaviour. |
| `keybindings.json` | Your custom keyboard shortcut overrides (only differences from defaults). |
| `keybindings/presets/` | Bundled binding presets: Vim, Emacs, default. |
| `layouts/` | Named Workbench layouts (toolbar **Workspace** list). Copy the file to another PC. |
| `workbench_layout.json` | The current arrangement, saved as you go. |
| `builder_drafts/` | Hierarchy Builder autosaves — one JSON per SoC under edit. |
| `lcot_user_commands.json` | Your custom LCOT commands. |
| `recent_files.json` | Last 20 files (local or remote). |
| `recent_connections.json` | Last 10 SSH hosts you connected to. |
| `logs/aidaide.log` | Main application log. Rotates at 10 MB. |
| `logs/ssh.log` | Per-connection SSH transcripts. |
| `audit.log` | Append-only security-event log (vault unlocks, license activations, PKI cert ops). |
| `bug_reports/` | Bundles staged for upload when offline. Auto-flushed on next successful launch. |
| `plugins/` | Installed `.plugin` directories. |
| `widgets/` | Installed widget directories. |
| `workflows/` | AI Workflow YAML/JSON files. |
| `cache/` | Disposable. Safe to delete; AidaIDE re-creates. |

The user-data directory is **not** touched by the uninstaller. Back it up before reinstalling if you want to preserve state. See [Ch. 18 §`~/.aidaide/`](/docs/troubleshooting#aidaide).

---

## Default ports and endpoints

| What | Port / URL |
| --- | --- |
| SSH (override per-host in Connection Manager) | `22` |
| SFTP | rides on SSH; same port |
| MySQL / MariaDB | `3306` |
| PostgreSQL | `5432` |
| MongoDB | `27017` |
| Redis | `6379` |
| HTTP MJPEG (cameras) | `80` / `8080` |
| RTSP (cameras) | `554` |
| ONVIF WS-Discovery | UDP `3702` (multicast) |
| Fleet Web Dashboard | `http://localhost:5001/fleet` |
| OTA manifest endpoint | `https://updates.aidaide.app/manifest.json` |
| Modbus TCP | `502` |
| OPC UA | `4840` |
| Siemens S7 | `102` |

If a connection is failing, the most common single cause is the wrong port. AidaIDE has historically had a few callsites that hardcode `22` for SSH — see [Ch. 2 §Ports and the port-22 trap](/docs/ssh-devices#ports-and-the-port-22-trap).

---

## Default keyboard shortcuts (full table)

A single consolidated table of every default binding. The same data is in [Chapter 14](/docs/shortcuts) split by category; here it is one alphabetical lookup. Customise any of these via **File → Keyboard Shortcuts…** (`Ctrl+K, Ctrl+S`). The table uses the Windows `Ctrl` convention of the packaged download. On an in-progress macOS build, substitute `Cmd` for `Ctrl` unless noted. That substitution is not a current packaged macOS download.

| Shortcut | Action |
| --- | --- |
| `Alt+Click` | Add a cursor at the click point (multi-cursor) |
| `Alt+F4` (Windows) / `Cmd+Q` (in-progress macOS) | Exit AidaIDE |
| `Alt+Shift+drag` | Column / box selection in the editor |
| `Ctrl+,` | Open Settings |
| `Ctrl+/` | Toggle line comment |
| `Ctrl+A` | Select all (in editor) |
| `Ctrl+Alt+L` | Load Chat Session |
| `Ctrl+Alt+M` | Marketplace Store |
| `Ctrl+Alt+P` | Plugin & Widget Manager |
| `Ctrl+Shift+B` | Add panel. `Ctrl+Shift+A` is AI Chat. |
| `Ctrl+F` | Find in current file |
| `Ctrl+F2` | Bookmark current line |
| `Ctrl+G` | Go to Line (`42:10` puts cursor at col 10 of line 42) |
| `Ctrl+H` | Replace in current file |
| `Ctrl+K, Ctrl+S` | Keyboard Shortcuts editor (two-key chord) |
| `Ctrl+O` | Open File |
| `Ctrl+R` | Refresh syntax (editor context) — avoid double-binding |
| `Ctrl+S` | Save current file |
| `Ctrl+Shift+A` | AI Chat |
| `Ctrl+Shift+Alt+S` | Save Chat Session |
| `Ctrl+Shift+D` | Debug Console |
| `Ctrl+Shift+F` | Find in Files |
| `Ctrl+Shift+H` | Agent Hierarchy Builder *(label may say "Replace in Files" in some builds — Hierarchy Builder is the actual behaviour)* |
| `Ctrl+Shift+I` | Toggle AI Sidebar |
| `Ctrl+Shift+J` | Live Coding Agents |
| `Ctrl+Shift+K` | Create New Plugin/Widget |
| `Ctrl+Shift+M` | Claude Agent Manager |
| `Ctrl+Shift+N` | New Project from Template |
| `Ctrl+Shift+O` | Open Project Folder |
| `Ctrl+Shift+P` | Command Palette |
| `Ctrl+Shift+W` | Protocol Wizard |
| `Ctrl+Shift+Z` | Redo (alternate) |
| `Ctrl+T` | New Connection Tab |
| `Ctrl+Y` | Redo |
| `Ctrl+Z` | Undo |
| `Ctrl+→` / `Ctrl+←` | Move cursor by word |
| `Ctrl+scroll` (editor) | Zoom font |
| `Ctrl+scroll` (canvas) | Zoom Hierarchy Builder canvas |
| `End` | Cursor to end of line |
| `Esc` (Command Palette) | Close palette |
| `F2` | Jump to next bookmark |
| `F3` | Find Next |
| `F5` | Run current file *(`F5` in connection-tab editors can double-fire if you bind a second action; tracked)* |
| `F8` | Run selection (Query Editor) |
| `F9` | Toggle breakpoint |
| `Home` | Cursor to start of line (twice = column 1) |
| `Middle-click` (tab bar) | Close tab |
| `Shift+F2` | Jump to previous bookmark |
| `Shift+F3` | Find Previous |
| `Tab` / `Shift+Tab` | Indent / Outdent selection |

Command Palette prefixes:

- `>` filter to actions only (skip settings)
- `@` jump to a symbol in the current editor file
- `:` jump to a line number in the current editor file

See [Ch. 14 §Customising shortcuts](/docs/shortcuts#customising-shortcuts) for the full editor.

---

## Top "how do I…?" — one-line answers

| Question | One-line answer |
| --- | --- |
| Open a new SSH connection | Toolbar `+` → pick host (or **Connection Manager** to add one). [Ch. 2](/docs/ssh-devices) |
| Set a non-22 SSH port | Connection Manager → host → **Port** field. [Ch. 2 §Ports](/docs/ssh-devices#ports-and-the-port-22-trap) |
| Generate an SSH key | `ssh-keygen -t ed25519 -C "you@example.com"` then `ssh-copy-id user@host`. [Ch. 2 §SSH key pair setup](/docs/ssh-devices#setting-up-your-first-ssh-key-pair) |
| Run a Python file on the remote box | Open in editor, click **▶** in the editor toolbar. [Ch. 3 §Running files](/docs/file-browser#running-files) |
| Find text across the whole project | `Ctrl+Shift+F`. [Ch. 3 §Find and Find in Files](/docs/file-browser#find-and-find-in-files) |
| Diff a remote file vs. a local file | Open both, **Tools → Git → Diff Viewer → Two files**. [Ch. 3 §Diff Viewer](/docs/file-browser#diff-viewer) |
| Add my own one-click command | LCOT panel → **+ Add Command**. [Ch. 4 §Adding your own command](/docs/lcot#adding-your-own-command) |
| Push a binary to a Raspberry Pi | Fleet → **Deploy Lite** (or toolbar `⚡`). [Ch. 5 §Deploy Lite](/docs/fleet#deploy-lite) |
| Scan the LAN for cameras | **Network → Cameras → Scan for Cameras**. [Ch. 10 §Scanning for cameras](/docs/cameras#scanning-for-cameras) |
| Connect to MySQL | **Preview → Database → Database Manager → Add MySQL**. [Ch. 11 §Database Manager](/docs/databases#database-manager) |
| Open the Command Palette | `Ctrl+Shift+P`. [Ch. 14 §Command Palette](/docs/shortcuts#command-palette-ctrlshiftp) |
| Switch themes | **View → Theme**. [Ch. 13 §Themes and appearance](/docs/settings-themes#themes-and-appearance) |
| Re-run the first-run wizard | **Help → Setup Wizard**. [Ch. 1 §First-run wizards](/docs/getting-started#first-run-wizards) |
| Enter my license key | **Help → Enter License Key**. [Ch. 17 §Activating your license](/docs/licensing#activating-your-license) |
| Save my current layout for later | Toolbar floppy icon next to the layout combo. [Ch. 16 §Saving and switching layouts](/docs/workspaces#saving-and-switching-layouts) |
| File a bug report | **Help → Report a Bug**. [Ch. 18 §Filing a useful bug report](/docs/troubleshooting#filing-a-useful-bug-report) |
| Make the splash go away | `AIDA_SPLASH=off`. [Ch. 1 §Splash screen](/docs/getting-started#splash-screen) |
| Launch without plugins | Packaged Windows: `"C:\Program Files\AidaIDE\aidaide.exe" --safe-mode`. In-progress macOS or experimental Linux: `aidaide --safe-mode` (not a packaged download). [Ch. 18 §Safe mode](/docs/troubleshooting#safe-mode) |
| Find a feature when I forget the menu | Toolbar magnifier → **Feature Browser**. [Ch. 14 §Feature Browser](/docs/shortcuts#feature-browser) |
| Drop into the Hierarchy Builder | **AI → Agent Hierarchy Builder** (or `Ctrl+Shift+H`). [Ch. 9](/docs/hierarchy-builder) |

---

## Platform-specific notes

**Windows is the primary host OS.** The packaged desktop download is Windows. macOS and Linux builds are in progress. Linux is a soft peer — an experimental source tarball is available to try while first-class Linux support ships. It is not a signed peer installer and not a first-class packaged host. Windows notes below describe the packaged download. macOS notes are for the in-progress build. Linux notes are for the experimental build, including a Linux install built on the device itself.

### Windows

The packaged download. These notes apply to the Windows host.

- **Master password** modifier keys: `Ctrl`, not `Cmd`. The Smart Login window respects the system IME — if typing into the password field shows nothing, swap input method with `Win+Space`.
- **User-data path** is `%APPDATA%\AidaIDE\` (typically `C:\Users\<you>\AppData\Roaming\AidaIDE\`).
- **Packet Capture** needs Npcap installed in WinPcap-compatible mode. The first capture-tab open will prompt if missing.
- **OpenSSH Server** for local testing: Settings → Apps → Optional Features → Add → **OpenSSH Server**, then start the **OpenSSH SSH Server** service. [Ch. 2 §SSH setup paths](/docs/ssh-devices#i-do-not-have-an-ssh-server--setup-paths)
- **Private key file permissions**: Windows OpenSSH checks them. Right-click key → Properties → Security → Advanced → Disable inheritance → remove all users except your own.
- **Path separators in workspace JSONs** are `\\` (escaped). Hand-editing requires care.

### macOS

**In progress.** Not a current packaged download, and not a first-class packaged host. The path and quirk notes below apply if you are running an in-progress macOS build.

- All `Ctrl` shortcuts above are `Cmd` on macOS. The Settings shortcut is `Cmd+,` (system convention).
- **User-data path** has two locations: `~/.aidaide/` for the bulk of state, and `~/Library/Application Support/AidaIDE/` for some auxiliary files.
- **Packet Capture** requires the `bpf` device to be readable by your user. Recent macOS releases ship `ChmodBPF` from the Wireshark installer; install Wireshark for the helper, then close it.
- **Camera USB access**: macOS will prompt for camera permission the first time the IDE accesses one. Accept; otherwise the feed stays black.
- **Vault keychain integration** is opt-in under **Settings → Security → macOS Keychain** — when enabled, your master password is also stored in the Keychain so the vault unlocks transparently per session.

### Linux

**Experimental.** Not a first-class packaged host. Linux is a soft peer — an experimental source tarball is available to try, and these notes also cover a Linux install built on the device itself.

- `Ctrl+Alt+S` may be eaten by your window manager (Cinnamon, KDE) for "screenshot." Re-bind in the shortcuts editor if so.
- **Packet Capture** needs `cap_net_raw,cap_net_admin=eip` on the Python interpreter: `sudo setcap cap_net_raw,cap_net_admin=eip $(which python3)`. Or run AidaIDE with `sudo` (not recommended).
- **Camera USB access** needs your user in the `video` group: `sudo usermod -aG video $USER` then log out / back in.
- **Wayland**: `Alt+Click` multi-cursor depends on your compositor's modifier-key handling. Most distros work; some KDE configs do not. Use right-click → **Add Cursor Here** as a fallback.
- **systemd integration** under **Sysadmin → Service Manager** assumes a working `systemctl` — works on Ubuntu, Debian, Fedora, RHEL, openSUSE, Arch. Alpine / Void / Gentoo may need OpenRC adapters.

---

## Pricing tiers at a glance

| Plan | Monthly | Yearly | Devices | AI Hierarchy |
| --- | --- | --- | --- | --- |
| Free | $0 | $0 | — | — |
| Pro | $19 | $190 | — | Included |
| Teams Pro | $70 | $700 | — | Included |

---

## Recurring traps to be aware of

Engineering shorthand for bug classes that have shipped more than once. Mentioned across the guide; consolidated here so you can scan for symptoms:

- **Port-22 hardcoded** — non-22 SSH port mysteriously fails. [Ch. 2 §Ports](/docs/ssh-devices#ports-and-the-port-22-trap)
- **Silent SFTP-to-local fallback** — remote save appears to succeed but the file did not change. [Ch. 18 §Save did not persist](/docs/troubleshooting#save-to-a-remote-file-appears-to-succeed-but-the-file-did-not-change)
- **UTF-8 mismatch** — non-ASCII filenames or content show mojibake. [Ch. 18 §Mojibake](/docs/troubleshooting#file-browser-editor-save)
- **Fabricated demo data presented as real** — Host Discovery, Service Detection, Threat Intel, certificate inventory. [Ch. 18 §"Demo mode" vs real data](/docs/troubleshooting#demo-mode-vs-real-data)
- **HTML escape missed on exports** — XSS in security reports. [Ch. 18 §Security tools](/docs/troubleshooting#security-tools)
- **Hierarchy Builder shortcut label lies** — `Ctrl+Shift+H` opens Hierarchy Builder despite some declarations naming it `edit.replaceInFiles`. [Ch. 14 §Recurring binding traps](/docs/shortcuts#recurring-binding-traps)
- **Decrypt-failure-returns-empty-string** — password field mysteriously blanks. [Ch. 18 §A password field mysteriously goes blank](/docs/troubleshooting#a-password-field-mysteriously-goes-blank)

If you suspect a recurring trap, note it in your bug report — the engineering team will check the relevant tracker.

---

## Where to go from here

- Forgot a term? → [Chapter 19 — Glossary](/docs/glossary)
- Need to find a UI label by name? → [Keyword Index](/docs/keyword-index)
- Something is broken? → [Chapter 18 — Troubleshooting & FAQ](/docs/troubleshooting)
- Brand-new user? → [Chapter 1 — Getting Started](/docs/getting-started) then [Chapter 2 — SSH Devices](/docs/ssh-devices)
- Master of everything? → File feedback via **Help → Report a Bug** — the dialog accepts documentation suggestions too.

---

# Cloud Portal and Web Access

Source: https://aidaide.app/docs/cloud-portal-docs

The Cloud Portal is the way to reach your AidaIDE machine from a browser — from your phone, a tablet, a hotel laptop, or a teammate's workstation. Nothing is installed remotely. You log into <https://aidaide.app>, pick a device you own, and the portal proxies your browser through a secure reverse tunnel back to a small web server running next to your local AidaIDE.

This chapter is also where the in-browser **Web Dashboards** (Fleet, Network, Security, Containers, Monitoring, Backup, Admin) live — they all serve through the same portal once you log in.

## What this chapter covers

- Logging in to the Cloud Portal and registering a device.
- Inviting a teammate with a **Guest Pass** — short-lived shareable URL.
- The **Access** panel (sessions, passes, permanent collaborators).
- The **Remote Desktop** browser tab — live frames of your AidaIDE screen.
- The **Web Hierarchy Composer** (browser version of the AI Hierarchy Builder).
- The other Web Dashboards bundled with the portal.
- Self-hosting the portal for offline / on-prem use.

## What is the Cloud Portal?

When AidaIDE is running on your local machine, a small Flask web server inside the app exposes a private API (port 5001 by default). The Cloud Portal is a hosted service at **aidaide.app** that proxies an authenticated browser request through a secure WebSocket tunnel back to that local Flask, with role-based access control and a "prompt the host" approval flow for sensitive actions.

You do **not** need to forward a port on your router. You do **not** need a public IP. The tunnel is initiated outward by your machine.

The portal is a thin façade: every byte of work still happens on your local AidaIDE. The portal is just authentication, transport, and a permission grid.

## Logging in

1. In your browser, open <https://aidaide.app/web/login>.
2. Sign in with the same account you use for your AidaIDE license (Google / GitHub / email). The portal uses OIDC.
3. The first time you log in from a given machine, you may be asked to verify by email.
4. Once in, you land on **My Devices** — every AidaIDE machine that has phoned home for this account.

If you have not connected any device yet, see [I do not have a device registered yet — setup paths](#i-do-not-have-a-device-registered-yet--setup-paths) below.

## Registering a device

A device must "enrol" once before it appears in My Devices.

1. On the device, launch AidaIDE and unlock the vault.
2. Open **Settings → Cloud Portal** (Chapter 13).
3. Click **Enable Cloud Access**. AidaIDE generates a per-device certificate, registers a stable `device_id`, and starts the outbound tunnel.
4. Refresh **aidaide.app/web/devices** — your device appears. Click it to open the **device detail** page.

The device enrolment is **idempotent**: re-running it on the same machine reuses the same `device_id` and rotates the cert.

## The device detail page

A device page has four areas:

- **Header** — device name, OS, last-seen time, online dot. Pencil-icon next to the name lets you rename.
- **Access panel** (new in 0.5.66+) — see below.
- **Activity** — audit log of who connected, when, and what they did.
- **Quick links** — buttons that open the in-browser dashboards proxied to this device (Fleet, Remote Desktop, Network, Security, etc.).

## The Access panel

The Access panel is where you decide **who else** can use this device.

```
ACCESS                                          [+ Invite a guest]
─────────────────────────────────────────────────────────────────
ACTIVE NOW (2)
  alice@x.com   [Read-Only]   23m online · last seen 4s   [Disconnect]
  bob@y.com     [Trusted]      5h online · last seen 11s  [Disconnect]

PASSES (3 active)                           [ ] Show revoked/expired
  ● Active     Read-Only   expires in 47m   claimed by alice@x.com   [Revoke]
  ○ Unclaimed  Trusted     expires in 18h   invited charlie@z.com    [Copy claim URL] [Revoke]

PERMANENT COLLABORATORS (1)                       [+ Add by email]
  wes@example.com    Owner                                (you)
  alice@x.com        Read-Only                       [Revoke]
```

Three sections in one panel:

- **Active now** polls every 5 seconds. Disconnect kicks a session and frees the guest-pass slot it was using.
- **Passes** is the list of every Guest Pass you have ever issued for this device. Toggle **Show revoked/expired** to see history.
- **Permanent collaborators** is for teammates who should have ongoing access; they consume a paid seat (not a guest pass).

### Inviting a guest

Click **+ Invite a guest** to open the modal:

- **Permission group** — Owner, Trusted, Collaborator, Read-Only.
- **Duration** — 1 hour, 24 hours, 7 days, or custom minutes.
- **Email** (optional) — pre-fills the claim page; not required.
- **Note** (optional) — what the pass is for; visible in the audit log.

Click **Issue**. The modal flips to a success view with a single-use **claim URL** and a **Copy** button.

Send that URL to the person you want to invite. When they open it they go through OIDC login (or sign up if needed), then are redirected straight into your device with the chosen permission group. The pass auto-revokes at the expiry; you can also revoke it manually any time.

A single guest pass can only be claimed by one user. Multiple people need multiple passes.

### Permission groups in plain language

| Group | Can read | Can change settings | Can run commands | Can use Remote Desktop |
|---|---|---|---|---|
| **Read-Only** | yes | no | no | view-only |
| **Collaborator** | yes | no | yes (with prompt-host) | yes (input gated) |
| **Trusted** | yes | yes | yes | yes |
| **Owner** | yes | yes | yes (no prompt) | yes |

"Prompt-host" means: when a Collaborator tries to do a sensitive thing (run a WRITE LCOT command, change a file outside the workspace, open the vault), the request pauses and the device owner gets a desktop popup asking **Allow / Deny / Always for this user**.

## Remote Desktop in the browser

From a device page, click **Remote Desktop** to open a live mirror of your AidaIDE window in the browser tab. This is a Socket.IO-driven streaming view: frames flow from your local screen up the tunnel; keyboard and mouse events flow back down.

When you first open it, you may be prompted for a six-digit **RD PIN** that pops up on the host machine. The PIN expires in 60 seconds; entering it pairs this browser session with the host.

Once paired:

- **Mouse and keyboard** are forwarded. The browser tab grabs keystrokes; press `Esc + ~` to release if you ever need to.
- **Quality** drop-down picks between 1080p / 720p / 480p substreams. Lower resolutions stay smooth on slow connections.
- **Read-only** badge appears in the header if your role does not include input.

Behind the scenes:

- Transport is WebSocket-only (no long-poll). The tunnel forwards Socket.IO frames between your browser and a local Socket.IO server on `localhost:5001`.
- The `api.aidaide.app` proxy forwards your authenticated browser cookie via the WS as `additional_headers`, so server-side capability checks still work.
- Mouse coordinates are translated from browser viewport → desktop coords with DPI scaling applied.

## Other web dashboards

The portal also serves these full-page dashboards for the connected device. Each is opened from **Quick links** on the device detail page or from the global toolbar.

- **Fleet Dashboard** (`/fleet`) — the same Fleet Manager view from Chapter 5, in HTML.
- **Network Dashboard** (`/network`) — scanner results, topology map, traffic charts (cross-reference [Ch. 6](/docs/network-tools)).
- **Security Dashboard** (`/security`) — vulnerability scanner, threat-intel feeds (cross-reference [Ch. 7](/docs/security-tools)).
- **Container Dashboard** (`/containers`) — Docker / Compose / k8s controls (cross-reference [Ch. 12](/docs/sysadmin#docker-and-containers)).
- **Monitoring Dashboard** (`/monitoring`) — CPU / RAM / disk / alerts.
- **Backup Dashboard** (`/backup`) — backup jobs, last-run status.
- **Admin Dashboard** (`/admin`) — only visible to Owners; user/seat/license management for the account.
- **Config Dashboard** (`/config`) — read-only view of settings the desktop app is currently using.

All eight dashboards reuse the same auth / role checks. A Read-Only guest sees data but every button that mutates state is hidden or disabled.

## Web Hierarchy Composer

The **Composer** is the browser version of the AI Hierarchy Builder (Chapter 9). Open it from the device dashboard via the **Composer** toolbar button — internally `showAIPanel('composer')`.

Toolbar (top of the canvas), left to right:

- **Zoom In / Out / Fit** — `+` / `-` / `Fit` buttons. Fit auto-frames every node in the current document.
- **Auto Layout** — runs the canvas auto-layout algorithm. Tidy when you have pasted a lot of nodes in by hand.
- **Auto Wire** — connects unwired outputs to the nearest matching input (best-effort, you can undo with `Ctrl+Z`).
- **Validate** — runs the same checks as the desktop's `Validate` button: dangling wires, type mismatches, missing properties.
- **Run / Stop** — calls `/api/ai/composer/run` against the SignalFlowEngine in your local AidaIDE.

Modes (pill row, top-left): **flat / ic / soc / hierarchy**. They mirror the desktop builder's modes — see Chapter 9 §Modes.

Library, properties, and minimap panes float on the right. The composer state is persisted in `~/.aidaide/builder_drafts/` so the desktop builder picks up exactly the same document.

Known parity gaps with the desktop builder (as of run 1 / 2026-05-29):

- The **animated trace** view is desktop-only — the web composer runs validation but does not animate signal flow.
- **Right-click context menus** on the web canvas are a subset.
- **Macy tour** (the 16-section tutorial overlay) is desktop-only.

Track parity progress in [Ch. 18 §Composer parity gaps](/docs/troubleshooting#composer-web-vs-desktop-parity).

## Self-hosting the portal

For air-gapped or compliance-sensitive environments you can run the portal on your own infrastructure.

- The portal is a FastAPI service in `cloudportal/api/` plus a Python tunnel gateway in `cloudportal/gateway-py/`.
- A `docker-compose.yml` is included for a quick local stand-up.
- A `docker-compose.prod.yml` plus `fly/` configs are included for the reference Fly.io deploy.
- Set `DEV_AUTH_BYPASS=1` to bypass OIDC for local development (do not enable in production).

Read `cloudportal/README.md` for the run-order, and `cloudportal/HANDOFF.md` for the architecture brief.

## Terms & Setup

### Cloud Portal
Hosted service at <https://aidaide.app> that proxies authenticated browser requests to your local AidaIDE through a secure reverse tunnel. No port forwarding required.

### Guest Pass
A single-use, time-bound, role-scoped invitation URL. Issued from the **Access** panel; claimed by clicking the URL and signing in. Auto-revokes at expiry, can be revoked manually.

### Permission group
The bundle of capability flags applied to a session. Read-Only / Collaborator / Trusted / Owner. Defined in `cloudportal/db/migrations/versions/0001_groups.py`.

### Prompt-host
The interactive approval flow: when a Collaborator tries a sensitive action, the device owner sees a popup with **Allow / Deny / Always for this user**. Decisions are logged in the device audit trail.

### Device enrolment
The one-time handshake where an AidaIDE install registers itself with the portal. Generates a per-device cert under `~/.aidaide/cloud_portal/device.pem`.

### Tunnel gateway
The hosted WebSocket endpoint that brokers traffic between the portal and your local AidaIDE. Speaks mutual TLS using the device cert.

### `webportal/d/<device_id>/` path
The portal's URL space for proxied access. Anything you would normally reach at `localhost:5001/foo` on the device is reachable as `aidaide.app/webportal/d/<id>/foo` once authenticated.

### Remote Desktop (browser)
Socket.IO streaming of your AidaIDE window into a browser tab. Transport is WebSocket-only. Authenticated by the same session cookie as the rest of the portal.

### RD PIN
The 6-digit pairing code shown on the host's desktop the first time a browser tries to open Remote Desktop. Expires in 60 seconds. Prevents a session that has compromised your browser cookie alone from opening a screen mirror.

### OIDC (OpenID Connect)
The federated login protocol used by the portal. Same identity you used to buy your AidaIDE license.

### Web Hierarchy Composer
Browser-based UI for the AI Hierarchy Builder (Chapter 9), opened with the **Composer** toolbar button on a device's dashboard.

### "I do not have a device registered yet" — setup paths

You need at least one AidaIDE install enrolled before the portal has anything to proxy.

**Easiest — the machine you are already on:**
1. Open **Settings → Cloud Portal**.
2. Tick **Enable Cloud Access**.
3. Wait 5-10 seconds for the green **Tunnel up** badge.
4. Reload <https://aidaide.app/web/devices>.

**Headless server (Pi / Linux VM):**
1. Install AidaIDE on the headless box (Chapter 1).
2. Run `aidaide --enable-cloud --headless` once with the vault unlocked.
3. The CLI prints the enrolment URL — open it once in a browser to confirm ownership.
4. From then on the tunnel auto-starts with the service.

**Test without a real device — self-host the portal:**
1. `cd cloudportal && docker compose up -d` to start API + gateway + Postgres locally.
2. Run the example local Flask: `python -m cloudportal.examples.local_flask`.
3. Open `http://localhost:8000/web/login` and use the seeded dev user `wes@electronyx.test`.
4. The example Flask appears as a device you can proxy to.

### "I do not have a teammate to invite yet" — practice without exposing your machine

If you want to see what a guest sees but have no one to send the URL to:

1. Issue a pass with the **Read-Only** group.
2. Copy the claim URL.
3. Open it in a private/incognito window.
4. Sign in with a second account (a free Google account is fine).
5. You will land on your own device with the Read-Only badge — exactly what your teammate would see.

Revoke the pass when you are done.

## See also

- [Chapter 5 — Fleet Management](/docs/fleet) for the underlying Fleet Web Dashboard at `localhost:5001/fleet`.
- [Chapter 9 — AI Hierarchy Builder](/docs/hierarchy-builder) for the desktop builder that the Web Composer mirrors.
- [Chapter 13 — Settings](/docs/settings-themes) for **Settings → Cloud Portal**.
- [Chapter 17 — Updates, Licensing, Support](/docs/licensing) for the account / license that gates portal access.
- [Chapter 18 — Troubleshooting & FAQ](/docs/troubleshooting) for tunnel-down and PIN-issue fixes.
- [Chapter 22 — Input Devices in the Browser](/docs/input-devices) for every touch / gamepad / international-keyboard detail of the Remote Desktop tab.

---

# Input Devices in the Browser

Source: https://aidaide.app/docs/input-devices

The Cloud Portal Remote Desktop tab (Ch. 21) is more than a keyboard and mouse mirror. It works on phones, tablets, gaming controllers, and keyboards from any country. This chapter is the field guide for every input device the browser RD supports.

## What this chapter covers

- Three **touch modes** — Trackpad, Direct Touch, Scroll.
- The full **gesture vocabulary** the touch controller understands.
- The on-screen **mobile shortcut bar** (modifier keys + arrows + F-keys).
- International **keyboard layouts** (en-US / en-GB / Deutsch QWERTZ / Français AZERTY / Español).
- **Presence and spectate** — seeing other people on the same device.
- "I do not have a touch screen / gamepad / international keyboard yet" — how to practise without the hardware.

## Touch modes

Open the Remote Desktop tab on a phone or tablet and a small pill appears at the bottom of the screen with three icons:

| Icon | Mode | What it does |
|---|---|---|
| 👆 | **Direct Touch** | Where you tap is where the cursor goes. Best for big buttons and full-screen apps. |
| 🖱️ | **Trackpad** | Your finger moves a virtual cursor that lives on screen. Best for fine clicking on small UI. Default mode. |
| 📜 | **Scroll** | All finger motion translates to scroll wheel. Best for reading long pages. |

The mode switcher gives a short haptic buzz (`navigator.vibrate`) when you switch modes — so you know it took even if you cannot see the bottom of the screen.

### Trackpad mode and the virtual cursor

When Trackpad is active a crosshair overlay (the **AidaVirtualCursor**) shows where your next tap will land. The crosshair is a real DOM element — it does not consume server input — so it stays smooth even on a slow tunnel. Sensitivity is **1.5×** by default: a one-inch finger sweep moves the cursor about 1.5 inches on the remote screen. Pinch-zoom does not change the sensitivity, so once you have zoomed in for precision the cursor stays predictable.

## Gesture vocabulary

The TouchController class in `web/static/js/touch_controls.js` recognises eight gestures:

| Gesture | Maps to |
|---|---|
| Single tap | Left click |
| Double tap | Double click |
| Long press (500ms) | Right click |
| Two-finger tap | Right click |
| One-finger drag | Mouse hold + move (selecting text, drag-drop) |
| Two-finger scroll | Mouse wheel |
| Two-finger pinch | Client-side zoom (no event sent to the host) |
| Three-finger tap | Toggle the on-screen shortcut bar |
| Top-edge swipe | Show / hide the RD toolbar |

The top-edge swipe is handy on phones where the toolbar would otherwise eat 10% of your screen. Swipe down from the top to summon it, swipe up to dismiss.

**Pinch is client-side only.** Pinching does not zoom anything on the host machine — it zooms your browser-side bitmap. The host has no idea you have done it. This keeps the round-trip latency-free and means the host never sees a flurry of pinch events.

## The mobile shortcut bar

Three-finger tap brings up the **shortcut bar** (built by `mobile_keyboard.js`). Two rows of keys you cannot type on a touchscreen keyboard alone:

- **Row 1 (essentials)**: `Esc`, `Tab`, `Ctrl`, `Alt`, `Shift`, `←`, `→`, `↑`, `↓`.
- **Row 2 (function row)**: `F1`–`F12`, plus a numpad chip for `0`–`9`.

Modifier keys (Ctrl / Alt / Shift / Win) latch when tapped — tap once to arm, then tap a letter to send the chord, then the modifier auto-releases. The latched state is visible (the chip glows). Tap a modifier again to manually release it.

This bar is also the only way to send the Windows key from an iPad — there is no native physical shortcut for it.

## International keyboard layouts

`web/static/js/hid_keyboard_layouts.js` ships five layouts:

| ID | Layout | Notes |
|---|---|---|
| `en-US` | English (US) | Default. ASCII passthrough. |
| `en-GB` | English (UK) | `£` on `Shift+3`, `@` and `"` swapped. |
| `de` | Deutsch QWERTZ | Y/Z swapped; `ß` on `-`; AltGr+Q = `@`. |
| `fr` | Français AZERTY | A/Q and Z/W swapped; digits require Shift. |
| `es` | Español | `Ñ` on the `;` slot; `¿` and `¡` on the bottom row. |

Pick a layout from the keyboard chooser in the RD toolbar. The vendor-neutral passthrough layout (`vendor: 'passthrough'`) means physical key positions are translated to the right scan codes for the chosen logical layout, so an AZERTY user on a QWERTY hardware keyboard still types correctly.

Switching layouts only affects what your browser sends — the host's own keyboard layout setting still applies as the final translation. If you have a layout mismatch where one side is set wrong, fix the side you control.

## Presence and spectate

If two people are looking at the same device at the same time, both their cursors appear on the host's screen (small coloured circles) and each browser tab shows a **watcher pill** in the corner with the other person's name + status dot.

- **Watcher pill** — listed names of everyone currently looking at this device. Click a name to spectate.
- **Spectate mode** — your view follows another watcher's scroll position and chapter / tab. You can read along but cannot click; spectating ends as soon as you scroll on your own.
- **Heartbeat** — `/api/presence/heartbeat` fires every 12 seconds; you drop off the watcher list 25 seconds after the last heartbeat. Phones going to sleep are detected and broadcast a clean leave.

This is enabled for any session with at least Collaborator permission. Read-Only viewers appear in the watcher list but their cursor does not show on the host (privacy default).

## Edge cases worth knowing

- **iPad Pencil** is treated as a single-finger touch with hover support. Long-press still works.
- **Android stylus** is the same as a finger touch — no hover events on most stock pens.
- **Wacom tablet over USB to a tablet computer** works because the browser exposes it as a pointer; pressure is **not** forwarded to the host (it is treated as a left-click).
- **Two simultaneous cursors** (someone on a Wacom + your finger) — the touch controller defers to the most-recent pointer.

## Terms & Setup

### Touch mode
Trackpad / Direct Touch / Scroll. The pill at the bottom of the RD tab. Default is Trackpad.

### Virtual cursor (AidaVirtualCursor)
The crosshair overlay shown in Trackpad mode. DOM-rendered; not sent to the host.

### Shortcut bar
The two-row keypad summoned by three-finger tap. Built by `mobile_keyboard.js`.

### Layout (keyboard)
The logical map from physical key positions to characters. Five ship in-the-box; default `en-US`.

### QWERTZ
The German keyboard layout — Y and Z swapped compared to QWERTY. Selected with the `de` layout ID.

### AZERTY
The French keyboard layout — A/Q and Z/W swapped, digits require Shift. Selected with the `fr` layout ID.

### Spectate
Read-only follow-mode: your viewport scrolls with another watcher's. Cancels the moment you scroll independently.

### Watcher pill
Header-corner widget listing who else is currently looking at this device. Each name is a clickable spectate button.

### Heartbeat (presence)
The 12-second poll to `/api/presence/heartbeat` that keeps you on the watcher list. 25-second timeout for stale entries.

### "I do not have a touch screen yet" — practise without one

Chrome and Edge ship a touch emulator inside DevTools:

1. Open the Cloud Portal Remote Desktop tab.
2. F12 to open DevTools.
3. Click the **Toggle device toolbar** icon (or `Ctrl+Shift+M`).
4. Pick **Responsive** / **iPad** / **Pixel 7** etc. from the device dropdown.
5. The browser now emits touch events instead of mouse events. The touch mode pill appears.

This emulator does **not** simulate pinch-zoom — for that you need real fingers or two mice.

### "I do not have a gamepad yet" — Gamepad API

If a gamepad ships in a later release, the same testing path applies: any USB or Bluetooth controller appears as a `Gamepad` in the browser's `navigator.getGamepads()` array. Plug a controller in, press any button, and the browser surfaces it. Test pages like `<https://gamepad-tester.com/>` confirm the OS sees it.

### "I do not have a foreign-language keyboard yet" — practise without one

Pick the layout from the chooser; your physical keys do not need to match. With the `de` (QWERTZ) layout selected on a US keyboard:

- Press the physical `Y` key — the host sees `Z`.
- Press the physical `Z` key — the host sees `Y`.
- Press `Right-Alt + Q` — the host sees `@`.

This is exactly how a French user with an AZERTY keyboard physically types a character that lives in a different position than where it is printed on the keycap.

### "I do not see other watchers" — checks

If presence is silent when you expect a teammate to be online:

1. The server must be at AidaIDE 0.5.66+ — earlier builds had no presence backend.
2. Your role must be Collaborator or higher to broadcast presence; Read-Only is silent by default.
3. Network: SSE (`/api/presence/stream`) must not be blocked by an aggressive proxy. Some hotel Wi-Fi captures long-lived connections.
4. Open the browser console and look for `presence.js` log lines — heartbeat failures print there.

## See also

- [Chapter 21 — Cloud Portal and Web Access](/docs/cloud-portal-docs) for how the Remote Desktop tab is opened in the first place.
- [Chapter 9 — AI Hierarchy Builder](/docs/hierarchy-builder) for keyboard shortcuts on the desktop builder (separate from RD's shortcut bar).
- [Chapter 13 — Settings](/docs/settings-themes) §SSH for the host-side terminal type (`xterm-256color`) that affects how arrow keys are reported.
- [Chapter 18 — Troubleshooting & FAQ](/docs/troubleshooting) for RD PIN issues and tunnel-down recovery.

---

# Hardware Lab

Source: https://aidaide.app/docs/hardware-lab

Public docs for **Hardware Lab** — the same topic as in-app User Guide **Chapter 23** (`23_hardware_lab`). Citation-ready definition: [What is Hardware Lab?](/guides/hardware-lab). Product surface: [/embedded#hardware-lab](/embedded#hardware-lab). Official desktop commit: `cf6b1f7`.

This site also has a separate public chapter for [OTA Updates](/docs/ota-updates) at `/docs/ota-updates`. That OTA chapter is not Hardware Lab.

## What this chapter covers

- Virtual hardware-in-the-loop (HIL) on a **virtual clock**
- Timeline scenarios, assertions, pass/fail
- **Where in the app:** Tools → **Hardware Lab (HIL)...**; also Intelligence Panel → **Virtual Board** → Open Hardware Lab
- **Bench** — 2D pinout/board views A–E (virtual parts, wires, live mirror; **not 3D**)
- **Run on Device** — SSH/Linux may push a temporary `hil_device_agent`; Arduino USB serial score
- **Record** — SSH pin watch or USB recorder sketch
- **Mirror** on the virtual board (default on)
- The **33-board** library (Raspberry Pi is in that count)
- CI Hardware Lab GitHub Action and Board Library Manager
- Free/base vs Pro AI (AI Scenario / AI Fix)
- **Also in the Oct 9 PC build** — local web Composer and editor, and the desktop workbench and Cloud Portal toolbar (not virtual HIL)

## What Hardware Lab is

Hardware Lab runs your device code against a **simulated board** — pins, I2C, UART — on a virtual clock, with **timeline scenarios** and **assertions** that return pass/fail in milliseconds. Then **Run on Device**: SSH/Linux **may** push a temporary `hil_device_agent` and diff sim vs bench; Arduino USB serial score (no standing agent; no C++ edge-diff).

**Where in the app:** Tools → **Hardware Lab (HIL)...**; also Intelligence Panel → **Virtual Board** → Open Hardware Lab.

It is **not** the Fleet **Test Panel**. Fleet Test Panel is device-connected test suites under Fleet tools. See [Fleet Management §Test Panel](/docs/fleet#test-panel) and the Related note there.

## Simulate → assert → Run on Device → diff

1. **Simulate** — run the file against a virtual board. The simulator uses simulated time, so a `sleep()` advances the clock instantly. A 30-second hardware scenario can finish in under a millisecond and give the same answer every run. That is a **virtual clock**, not wall-clock electrical HIL.
2. **Assert** — put stimuli on a timeline, then state expectations: pin states, pulse counts, I2C writes, log output. You get pass/fail with the check that failed — not a wall of serial output.
3. **Run on Device** — SSH/Linux **may** push a temporary `hil_device_agent` + sim vs bench diff; Arduino USB serial score (no standing agent; no C++ edge-diff). Scenario inputs are GPIO-API injected (not electrical jumpers). Outputs and timing are real on the SSH/Linux road. That helper is temporary for the run.
4. **Diff** — compare simulation and bench edge by edge: matched edges with timing skew in milliseconds, edges the device never produced, and edges only the device produced.

**Record** — SSH pin watch **or** USB recorder sketch; both become replayable stimuli.

**Mirror** on virtual board (default on) shows live edges on Board View / Bench during a real run.

## Bench (A–E)

**Bench** is a 2D pinout/board view (layouts A–E) — not a 3D CAD scene. Phase F (3D) is not started. Layouts A–E carry virtual parts, wires, and a live mirror of pin state.

A separate [3D world plugin](/3d) for Hardware Lab and the AI Agent Hierarchy builder is coming to Pro and Teams Pro. It is not purchasable yet and does not replace this free 2D Bench.

## 33 boards

The library is **33 boards** with real pin maps. Raspberry Pi is in that count. Simulation and Generic Linux GPIO are in the 33 as well — not only Jetson, Arduino, and ESP32.

| Family | In the 33 |
| --- | --- |
| Simulation Board | Yes — virtual target for scenarios |
| Generic Linux GPIO | Yes |
| Raspberry Pi | ×6 — Generic, 3B, 4B, 5, Zero W, Zero 2 W |
| ESP32 classic | ×3 |
| Jetson | ×6 |
| Arduino | ×10 |
| Espressif | ×6 — S2, S3, C3, C6, ESP8266 NodeMCU, D1 Mini |

The same board registry feeds Hardware Lab, the Board Library Manager, and the editor's board picker. Pin numbering follows the platform (sketch-style on Arduino; BCM-compatible on Jetson).

**Also ships:** CI Hardware Lab GitHub Action + Tools → **Board Library Manager...** (same 33-board registry).

## Agents — what Hardware Lab does and does not install

AidaIDE is **agentless SSH/SFTP by default**. Terminal, SFTP, and LCOT on a normal host need only standard SSH/SFTP.

SSH/Linux Run on Device and Record **may** push a tiny **temporary HIL helper** (`hil_device_agent`) over SSH/SFTP for that run. Arduino USB serial score has no standing agent and no C++ edge-diff. There is no standing Hardware Lab agent.

## Free vs Pro

| Capability | Tier |
| --- | --- |
| Virtual board / HIL, timeline scenarios, assertions, pass/fail | Free / base |
| Board view and pinout replay | Free / base |
| Run on Device (SSH/Linux may push helper + sim vs bench diff; Arduino USB serial score) | Free / base |
| Record (SSH pin watch or USB recorder sketch) | Free / base |
| AI Scenario (model writes stimuli and expectations) | Pro AI suite |
| AI Fix (model proposes a fix from failing checks) | Pro AI suite |
| 3D world plugin | Coming — Pro and Teams Pro (not purchasable yet) |

There is no separate Hardware Lab license. See [pricing](/pricing). Optional Pro is **$19/mo or $190/yr**. Teams Pro is **$70/mo or $700/yr for 5 seats**.

## OS and download

AidaIDE ships for **Windows today**. Linux experimental (soft peer). Create a free account to download — there is no naked installer path.

## Also in the Oct 9 PC build

These notes are from the Oct 9 PC build (`7e4239d`, `1a26cef`, `c4f622f`, `cd9acb2`, `ca26052`). They are not Hardware Lab. The first three are the local web Composer and editor, the browser surfaces of that PC build. The last two are the desktop window.

### Native IC and SoC debugger controls

On the browser IC canvas and the browser SoC canvas, **Run a saved circuit to attach the native debugger.** The **Live debug** panel is that debugger. Controls are **Pause**, **Resume**, **Step**, **Set breakpoint**, **Clear breakpoint**, and **Inspect wire**, over the existing private owned-worker channel. **Pause on start (SignalFlow only)**. Step advances the next native wave. Inspect wire can report "No packet has been observed on this wire."

### Saved SoC wire aliases and browser workspace restore

On the browser SoC canvas, a saved wire alias draws only when a retained placement alias resolves: its unique canonical node and the actual linked IC agree. Ambiguous, shadowed, and unknown targets refuse.

Browser workspace restore: a rendered current-window capture saved two local files, cursor positions, and the unsaved flag. Explicit fresh review reopens the clean file at its saved cursor while preserving the other live draft. There is no automatic SSH contact. This checkpoint does not establish complete desktop parity.

### Native editor workspaces and shared-IC impact review

Home and PC editor windows retain multi-file views, cursor and scroll positions, and private unsaved drafts. **Saved Workspaces** explicitly review file restoration into the source window. The dashboard has a **Saved workspaces** button.

Opening a shared IC displays the saved SoCs and placement IDs affected by its definition. IC mode shows **Shared definition: N placements in M SoCs**. Unsynced placements detach parameters only. IC writes, **Delete**, and saved **Undo** refuse while an actual owned dependent SoC has not observed cleanup. This is not a new authorization capability.

### One-arrangement workbench layouts

On the desktop window, the workbench is either all plain tabs or all Classic. Adopting a connection tab while Classic is active returns every panel to its tab first, with a toast. `apply_classic`, `classic_all`, and Classic on connect wait while any connection tab in the main window is unconnected. **Classic layout for this connection** lays out every connected tab.

The three-pane workspace keeps its proportions. Sidebar and intelligence sashes come from the saved panel sizes, else the first layout's fractions, else 20/20. The layout re-applies once the last part is home.

### Cloud Portal toolbar light

On the desktop toolbar, **Portal OFF** is a plain grey button with a hollow dot. Connecting or reconnecting is amber and shows the try count. **Portal ON** is a green button with a solid dot. The tooltip follows the state.

A tunnel the launch brought back says so in its tooltip and once in a toast with a **Turn off** button. **Settings > Cloud Portal > Remote Access Keep-Alive** reads: "Turn the Cloud Portal back on when AidaIDE starts, if it was on when AidaIDE closed." `resume_on_launch` defaults on.

## Related

- [What is Hardware Lab?](/guides/hardware-lab) — citation-ready definition (canonical URL; `/hardware-lab` redirects here)
- [Embedded](/embedded#hardware-lab) — product page
- [Fleet Management §Test Panel](/docs/fleet#test-panel) — device-connected tests, not marketing Hardware Lab
- [LCOT Panel](/docs/lcot) — Local Chain of Thought is the command library, not HIL
- [OTA Updates](/docs/ota-updates) — fleet firmware rollouts

---

# OTA Updates

Source: https://aidaide.app/docs/ota-updates

Push signed firmware and payload updates to your fleet from AidaIDE — canary rollouts, history per device, and vault-backed signing keys. OTA ships with the **free forever** workspace (unlimited Fleet Manager); Pro ($19/mo) adds the AI suite on top.

This chapter is the deep dive on **Fleet → OTA Update Manager**. For discovery, groups, and Deploy Lite, see [Fleet Management](/docs/fleet).

## What this chapter covers

- Opening the OTA Update Manager
- Publishing a signed release (All / Group / Selected, canary)
- How aida-lite polls, verifies, and applies updates
- Per-device OTA history
- Signing keys (generate, rotate, deploy public keys)
- Smoke-testing with the simulator or a local agent
- Common OTA failures and how to fix them

## Open OTA Update Manager

Open from **Fleet → OTA Update Manager**, **Tools → Device Monitoring → OTA Update Manager**, or the red **OTA Update** toolbar button.

OTA pushes a signed payload to fleet devices; the device's **aida-lite** agent downloads, verifies the signature, and applies it.

## Publishing an update

1. Click **New Release**.
2. Drag the build artefact (for example a `.zip`, `.tar.gz`, or ESP32 firmware `.bin`) into the drop zone.
3. AidaIDE signs the artefact with your OTA private key and generates a manifest. The expected upload URL is `updates.aidaide.app`.
4. Choose roll-out scope — **All** / **Group** / **Selected** devices.
5. Optionally stage as **Canary** — about 10% of the selection first, watch metrics, then promote.
6. Click **Publish**.

Devices running aida-lite poll the manifest at the configured interval (default 5 minutes). When they see a newer version targeted at their group, they download, verify the signature, and apply.

## OTA history

Each device's detail panel in Fleet Manager has an **OTA history** subtab — current version, previous version, and when the last apply succeeded or failed.

Use history when a canary looks healthy before you promote the rest of the fleet.

## Signing keys

The OTA signing keypair is generated on first OTA Manager launch and stored in the **credential vault**.

To rotate: **OTA Update Manager → Settings → Rotate Signing Key**.

- Old releases stay verifiable while the old public key remains on devices.
- New releases require the new public key on devices first — check **OTA Update Manager → Devices → Key Status** before a wide rollout.

## aida-lite on the device

**aida-lite** is the lightweight agent on each fleet device. It reports specs and health to Fleet Manager and applies OTA updates.

Ways to try OTA safely before production:

- **Bundled simulator** — **Tools → Protocol Wizard → Simulated Device** registers a virtual aida-lite with Fleet Manager.
- **Local Linux / WSL2 / VM** — install aida-lite on a box you control and enroll it in a canary group.
- **AidaIDE host itself** — install aida-lite on the workstation for a quick smoke test.

Fleet OTA updates for connected devices are included.

## Troubleshooting

### OTA Update Manager says "No updates available"

1. Click **Refresh** in the OTA Update Manager (endpoint cache TTL is a few minutes).
2. Confirm **Settings → Network → OTA** points at `updates.aidaide.app`.
3. Confirm the device is in the release's target group or selection.

### OTA Update succeeded but the device did not change

- Check aida-lite logs on the device (`journalctl -u aida-lite` on systemd hosts).
- Verify the device is in the target group for that release.
- Verify **Key Status** shows the current signing public key on the device.

### Canary looks fine but promote does nothing

- Confirm you promoted the same release ID (not a duplicate draft).
- Refresh Fleet Manager device list — stale filters can hide the remaining cohort.

## Terms & Setup

- **OTA Update Manager** — signs artefacts and rolls them out to All / Group / Selected devices, with optional canary.
- **aida-lite** — device agent that polls the manifest, verifies signatures, and applies updates.
- **Canary** — stage a small percentage of the selection first, then promote.
- **Signing keypair** — vault-backed keys used to sign manifests; rotate only after deploying the new public key.
- **Fleet Manager** — bulk device registry that hosts OTA history and groups; see [Fleet Management](/docs/fleet).

## Related

- [Fleet Management](/docs/fleet) — discovery, groups, Deploy Lite, serial / PLC monitors
- [Updates, Licensing, Support](/docs/licensing) — AidaIDE app updates and Free / Pro licensing
- [SSH Devices and Connections](/docs/ssh-devices) — interactive sessions vs fleet enrollment
- Live status for the update plane: [/status](/status)