Release v3.1.0a5

# Conflicts:
#	gns3server/compute/builtin/nodes/cloud.py
#	gns3server/utils/interfaces.py

.claude/memory/MEMORY.md

@@ -0,0 +1,37 @@
+# GNS3 Server Project Memory
+
+> **Note**: This directory stores important project-related memories and case studies, managed with the code repository.
+>
+> **How to record**: Use the `/memory` skill to record important information to the project memory directory.
+
+## Quick Reference
+- **Memory directory**: `.claude/memory/`
+- **Skill file**: `.claude/skills/memory/SKILL.md`
+- **Main index**: `MEMORY.md` (this file)
+
+## Topics
+
+### Web Wireshark Integration
+- **[JWT Token Flow](./web-wireshark-jwt-token-flow.md)** - JWT token transmission path in Web Wireshark
+  - Key point: UDPLink only passes through jwt_token, ultimately used by curl command inside Web Wireshark container to authenticate with GNS3 capture stream API
+- **[Xpra HTML5 Client](./xpra-html5-client.md)** - Xpra HTML5 client menu control parameters for customizing the web interface
+
+### RBAC & User Isolation
+- **[RBAC User Isolation Design](./rbac-user-isolation-design.md)** — Three-step permission check design: ACE batch check → created_by filtering → resource pools
+
+### Appliance Management
+- **[GNS3 Appliance Loading](./gns3-appliance-loading.md)** - How GNS3 loads appliance files from builtin and custom directories with priority rules
+
+### uBridge Permission
+- **[uBridge Permission Issue](./gns3-ubridge-permission.md)** - Docker containers fail to start due to missing CAP_NET_ADMIN/CAP_NET_RAW capabilities on uBridge
+- **[Docker iptables FORWARD blocks bridge](./docker-iptables-forward-bridge.md)** - Docker sets FORWARD chain to DROP, blocking kernel bridge forwarding; `sudo iptables -P FORWARD ACCEPT` to fix
+
+### Docker Container Stop Delay
+- **[Docker Container Stop Delay](./docker-container-stop-delay.md)** - Some containers take ~5s to stop because they don't handle SIGTERM (AlpiNet, OstinatoWireshark)
+
+### MCP Service
+- **[MCP Service Design](./mcp-service-design.md)** - MCP (Model Context Protocol) service architecture using FastMCP with SSE transport, JWT auth, 29 tools across 5 domains
+- **[MCP Tool Description Location](./mcp-tool-description-guide.md)** - Where to define MCP tool descriptions: in `@mcp.tool()` functions in `__init__.py`, not in `*_TOOLS` arrays
+
+### Python Code Verification
+- **[Import Validation](./python-import-validation.md)** - Use actual module imports (`python -c "from ... import ..."`) instead of `py_compile` to catch missing imports

.claude/memory/docker-container-stop-delay.md

@@ -0,0 +1,41 @@
+---
+name: docker-container-stop-delay
+description: Docker containers not responding to SIGTERM cause ~5s stop delays when closing a project
+metadata:
+  type: reference
+---
+
+# Docker Container Stop Delay Analysis
+
+## Background
+When stopping a GNS3 project, some Docker containers take ~5s to exit while others stop instantly.
+
+## Root Cause
+Docker's `stop` command sends SIGTERM and waits `t` seconds (GNS3 sets `t=5`) before sending SIGKILL. Containers that don't handle SIGTERM are stuck waiting for the full timeout.
+
+## Affected Containers
+
+| Container | PID 1 | Why it's slow |
+|-----------|-------|---------------|
+| **AlpiNet** (alpine) | `dumb-init` → `bash -i` | Interactive bash ignores SIGTERM by design |
+| **OstinatoWireshark** | `bash` (PID 1) | Linux kernel won't apply default signal actions to PID 1 without an explicit handler; interactive bash doesn't install one |
+
+## Normal Containers (for comparison)
+
+| Container | PID 1 | Why fast |
+|-----------|-------|----------|
+| Chromium | `/usr/bin/chromium` | Chromium handles SIGTERM natively |
+| webterm | `dumb-init` → firefox | Firefox responds to SIGTERM immediately |
+
+## Related Files
+- `gns3-registry/docker/alpinet/Dockerfile`
+- `gns3-registry/docker/ostinato-wireshark/Dockerfile`
+- `gns3-registry/docker/ostinato-wireshark/entry.sh`
+- `gns3-registry/docker/chromium/Dockerfile`
+- `gns3-registry/docker/ipterm/web/Dockerfile`
+- `gns3-server/gns3server/compute/docker/docker_vm.py:1040` — stop timeout parameter `t=5`
+
+## Note
+This is not a GNS3 server bug (except a minor `or` vs `and` logic issue at `docker_vm.py:1037` which doesn't affect behavior). The root cause is in the Docker images themselves.
+
+See also: [[docker-container-stop-delay]]

.claude/memory/docker-iptables-forward-bridge.md

@@ -0,0 +1,38 @@
+---
+name: docker-iptables-forward-bridge
+description: Docker iptables FORWARD DROP blocks kernel bridge forwarding, fix and symptoms
+metadata:
+  type: reference
+---
+
+Docker sets the iptables `FORWARD` chain default policy to `DROP` when the
+Docker daemon starts. This blocks **all** forwarded traffic through Linux
+kernel bridges on the host — including `gns3br{N}` bridges created by the
+builtin Ethernet Switch (ubridge `brctl`).
+
+## Symptoms
+
+- Nodes connected to the switch can send frames into the bridge (visible in
+  `tcpdump -i gns3br{N}`) but never receive forwarded unicast frames.
+- `bridge fdb show` may fail to learn MAC addresses (frames dropped before
+  the bridge learning path).
+- ARP and multicast/broadcast may appear to work because they flood, but
+  unicast replies never reach the destination.
+- OSPF Hello / CDP visible on both sides but ICMP echo reply never returns.
+- `ubridge bridge get_stats` shows symmetric IN/OUT counts (relay is fine),
+  `bridge fdb show` shows learned MACs, `bridge link show` shows `state forwarding`
+  on all ports — yet unicast still doesn't work.
+
+## Fix
+
+Run once per host boot, or make persistent via iptables-persistent / firewall config:
+
+```bash
+sudo iptables -P FORWARD ACCEPT
+```
+
+## Related
+
+- [[ethernet-switch-ubridge-brctl-migration]] — the kernel bridge that hits this
+- [[gns3-server-linux-only]] — datapath constraint
+- [[gns3-ubridge-permission]] — another host-level prerequisite (CAP_NET_ADMIN)

.claude/memory/gns3-appliance-loading.md

@@ -0,0 +1,20 @@
+---
+name: gns3-appliance-loading
+description: GNS3 appliance file loading mechanism and storage locations
+metadata:
+  type: reference
+---
+
+GNS3 loads appliance (.gns3a) files from two locations with specific priority order:
+
+1. **Builtin appliances directory**: `~/.local/share/GNS3/appliances/`
+   - Stores automatically downloaded devices from GNS3 registry
+   - Maintained and updated by the system automatically
+
+2. **Custom appliances directory**: `~/GNS3/appliances/`
+   - Stores user-customized or modified appliance files
+   - Manually managed by users
+
+**Loading priority**: System loads builtin appliances first, then custom appliances. If both directories contain devices with the same `device_id`, the custom appliance overwrites the builtin one. This design allows users to customize devices without having their modifications overwritten by automatic registry updates.
+
+**Implementation**: See `gns3server/controller/appliance_manager.py` in the `load_appliances()` method (lines 314-351).

.claude/memory/gns3-ubridge-permission.md

@@ -0,0 +1,25 @@
+# GNS3 uBridge Permission Issue
+
+## Problem
+Docker container node fails to start with error: `uBridge requires root access or the capability to interact with network adapters`
+
+## Root Cause
+- uBridge needs to create TAP network interfaces to connect Docker containers to GNS3 virtual network
+- This requires `CAP_NET_ADMIN` and `CAP_NET_RAW` capabilities
+- Other node types (like QEMU) may have their own network implementation and don't need uBridge
+
+## Solution
+```bash
+sudo setcap cap_net_admin,cap_net_raw=eip /usr/bin/ubridge
+```
+
+## Code Locations
+- uBridge path check: `gns3server/compute/base_manager.py:298` (`has_privileged_access`)
+- Permission check call: `gns3server/compute/base_node.py:851`
+- Error message definition: `gns3server/compute/base_node.py:852`
+
+## Error Propagation Flow
+Error is propagated via `NodeError` exception:
+1. `NodeError` is caught at `gns3server/api/routes/compute/__init__.py:131-137`
+2. Returns HTTP 409 with JSON: `{"message": "...", "exception": "NodeError"}`
+3. Frontend should read error info from `message` field

.claude/memory/mcp-service-design.md

@@ -0,0 +1,91 @@
+---
+name: mcp-service-design
+description: MCP (Model Context Protocol) service architecture and tool design for GNS3 server
+metadata:
+  type: project
+---
+
+# MCP (Model Context Protocol) Service Design
+
+## Background
+
+Provide a standard MCP interface for GNS3 Server, allowing AI assistants (Claude Code, Claude Desktop) to interact with GNS3 network simulations through the Model Context Protocol.
+
+## Decision/Implementation
+
+### Transport
+- **SSE (Server-Sent Events)** with JWT token authentication
+- Endpoint: `/v3/mcp/transport/sse`
+- Message endpoint: `/v3/mcp/transport/messages/`
+
+### Authentication
+- JWT token obtained via `/v3/access/users/authenticate`
+- Two ways to pass token:
+  - `Authorization: Bearer <jwt>` header (Claude Code via `-H`)
+  - `?token=<jwt>` query param (Claude Desktop, EventSource limitation)
+- Token validated using GNS3's existing `auth_service`
+- Token stored in `contextvars.ContextVar` for per-session isolation
+- Python ≥ 3.9 `asyncio.to_thread` propagates contextvars to threads
+
+### Architecture
+```
+Claude Code / Desktop → SSE → Auth Wrapper → FastMCP Server → Tool Handler → Gns3Connector → GNS3 REST API
+```
+
+### Tool Organization
+Tools are separated by domain into individual files under `gns3server/api/routes/mcp/`:
+
+| File | Domain | Tool Count |
+|------|--------|:----------:|
+| `projects.py` | Project CRUD, open/close/stats | 7 |
+| `nodes.py` | Node CRUD, start/stop/reload/suspend, console WS | 10 |
+| `links.py` | Link CRUD | 5 |
+| `templates.py` | Template CRUD | 5 |
+| `computes.py` | Compute list/get/images | 3 |
+
+**Total: 30 tools**
+
+### Handler Pattern
+- Synchronous functions receiving `(params: dict, gns3_ctx: dict)`
+- Run via `asyncio.to_thread()` to avoid blocking the event loop
+- `gns3_ctx` contains `server_url` and `jwt_token`
+- `Gns3Connector` is created per-handler from `custom_gns3fy`
+
+### Token Lifetime
+- Default: 1440 minutes (24 hours)
+- Configurable via `jwt_access_token_expire_minutes` in `gns3_server.conf`
+
+## Rationale
+- **Why not Direct Controller calls**: MCP layer calls GNS3's own REST API through Gns3Connector, keeping full decoupling and supporting future multi-user/multi-instance scenarios
+- **Why not Streamable HTTP**: Claude Code supports SSE natively via `--transport sse` with custom headers; Streamable HTTP session manager lifecycle conflicts with FastAPI mount
+- **Why not stdio**: stdio is local-only; SSE supports both local and remote deployments
+
+## Related Files
+- `gns3server/api/routes/mcp/__init__.py` — FastMCP server, tool decorators, auth wrapper
+- `gns3server/api/routes/mcp/projects.py` — Project tool handlers
+- `gns3server/api/routes/mcp/nodes.py` — Node tool handlers
+- `gns3server/api/routes/mcp/links.py` — Link tool handlers
+- `gns3server/api/routes/mcp/templates.py` — Template tool handlers
+- `gns3server/api/routes/mcp/computes.py` — Compute tool handlers
+- `gns3server/agent/gns3_copilot/gns3_client/custom_gns3fy.py` — Gns3Connector client
+- `gns3server/api/server.py:87` — MCP route registration
+
+## Configuration
+
+### Claude Code
+```bash
+claude mcp add --transport sse My_GNS3_Server \
+  http://host:3080/v3/mcp/transport/sse \
+  -H "Authorization: Bearer <jwt>"
+```
+
+### Claude Desktop
+```json
+{
+  "mcpServers": {
+    "My_GNS3_Server": {
+      "url": "http://host:3080/v3/mcp/transport/sse?token=<jwt>"
+    }
+  }
+}
+```

.claude/memory/mcp-tool-description-guide.md

@@ -0,0 +1,43 @@
+---
+name: mcp-tool-description-location
+description: Where to define MCP tool descriptions so AI can see them
+metadata:
+  type: reference
+---
+
+# MCP Tool Description Location
+
+## Key Point
+MCP tool descriptions are defined in `@mcp.tool()` decorator functions in `__init__.py`, NOT in the `*_TOOLS` arrays in individual module files.
+
+## Correct Location
+**File**: `gns3server/api/routes/mcp/__init__.py`
+
+**Example**:
+```python
+@mcp.tool()
+async def update_link(
+    project_id: Annotated[str, Field(description="UUID of the project")],
+    link_id: Annotated[str, Field(description="UUID of the link to update")],
+    **kwargs: Any,
+) -> list[dict[str, Any]]:
+    """Update a link's properties.
+    
+    Put detailed descriptions here, especially for complex parameters.
+    Include format requirements, ranges, and examples.
+    """
+    # implementation
+```
+
+## Wrong Location
+- ❌ `LINK_TOOLS` in `gns3server/api/routes/mcp/links.py`
+- ❌ `TEMPLATE_TOOLS` in `gns3server/api/routes/mcp/templates.py`
+
+## Activation
+**Must restart GNS3 server** for description updates to take effect.
+
+## Description Requirements
+- Be explicit about data formats (arrays vs single values)
+- Include parameter ranges and constraints
+- Provide usage examples
+- Prevent common errors in the description itself

.claude/memory/python-import-validation.md

@@ -0,0 +1,30 @@
+# Python Import Validation
+
+## Background
+
+When checking if modified Python code is correct, `py_compile` only validates syntax (e.g., balanced parentheses, valid keywords). It does **not** catch missing imports or other runtime errors (e.g., using `UUID()` without importing `UUID`).
+
+## Decision/Implementation
+
+Use actual module imports to verify code correctness:
+
+```bash
+# ✅ This catches missing imports and runtime errors
+venv/bin/python -c "
+from gns3server.api.routes.controller.dependencies.authentication import get_user_from_token
+from gns3server.api.routes.mcp.__init__ import _resolve_token
+print('All imports OK')
+"
+
+# ❌ This only checks syntax, not references
+venv/bin/python -c "import py_compile; py_compile.compile('file.py', doraise=True)"
+```
+
+## Related Files
+
+`gns3server/api/routes/controller/dependencies/authentication.py` — missed `from uuid import UUID`
+`gns3server/api/routes/mcp/__init__.py` — missed `from uuid import UUID`
+
+## Why
+
+A `NameError` at runtime is far more expensive than a failed import check. Real import testing catches the full dependency chain.

.claude/memory/rbac-user-isolation-design.md

@@ -0,0 +1,231 @@
+---
+name: rbac-user-isolation-design
+description: GNS3 RBAC user isolation design and implementation thought process
+metadata:
+  type: project
+---
+
+## RBAC User Isolation Design Summary
+
+### Core Problem
+GNS3 3.0 has a complete RBAC framework (ACE + Role + Privilege), but lacks user isolation implementation, causing users to see resources they shouldn't have access to.
+
+### Design Conflict
+Traditional RBAC's **path permission model** fundamentally conflicts with **user data isolation**:
+- **Path permission model**: Controls which paths users can access (e.g., `/projects`)
+- **User data isolation**: Controls which specific resources users can access (e.g., alice's project vs bob's project)
+
+### Final Implementation Approach
+
+#### Three-Step Permission Check Logic
+
+```python
+# Step 1: Batch ACE + resource pool check (3 DB queries regardless of project count)
+direct_ace_ids, pool_accessible_ids = await rbac_repo.get_accessible_project_ids(
+    current_user.user_id, "Project.Audit", all_project_ids
+)
+
+# Step 2: Filter direct ACE projects by created_by (user's own projects)
+# Direct project sharing is only available through resource pools
+for p in controller.projects.values():
+    if p.id in direct_ace_ids and p.created_by == current_user.username:
+        projects.append(p.asdict())
+
+# Step 3: Resource pool projects (no created_by filter)
+for p in controller.projects.values():
+    if p.id in pool_accessible_ids:
+        projects.append(p.asdict())
+```
+
+##### Super Admin Bypass
+```python
+if current_user.is_superadmin:
+    return [p.asdict() for p in controller.projects.values()]
+```
+Super admins skip all three steps and see every project.
+
+##### seen_project_ids Deduplication
+A simple `seen_project_ids` set prevents the same project from appearing twice when it exists in both direct ACE and pool results. This is a lightweight dedup, not the complex blocking mechanism from earlier rejected designs.
+
+### Key Design Decisions
+
+#### 1. ACE vs created_by Relationship
+- **ACE for basic access control**: Whether user can access the system
+- **created_by for user isolation**: Which specific resources user can access
+- **Step 2 filtering is critical**: Even with broad ACE, created_by filtering ensures user isolation
+
+#### 2. Project Sharing Mechanism
+- **Project sharing only through resource pools**: Cannot configure ACE directly for specific projects
+- **Avoids complexity of direct ACE sharing**: Prevents permission configuration chaos
+
+#### 3. Broad ACE Fault Tolerance
+```
+Even with configuration: ACE: Users group + User role + "/" + propagate: True
+Result: Users still only see projects they created
+Reason: Step 2 created_by filtering removes other users' projects
+```
+
+### RbacRepository.get_accessible_project_ids()
+
+The core batch-check method in `gns3server/db/repositories/rbac.py` uses 3 DB queries:
+
+1. **User ACEs**: Direct ACE entries matching user + privilege
+2. **Group ACEs**: Group-level ACE entries via `UserGroup` membership
+3. **All resources with pool memberships**: Preloads all resources and their pool relationships
+
+Then it computes two sets:
+- **`direct_ace_ids`**: Project paths matching user or group ACEs (path-based check)
+- **`pool_accessible_ids`**: Projects in pools the user/group can access (pool-based check)
+
+Pool IDs are precomputed into a `pool_id -> set(project_ids)` map for O(1) lookup.
+
+### Problems Solved
+
+#### Problem 1: Missing User Isolation
+- **Issue**: All users can see all projects
+- **Solution**: Filter by created_by to implement user isolation
+
+#### Problem 2: Broad ACE Breaking Isolation
+- **Issue**: `path: "/" + propagate: true` breaks user isolation
+- **Solution**: Step 2 created_by filtering ensures user isolation even with broad ACE
+
+#### Problem 3: Permission Check Order Conflicts
+- **Issue**: seen mechanism blocks subsequent checks (from earlier design phases)
+- **Solution**: Simple pipeline-style filtering with lightweight dedup set
+
+### Technical Details
+
+#### API Layer Permission Check
+```python
+@router.get("/projects")  # Note: no has_privilege decorator
+async def get_projects(current_user=..., rbac_repo=...):
+    # Permission checks in business logic
+```
+
+#### Duplicate Prevention
+- Simple `seen_project_ids` set for deduplication between direct ACE and pool results
+- Not the complex blocking mechanism from earlier phases
+
+#### Performance Considerations
+- Super admin path: O(1) — returns all projects directly
+- Regular user path: 3 fixed DB queries regardless of project count
+- Path-based ACE check: O(n * m) in worst case, where n = projects, m = ACE entries
+- Pool lookup: O(1) via precomputed pool->project map
+
+### Use Cases
+
+#### Scenario 1: Personal Use
+```
+alice creates project → alice only sees alice's projects ✅
+bob creates project → bob only sees bob's projects ✅
+No extra configuration needed, automatic user isolation
+```
+
+#### Scenario 2: Team Collaboration
+```
+Admin creates resource pool → adds projects → team members can access
+alice creates project → alice still sees her own projects ✅
+Team sharing + user isolation coexist
+```
+
+#### Scenario 3: Broad ACE Configuration
+```
+ACE: Users group + "/" + propagate: True
+alice still only sees alice's projects ✅
+User isolation unaffected by ACE configuration
+```
+
+### Design Principles
+
+#### 1. Separation of Concerns
+- **Basic access permission**: Controlled by ACE
+- **Data ownership**: Controlled by created_by
+- **Team sharing**: Controlled by resource pools
+
+#### 2. Defensive Design
+- User isolation remains effective even with improper ACE configuration
+- Secure by default: users only see their own resources
+
+#### 3. Simplicity
+- Avoid complex seen mechanisms and mutual exclusion logic
+- Clear pipeline-style check order
+
+### Relationship with Original ACE System
+
+#### Preserved Components
+- ✅ ACE framework (permission check mechanism)
+- ✅ Role and privilege definitions
+- ✅ Resource pool functionality
+
+#### Improved Components
+- ✅ Added user isolation (created_by filtering)
+- ✅ Clarified project sharing mechanism (only through resource pools)
+- ✅ Simplified permission check logic
+
+#### Removed Components
+- ❌ Removed `/projects` path privilege check on `get_projects` route
+- ❌ Removed the old complex `seen_project_ids` blocking mechanism
+- ❌ Avoided "can see all non-pool projects" privilege leak
+
+### Implementation Details
+- **Main modification**: `gns3server/api/routes/controller/projects.py`
+- **Function**: `get_projects()`
+- **Batch check method**: `gns3server/db/repositories/rbac.py::RbacRepository.get_accessible_project_ids()`
+- **Privilege dependency**: `gns3server/api/routes/controller/dependencies/rbac.py::has_privilege()`
+- **Branch**: `feature/simple-user-isolation`
+- **Base branch**: `master`
+
+### Key Commits
+1. Implemented basic created_by filtering
+2. Implemented three-layer permission check (with logic issues)
+3. Fixed to correct three-step check logic
+
+### Design Evolution Process
+
+#### Phase 1: Simple created_by Filtering
+```python
+user_projects = [p for p in all_projects() if p.created_by == user.username]
+```
+**Issue**: Didn't integrate with ACE system
+
+#### Phase 2: Three-Layer Check (Wrong Version)
+```python
+# Used complex seen_project_ids blocking mechanism
+# Issue: Broad ACE breaks user isolation
+```
+
+#### Phase 3: Three-Step Check (Correct Version)
+```python
+# Step 1: Batch ACE check via get_accessible_project_ids()
+# Step 2: Filter direct_ace_ids by created_by
+# Step 3: Resource pool projects (no created_by filter)
+```
+**Solution**: User isolation works even with broad ACE
+
+### Relationship with RBAC Roadmap
+This implementation addresses items mentioned in the roadmap:
+- **Phase 1 (MVP)**: Basic project isolation implementation
+- **Auto-ACE on create**: Still needs to be implemented separately
+- **Template isolation**: Can use same design pattern
+
+### Unsolved Issues
+
+1. **Auto-ACE on project creation**: Part of roadmap Phase 1 — `create_project()` sets `created_by` but doesn't create ACE entries
+2. **Template and image isolation**: Can apply same design pattern
+3. **Default ACE configuration**: Need reasonable default permissions for Users group
+
+### Design Limitations
+
+1. **Project sharing only through resource pools**: No direct ACE configuration for sharing
+2. **ACE configuration required**: Users need basic ACE to access system
+3. **Performance considerations**: ACE check queries database for each project path
+
+### Future Improvement Directions
+
+1. **Auto-create ACE**: Automatically add ACE for creator when creating projects
+2. **Default ACE strategy**: Configure reasonable default permissions for Users group
+3. **Performance optimization**: Cache ACE check results to reduce database queries
+
+This design achieves effective user isolation while maintaining RBAC system integrity, and solves the problem of broad ACE configurations breaking isolation.
+
+**Key insight**: The Step 2 created_by filtering is the critical innovation that allows ACE and user isolation to coexist properly.

.claude/memory/web-wireshark-jwt-token-flow.md

@@ -0,0 +1,53 @@
+# Web Wireshark JWT Token Flow
+
+## Background
+
+Question: What is the purpose of `jwt_token` parameter in UDPLink and how is it transmitted?
+
+## JWT Token Complete Flow
+
+1. **User initiates request** → HTTP request with `Authorization: Bearer <jwt_token>`
+
+2. **API layer extracts token** → `gns3server/api/routes/controller/links.py`:
+   ```python
+   auth_header = http_request.headers.get("Authorization", "")
+   jwt_token = auth_header.replace("Bearer ", "") if auth_header else None
+   ```
+
+3. **Pass to Link layer** → `Link.start_capture(wireshark=True, jwt_token=xxx)`
+
+4. **UDPLink forwards** → `UDPLink.start_capture()` calls `super().start_capture(jwt_token=jwt_token)`
+
+5. **Start Web Wireshark container** → `Link._start_web_wireshark(jwt_token)` calls management script
+
+6. **Container uses token** → `manage_wireshark.py` executes inside container:
+   ```bash
+   curl -N -H 'Authorization: Bearer {jwt_token}' \
+     'http://controller:3080/v3/projects/{project_id}/links/{link_id}/capture/stream' | \
+     wireshark -i - -k -display :{display}
+   ```
+
+## Why More Verbose Than gns3-copilot?
+
+**gns3-copilot approach**:
+- All code within the same process
+- Uses `contextvars` to store and retrieve token
+- Downstream code directly calls `get_current_jwt_token()`, no need to pass through layers
+
+**Web Wireshark approach**:
+- Token needs to be passed across processes (management script is separate process)
+- Token needs to be passed across containers (Docker container isolation)
+- Cannot use `contextvars`, must pass through command line arguments
+
+## Conclusion
+
+UDPLink does not use this token, it only forwards it to the parent class. Ultimately used by the curl command inside the Web Wireshark container to authenticate with the GNS3 controller's capture stream API.
+
+Token flow: **Client → GNS3 API → Link → UDPLink → Web Wireshark container → GNS3 capture stream API**
+
+## Related Files
+
+- `gns3server/api/routes/controller/links.py:114-115` - JWT token extraction
+- `gns3server/controller/link.py:321-360` - Web Wireshark startup logic
+- `gns3server/controller/udp_link.py:178` - UDPLink start_capture signature
+- `gns3server/agent/web_wireshark/manage_wireshark.py:527-529` - Container curl command with JWT

.claude/memory/xpra-html5-client.md

@@ -0,0 +1,148 @@
+# Xpra HTML5 Client Configuration
+
+## Overview
+
+Web Wireshark integration uses xpra's built-in HTML5 client to provide browser-based packet capture viewing. The xpra HTML5 client is located at `/usr/share/xpra/www` in the container.
+
+## Configuration Methods
+
+### 1. URL Parameters (Per-Session)
+
+Control toolbar menu items via URL query parameters (default: true):
+
+| Parameter | Menu Item | Description |
+|-----------|-----------|-------------|
+| xpramenu | Xpra Menu | Main menu (Server, Information submenus) |
+| open_windows | Open Windows | List of open windows |
+| fullscreen_button | Fullscreen | Fullscreen toggle button |
+| keyboard_button | Keyboard | Keyboard layout/shortcuts |
+| clipboard_button | Clipboard Copy | Clipboard copy functionality |
+| sound_button | Audio | Audio toggle |
+| cursor_lock_button | Lock Cursor | Game cursor lock mode |
+
+```bash
+# Examples
+?fullscreen_button=false&sound_button=false
+?xpramenu=false&keyboard_button=false&clipboard_button=false&sound_button=false&cursor_lock_button=false
+```
+
+### 2. default-settings.txt (Recommended - Global/Persistent)
+
+Modify `html5/default-settings.txt` (INI format) for all users.
+
+**Features:**
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| keyboard | auto-detect | Enable keyboard input |
+| keyboard_layout | us | Keyboard layout |
+| clipboard | yes | Clipboard sharing |
+| printing | yes | Printer forwarding |
+| file_transfer | yes | File transfer |
+| swap_keys | MacOS yes | Swap Command/Control keys |
+| scroll_reverse_x | no | Reverse mouse X-axis |
+| floating_menu | yes | Show floating menu |
+| toolbar_position | top-left | Toolbar position |
+| autohide | no | Auto-hide toolbar |
+| sound | yes | Audio forwarding |
+| video | 64-bit yes | Video decoding |
+
+**Connection Options:**
+
+| Parameter | Description |
+|-----------|-------------|
+| server | Server address |
+| port | Port number |
+| username | Username |
+| password | Password |
+| ssl | Enable SSL |
+| encryption | Encryption type (AES-CBC/CTR/CFB) |
+| key | AES encryption key |
+| sharing | Allow session sharing |
+| steal | Steal session |
+| reconnect | Auto-reconnect |
+| bandwidth_limit | Bandwidth limit (bits/s) |
+| override_width | Client desktop width |
+
+**Advanced Options:**
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| audio_codec | auto-detect | Audio codec |
+| encoding | auto | Image encoding (png/jpeg/webp/etc) |
+| remote_logging | yes | Send logs to server |
+| action | connect | Connection mode (start/shadow) |
+| submit | yes | Show diagnostics on disconnect |
+
+### 3. default_settings in Code
+
+Set directly in `<script>` tag in index.html:
+```javascript
+const default_settings = {};
+default_settings["xpramenu"] = false;
+```
+
+### Priority Order
+
+URL parameter > default_settings object > default-settings.txt > code default value
+
+## Server-Controlled Submenu Items
+
+The **Server submenu** items are controlled by server hello message:
+
+| Menu Item ID | Content | Control Source |
+|--------------|---------|----------------|
+| clock_menu_entry | Clock | server-time in hello |
+| upload_menu_entry | Upload file | file-transfer or file.enabled |
+| download_menu_entry | Download file | file-transfer or file.enabled |
+| shutdown_menu_entry | Shutdown Server | client-shutdown in hello |
+
+**Information submenu** (About Xpra, Session Info, Bug Report) and fixed items (Reload, Disconnect) are always displayed.
+
+To hide "Shutdown Server", set environment variable before starting xpra:
+```bash
+export XPRA_CLIENT_CAN_SHUTDOWN=false
+xpra start :{display} ...
+```
+Code: `xpra/server/base.py:40` - `CLIENT_CAN_SHUTDOWN = envbool("XPRA_CLIENT_CAN_SHUTDOWN", True)`
+
+## Customizing Background Image
+
+Background image is defined in `html5/css/client.css`:
+```css
+body {
+    margin: 0;
+    padding: 0;
+    overflow: hidden;
+    background-color: #021d3a;
+    background-image: url(../background.jpg);
+    background-position: center center;
+    background-repeat: no-repeat;
+    background-size: cover;
+}
+```
+
+### Methods
+
+1. **Replace image file**: Create/replace `html5/background.jpg`
+2. **Modify CSS**: Change `html5/css/client.css` line 9:
+   ```css
+   background-image: url(../your-image.jpg);
+   ```
+
+### Notes
+- Supported formats: jpg, png, svg, etc.
+- Recommended resolution: 1920x1080 or higher
+- `background-size: cover` auto-stretches to fill
+
+### Temporary Modification (via URL)
+
+Cannot modify background via URL directly, but can use browser DevTools:
+```css
+body { background-image: url(your-image-url); }
+```
+
+## Related Files
+
+- Container Dockerfile: `gns3server/agent/web_wireshark/docker/Dockerfile`
+- Container HTML5 client path: `/usr/share/xpra/www`

.claude/skills/gns3-api-testing/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: gns3-api-testing
+description: Use this skill when testing GNS3 server REST API endpoints with curl — covers JWT auth, common patterns, and marker/link examples.
+version: 1.0.0
+---
+
+# GNS3 Server API Testing with curl
+
+## Core Principle
+
+Fixed routine for testing the GNS3 server API: **get a JWT token first, then send `Authorization: Bearer <token>` with every request.**
+Default address `http://127.0.0.1:3080`, API prefix `/v3`.
+
+---
+
+## Authentication (always first)
+
+```bash
+TOKEN=$(curl -s -X POST http://127.0.0.1:3080/v3/access/users/authenticate \
+  -H "Content-Type: application/json" \
+  -d '{"username":"admin","password":"admin"}' \
+  | python3 -c "import sys,json; print(json.load(sys.stdin)['access_token'])")
+```
+
+Persist to a file for reuse (avoids re-logging in each time):
+
+```bash
+echo "$TOKEN" > /tmp/gns3_token.txt
+TOKEN=$(cat /tmp/gns3_token.txt)
+```
+
+Then attach to every request:
+```bash
+AUTH="Authorization: Bearer $TOKEN"
+curl -s -H "$AUTH" http://127.0.0.1:3080/v3/...
+```
+
+> **Endpoint note**: login is `/v3/access/users/authenticate`, **not** `/v3/auth/login`.
+> OpenAPI spec is at `/openapi.json` (not `/v3/openapi.json`).
+
+---
+
+## Common Variables
+
+```bash
+BASE="http://127.0.0.1:3080/v3"
+PID=<project_id>
+LID=<link_id>
+NID=<node_id>
+AUTH="Authorization: Bearer $TOKEN"
+```
+
+---
+
+## Generic Request Patterns
+
+### GET (query)
+```bash
+curl -s -H "$AUTH" $BASE/projects/$PID/links | python3 -m json.tool
+```
+
+### POST (create) — with JSON body
+```bash
+curl -s -X POST -H "$AUTH" -H "Content-Type: application/json" \
+  -d '{"name":"foo","bpf":"icmp"}' \
+  $BASE/projects/$PID/links/$LID/markers
+```
+
+### HTTP status code only (body not needed)
+```bash
+curl -s -o /dev/null -w "HTTP %{http_code}\n" -X DELETE -H "$AUTH" \
+  $BASE/projects/$PID/links/$LID/markers/global-icmp
+```
+
+### Extract a field from the response
+```bash
+LID=$(curl -s -H "$AUTH" -X POST ... | python3 -c "import sys,json; print(json.load(sys.stdin)['link_id'])")
+```
+
+---
+
+## Status Code Reference
+
+| Code | Meaning |
+|---|---|
+| 200 | GET/PUT succeeded |
+| 201 | POST created |
+| 204 | DELETE succeeded (no body) |
+| 401 | Not authenticated (token missing/expired) |
+| 404 | Resource not found |
+| 409 | Conflict (e.g. per-link edit of an inherited marker) |
+| 422 | Schema validation failed (e.g. marker name starting with `global`) |
+
+---
+
+## Marker Cheat Sheet
+
+### Project-level global marker definitions (inheritance)
+```bash
+# Create a def → fans out to every link automatically
+curl -s -X POST -H "$AUTH" -H "Content-Type: application/json" \
+  -d '{"name":"icmp","bpf":"icmp","tag":1,"color":"#ff5722"}' \
+  $BASE/projects/$PID/marker-definitions
+
+# List all defs + the link_ids each is bound to
+curl -s -H "$AUTH" $BASE/projects/$PID/marker-definitions
+
+# Update a def → syncs to every link
+curl -s -X PUT -H "$AUTH" -H "Content-Type: application/json" \
+  -d '{"bpf":"icmp","tag":99}' \
+  $BASE/projects/$PID/marker-definitions/icmp
+
+# Delete a def → removes the inherited marker from every link
+curl -s -X DELETE -H "$AUTH" $BASE/projects/$PID/marker-definitions/icmp
+```
+
+### Per-link markers
+```bash
+# List markers on a link
+curl -s -H "$AUTH" $BASE/projects/$PID/links/$LID/markers
+
+# Create a private marker (name cannot start with "global")
+curl -s -X POST -H "$AUTH" -H "Content-Type: application/json" \
+  -d '{"bpf":"tcp port 80"}' \
+  $BASE/projects/$PID/links/$LID/markers
+
+# Delete (inherited markers return 409)
+curl -s -X DELETE -H "$AUTH" $BASE/projects/$PID/links/$LID/markers/<name>
+```
+
+### Project-level aggregation query
+```bash
+curl -s -H "$AUTH" $BASE/projects/$PID/markers   # all markers across links, flattened
+```
+
+---
+
+## Link / Node Cheat Sheet
+
+```bash
+# List all links in a project (includes the markers field)
+curl -s -H "$AUTH" $BASE/projects/$PID/links
+
+# List nodes (check ports[].link_id to find free ports)
+curl -s -H "$AUTH" $BASE/projects/$PID/nodes
+
+# Create a VPCS
+curl -s -X POST -H "$AUTH" -H "Content-Type: application/json" \
+  -d '{"name":"t1","node_type":"vpcs","compute_id":"local"}' \
+  $BASE/projects/$PID/nodes
+
+# Start a node
+curl -s -o /dev/null -X POST -H "$AUTH" $BASE/projects/$PID/nodes/$NID/start
+
+# Create a link (both ends: node + adapter/port)
+curl -s -X POST -H "$AUTH" -H "Content-Type: application/json" \
+  -d "{\"nodes\":[{\"node_id\":\"$N1\",\"adapter_number\":0,\"port_number\":0},{\"node_id\":\"$N2\",\"adapter_number\":0,\"port_number\":0}]}" \
+  $BASE/projects/$PID/links
+```
+
+> **Port occupancy**: VPCS has only one interface (port 0); once linked it cannot connect again.
+> Confirm `ports[].link_id` is empty before creating a link; `"Port is already used"` means the port is taken.
+
+---
+
+## Gotchas
+
+- **`POST /links` response may show `markers: []`** — the create response is serialized before the inheritance hook runs.
+  The inherited marker is actually applied; check `GET /links/{lid}/markers` or refresh `GET /links` to see it.
+- **Restart gns3server after code changes** — the Python process does not hot-reload.
+- **Wrap JSON bodies in single quotes** in the shell (double quotes inside); to interpolate a shell variable use `\"$VAR\"`.
+- **Pipe long output through `python3 -m json.tool`** to pretty-print; extract fields with `python3 -c "import sys,json; ..."`.

.claude/skills/gns3-documentation/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: documentation
+description: Use this skill when creating or updating technical documentation under docs/ directory for GNS3 server
+version: 3.0.0
+---
+
+# GNS3 Server Technical Documentation Standard
+
+## Core Principle
+
+Documentation answers: **What is this, how does it work at a high level.**
+
+Code details are left to the codebase — readers can use AI to find implementation specifics.
+
+---
+
+## Document Structure
+
+```markdown
+# Feature Name
+
+## Overview
+[What it does, in 2-3 sentences]
+
+## Architecture
+[Mermaid diagram: components and their relationships]
+
+## Business Process
+[Mermaid sequence/flowchart: key flows]
+
+## API Endpoints
+[Table: Method | Path | Description | Privilege]
+
+## Notes
+[Known limitations, performance data, security — only when relevant]
+```
+
+---
+
+## What to Include
+
+- Mermaid diagrams for architecture and flow (GitHub renders natively)
+  - `graph` for component relationships
+  - `sequenceDiagram` for request/response flows
+  - `flowchart` for data processing steps
+- API endpoint tables
+- Request/response JSON examples (for interfaces)
+- Performance data (only measured numbers, no estimates)
+
+## What to Skip
+
+- Code snippets — let readers search the codebase
+- Verbose prose — use diagrams and tables
+- Implementation details — link file paths instead of pasting code

.claude/skills/memory/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: memory
+description: This skill should be used when the user asks to "record memory", "save to memory", "remember this", "create a memory", "add to memory", or discusses documenting technical decisions, architectural choices, or important case studies for the project. Use this skill to record project knowledge to the .claude/memory/ directory.
+version: 1.0.0
+---
+
+# Memory Skill
+
+## Overview
+
+Record project-related technical decisions, important case studies, and lessons learned to the project memory directory, ensuring critical knowledge is managed with the code repository.
+
+## When This Skill Activates
+
+Activate this skill when user requests involve:
+- "Record to memory", "save to memory", "add to memory"
+- "Remember this", "create a memory"
+- Documenting technical decisions, architectural choices
+- Recording problem solutions and lessons learned
+- Discussing API design, performance optimization, security implementations
+
+## Memory Location
+
+Project memory is stored in: `.claude/memory/`
+
+## Memory Structure
+
+```
+.claude/
+├── memory/
+│   ├── MEMORY.md          # Main index file
+│   └── <topic>.md         # Detailed records for specific topics
+└── skills/
+    └── memory/
+        └── SKILL.md       # This file
+```
+
+## What to Record
+
+### ✅ Should Record
+
+- Important architectural decisions and rationale
+- Solutions to complex problems
+- Key considerations for API design
+- Performance optimization experiences
+- Security-related implementation details
+- Integration approaches with other systems
+- Common errors and solutions
+- Design changes based on user feedback
+
+### ❌ Should Not Record
+
+- Temporary debugging information
+- Session-specific state
+- Obvious code implementation details (code is documentation)
+- Content already documented elsewhere
+
+## Memory Template
+
+```markdown
+# <Topic Title>
+
+## Background
+<Why this record exists>
+
+## Decision/Implementation
+<What was done or how it was implemented>
+
+## Rationale
+<Why this approach was chosen, what alternatives were considered>
+
+## Related Files
+<Code files involved, use file_path:line_number format>
+
+## Examples
+<If there are code examples or other examples>
+```
+
+## Recording Process
+
+1. **Identify content to record**
+2. **Determine topic title** (concise, descriptive)
+3. **Create record using template**
+4. **Update MEMORY.md index**
+5. **Save to .claude/memory/<topic>.md**
+
+## Examples
+
+- `web-wireshark-jwt-token-flow.md` - JWT token flow in Web Wireshark integration
+- `docker-api-version-detection.md` - Docker API version dynamic detection implementation
+
+## Best Practices
+
+- Use clear, descriptive filenames
+- Include references to related code files (with line numbers)
+- Document "why" not just "what"
+- Keep records updated, remove outdated ones
+- Link to related memory files

.dockerignore

@@ -0,0 +1,57 @@
+# Version control
+.git
+.gitignore
+.gitattributes
+
+# CI / GitHub / Docker
+.github
+.whitesource
+.dockerignore
+
+# Editor / IDE
+.idea
+.vscode
+.settings
+.project
+.pydevproject
+.mr.developer.cfg
+
+# Claude
+.claude
+
+# Python build artifacts
+__pycache__
+*.py[cod]
+*.so
+*.egg
+*.egg-info
+build/
+dist/
+eggs/
+parts/
+var/
+sdist/
+develop-eggs/
+.installed.cfg
+lib/
+lib64/
+.ropeproject
+
+# Test & coverage
+tests/
+pytest.ini
+.coveragerc
+.coverage
+.coverage*
+.tox
+.cache
+.pytest_cache
+nosetests.xml
+
+# Virtualenv
+env/
+venv/
+.venv/
+
+# Editor backup files
+*~

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,40 @@
+name: Bug report
+description: Report a bug so we can fix it.
+title: "[Bug]: "
+labels: ["bug"]
+body:
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: A clear description of the bug.
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to reproduce
+      description: How can we reproduce this? Numbered steps if possible.
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      description: What did you expect to happen instead?
+  - type: input
+    id: version
+    attributes:
+      label: Version / commit
+      description: Which version or commit hash are you on?
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: OS, runtime version, anything else that might be relevant.
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant logs
+      description: Paste any relevant log output. This is automatically rendered as code.
+      render: shell

.github/workflows/add-new-issues-to-project.yml

@@ -10,7 +10,7 @@ jobs:
     name: Add issue to project
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/add-to-project@v1.0.1
+      - uses: actions/add-to-project@v2
         with:
           project-url: https://github.com/orgs/GNS3/projects/3
           github-token: ${{ secrets.ADD_NEW_ISSUES_TO_PROJECT }}

.github/workflows/codeql-analysis.yml

@@ -56,11 +56,11 @@ jobs:
         # your codebase is analyzed, see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages
     steps:
     - name: Checkout repository
-      uses: actions/checkout@v4
+      uses: actions/checkout@v7
 
     # Initializes the CodeQL tools for scanning.
     - name: Initialize CodeQL
-      uses: github/codeql-action/init@v3
+      uses: github/codeql-action/init@v4
       with:
         languages: ${{ matrix.language }}
         build-mode: ${{ matrix.build-mode }}
@@ -88,6 +88,6 @@ jobs:
         exit 1
 
     - name: Perform CodeQL Analysis
-      uses: github/codeql-action/analyze@v3
+      uses: github/codeql-action/analyze@v4
       with:
         category: "/language:${{matrix.language}}"

.github/workflows/docker-build.yml

@@ -0,0 +1,68 @@
+name: Build and Push Docker Image
+
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      - v2.*
+      - v3.*
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    env:
+      DOCKERHUB_ORG: ${{ vars.DOCKERHUB_ORG || 'gns3' }}
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v7
+
+    - name: Check for stable release
+      id: ver
+      run: |
+        TAG="${GITHUB_REF_NAME#v}"
+        echo "tag=$TAG" >> $GITHUB_OUTPUT
+        if echo "$TAG" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+$'; then
+          echo "stable=true" >> $GITHUB_OUTPUT
+        else
+          echo "stable=false" >> $GITHUB_OUTPUT
+        fi
+
+    - name: Set lowercase image name vars
+      if: steps.ver.outputs.stable == 'true'
+      id: names
+      run: |
+        echo "owner=$(echo '${{ github.repository_owner }}' | tr '[:upper:]' '[:lower:]')" >> "$GITHUB_OUTPUT"
+        echo "repo=$(echo '${{ github.event.repository.name }}' | tr '[:upper:]' '[:lower:]')" >> "$GITHUB_OUTPUT"
+
+    - name: Set up Docker Buildx
+      if: steps.ver.outputs.stable == 'true'
+      uses: docker/setup-buildx-action@v3
+
+    - name: Login to GitHub Container Registry
+      if: steps.ver.outputs.stable == 'true'
+      uses: docker/login-action@v4
+      with:
+        registry: ghcr.io
+        username: ${{ github.repository_owner }}
+        password: ${{ secrets.GITHUB_TOKEN }}
+
+    - name: Login to Docker Hub
+      if: steps.ver.outputs.stable == 'true'
+      uses: docker/login-action@v4
+      with:
+        registry: docker.io
+        username: ${{ secrets.DOCKERHUB_USERNAME }}
+        password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+    - name: Build and push
+      if: steps.ver.outputs.stable == 'true'
+      uses: docker/build-push-action@v6
+      with:
+        context: .
+        push: true
+        tags: |
+          ${{ env.DOCKERHUB_ORG }}/${{ github.event.repository.name }}:${{ steps.ver.outputs.tag }}
+          ${{ env.DOCKERHUB_ORG }}/${{ github.event.repository.name }}:latest
+          ghcr.io/${{ steps.names.outputs.owner }}/${{ steps.names.outputs.repo }}:${{ steps.ver.outputs.tag }}
+          ghcr.io/${{ steps.names.outputs.owner }}/${{ steps.names.outputs.repo }}:latest

.github/workflows/publish-api-documentation.yml

@@ -12,13 +12,13 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v7
       with:
         fetch-depth: 0
         ref: "gh-pages"
-    - uses: actions/setup-python@v5
+    - uses: actions/setup-python@v6
       with:
-        python-version: 3.8
+        python-version: 3.12
     - name: Merge changes from 3.0 branch
       run: |
         git config user.name github-actions

.github/workflows/testing.yml

@@ -4,45 +4,32 @@ on:
   push:
     branches:
       - master
-      - 3.0
+      - 3.1
   pull_request:
     branches:
       - master
-      - 3.0
+      - 3.1
 
 jobs:
   build:
 
-    runs-on: ${{ matrix.os }}
+    runs-on: ubuntu-latest
 
     strategy:
       matrix:
-        os: ["ubuntu-latest"]
-        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
-        #include:
-          # only test with Python 3.10 on Windows
-        #  - os: windows-latest
-        #    python-version: "3.10"
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v7
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v5
+      uses: actions/setup-python@v6
       with:
         python-version: ${{ matrix.python-version }}
-    - name: Display Python version
-      run: python -c "import sys; print(sys.version)"
+        cache: pip
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        python -m pip install .[dev]
-
-    - name: Install Windows specific dependencies
-      if: runner.os == 'Windows'
-      run: |
-        python -m pip install -r win-requirements.txt
-        curl -O "http://www.win10pcap.org/download/Win10Pcap-v10.2-5002.msi"
-        msiexec /i "Win10Pcap-v10.2-5002.msi" /qn /norestart
+        python -m pip install .[ai-features,dev]
 
     - name: Lint with flake8
       run: |

.gitignore

@@ -67,3 +67,23 @@ env
 venv
 *venv
 .ropeproject
+
+# Claude Code settings (may contain API keys)
+.claude/settings*.json
+.claude/minmax-settings.json
+.claude/zhipu-settings.json
+.claude/settings.local.json
+.claude/deepseek-settings.json
+.claude/claude-settings.json
+.claude/gemini-settings.json
+.claude/grok-settings.json
+!.claude/development.md  # Exception: allow development docs
+!.claude/skills/         # Exception: allow project skills
+!.claude/memory/         # Exception: allow project memory
+# PROJECT_CONTEXT.md  # Commented out: allow tracking project context
+
+# Tiktoken cache files
+gns3server/agent/gns3_copilot/cache/tiktoken/
+
+gns3.log
+/configs/

.whitesource

@@ -2,13 +2,44 @@
   "scanSettings": {
     "configMode": "AUTO",
     "configExternalURL": "",
-    "projectToken" : "",
-    "baseBranches": ["master", "2.2", "3.0"]
+    "projectToken": "",
+    "baseBranches": []
+  },
+  "scanSettingsSAST": {
+    "enableScan": false,
+    "scanPullRequests": false,
+    "incrementalScan": true,
+    "baseBranches": [],
+    "snippetSize": 10
   },
   "checkRunSettings": {
-    "vulnerableCheckRunConclusionLevel": "failure"
+    "vulnerableCheckRunConclusionLevel": "failure",
+    "displayMode": "diff",
+    "useMendCheckNames": true
+  },
+  "checkRunSettingsSAST": {
+    "checkRunConclusionLevel": "failure",
+    "severityThreshold": "high"
   },
   "issueSettings": {
-    "minSeverityLevel": "LOW"
-  }
+    "minSeverityLevel": "LOW",
+    "issueType": "DEPENDENCY"
+  },
+  "issueSettingsSAST": {
+    "minSeverityLevel": "high",
+    "issueType": "repo"
+  },
+  "remediateSettings": {
+    "workflowRules": {
+      "enabled": true
+    }
+  },
+   "imageSettings":{
+       "imageTracing":{
+           "enableImageTracingPR": false,
+           "addRepositoryCoordinate": false,
+           "addDockerfilePath": false,
+           "addMendIdentifier": false
+       }
+   }
 }

CHANGELOG

@@ -1,5 +1,710 @@
 # Change Log
 
+## 3.1.0a5 19/08/2026
+
+* Bundle web-ui v3.1.0a5
+* Sync appliances
+* copilot: sync CONSOLE_TYPES with the server ConsoleType enum
+* feat: Enhance information displayed on the system status dashboard
+* docker: cap GNS3_STOP_TIMEOUT at 210 s (controller stop budget)
+* docker: harden the shm/devices/extra_configs/masking work (code review)
+* docker: make the vendor graceful-stop grace period configurable (GNS3_STOP_TIMEOUT)
+* docker: graceful stop for vendor NOS containers (SIGTERM + 60s grace)
+* fix: UDP port allocation race causing link self-loop (one-way links)
+* add support basic support for OpenBSD.
+* docker: use the container's chown (not busybox) in vendor volume/perms path
+* docker: mask systemd-udevd in privileged containers (GNS3_MASK_UDEV)
+* docker: persist extra_configs in the template DB table
+* docker: inject config files into containers via extra_configs
+* docker: warn about low inotify/file-max and missing FUSE at connect
+* docker: inject /dev/shm size and host devices via HostConfig from env
+* appliance: expose custom_adapters on the v1-6 appliance model
+* appliance: accept docker_exec console type in Docker appliances
+* fix: recreate docker_exec console on reconnect after CLI exit
+* vendor: drop the hardcoded /etc/network mount for SKIP_INIT containers
+* vendor: skip /etc/network in volume bridge and permission passes
+* fix: run _fix_permissions container-side on /gns3volumes mount targets
+* fix: host-side permission fix + SKIP_INIT volume persistence docs
+* refactor: move vendor NOS Docker support into VendorDockerVM subclass
+* docker_exec console: wrap exec command in while-true loop so sr_cli restarts on quit
+* Prototype: vendor NOS Docker node support (SR Linux etc.) — docker_exec console via Docker exec API (pty + hijacked HTTP + NAWS resize)
+* fix: update CI configuration to use a single OS and remove Windows-specific dependencies
+* fix: breaking change with dependency FastAPI v0.137.0 https://fastapi.tiangolo.com/release-notes/#specific-breaking-changes
+* fix: suppress redundant console port setter log during Docker node create
+* revert: restore force_close=True in compute._session()
+* perf: parallelize batch NIO creation across nodes
+* fix: scope marker reconcile to the current bridge/NIO
+* cleanup: remove stray debug print in Dynamips node creation
+* fix: reconcile marker filters in _ubridge_apply_markers (delete/update)
+* log: suppress marker sink stats when no matches received
+* log: add periodic marker.match throughput statistics
+* marker: route marker.match to a dedicated project WS channel
+* perf: raise marker UDP receive buffer from ~208KB to 8MB
+* perf: move project-open marker inheritance to prepare phase
+* perf: parallelise compute-side batch NIO update per node
+* perf: batch update/delete marker-def fan-out too (full project-level)
+* perf: batch marker-def fan-out to one PUT /nios/batch per compute
+* log: add marker fan-out timing for project-open and interactive def-change
+* tune: raise start_all concurrency from 3 to 10
+* revert: drop _connect_nio thread-pool executor, restore async _ubridge_send
+* fix: use socket.fromfd in send_batch_sync for Python 3.13 compat
+* log: demote all per-node lifecycle INFO logs to DEBUG
+* fix: await Dynamips.create_nio (it is async, unlike sync base)
+* fix: use bound-method param count for Dynamips create_nio detection
+* fix: Dynamips create_nio(node, nio_settings) takes extra arg + add tests
+* log: add start/stop/close progress lines; revert start concurrency to 3
+* log: lower per-node lifecycle logs in base_node to DEBUG
+* perf: raise start/stop/suspend/reset-console concurrency from 3
+* fix: race in concurrent node creation sending duplicate POST /projects
+* log: lower per-node docker lifecycle logs to DEBUG
+* log: emit progress lines for node and link loading on project open
+* cleanup: remove project-open stage timing logs, lower NIO-added log to debug
+* perf: skip per-link topology dump during project-open prepare
+* perf: batch NIO dispatch on project open (one HTTP per compute)
+* perf: cache compute.host_ip + add UDPLink.create timing log
+* perf: dedicated 500-worker thread pool for ubridge batch I/O
+* perf: offload per-NIO ubridge commands to thread-pool executor
+* perf: enable TCP keep-alive for local compute HTTP requests
+* debug: add per-command timing to _connect_nio ubridge calls
+* perf: parallelize UDP port allocation and NIO creation in UDPLink.create
+* fix: SIGKILL docker container on stop instead of 5s grace period
+* fix: add event handling for deleted projects
+* fix: tests after merging
+* server: raise the open-files (RLIMIT_NOFILE) limit at startup
+* marker: batch topology dumps in bulk fan-out (per-def on 500+ links was ~1 minute)
+* marker: concurrent (bounded) definition fan-out
+* marker: forward data_link_type on per-link marker create
+* iou: skip already-installed markers in _ubridge_apply_markers (NIO update idempotency)
+* marker: serial-link (WAN) support via data_link_type -> uBridge linktype
+* iou: forward data_link_type on capture start so serial pcaps use the correct linktype
+* ubridge: default the control transport to unix
+* ubridge: require version >= 1.2.0
+* fix: add missing HTTPException import
+* mcp: drop direction from marker_definition tool
+* marker: tighten marker name max length from 128 to 32
+* marker: drop deleted marker from port NIO cache to stop empty pcap on restart
+* marker: validate def BPF once, skip re-validation on inherited fan-out
+* marker: point directional defs at BPF, refresh implementation doc
+* marker: incremental apply, clear bridge map on uBridge stop
+* marker: fine-grained filter ops, clean pcap on remove
+* marker: restore direction on project load, reject tx/rx on definitions
+* schema: accept direction='both' in marker schemas, normalize to None
+* qemu: demote QEMU monitor connect and set_link logs to DEBUG
+* marker: key _marker_filter_bridges by (name, link_id) so multi-link nodes toggle every copy
+* marker: make per-filter toggle fall back to NIO rebuild when the marker isn't installed
+* marker: make per-filter toggle a no-op when the marker isn't installed
+* marker: rework pause/resume from project-wide to per-definition
+* marker: fix PUT marker with an enabled-only body (bpf no longer required)
+* marker: persist project-wide markers_paused to the .gns3 file
+* marker: document pause/resume and instant enabled toggle
+* marker: test enabled/pause/resume and instant toggle
+* marker: drive uBridge enabled/pause/resume in real time
+* marker: add direction-clear, routing, and ubridge transport tests
+* marker: support clearing direction via explicit null / "both"
+* marker: let callers pin the capture node via capture_node_id
+* Name AF_UNIX sockets by node id for self-describing debuggability
+* Detect unsupported -U flag and fail fast with a clear error
+* Add configurable uBridge control channel transport (tcp/unix)
+* fix(import): unvalidated symlink creation in import_project
+* fix(qemu): move the bios options after the network ones
+* fix(qemu): fix addition of QEMU RNG device causes interface names to change
+* bugfix: docker workflow needs lowercase name
+* fix(qemu): remove trailing space from RNG object argument
+* Add MCP tools for traffic-insight marker feature
+* Improve MCP tool descriptions for link_update, device_show_run, and link_reset
+* Do not start nodes when deleting a project
+* fix: correct always-true state check in DockerVM.stop()
+* add bug report issue template
+* Adds controller and compute API support for explicitly pulling or updating Docker images.
+* feat(tests): increase maximum open file descriptors for test runs on Unix
+* (feat): Implement functional Layer 1 keepalive support for IOU/IOL nodes
+* Fix typo with ovmf_firmware_dir
+* Fix issues after merging
+* fix(builtin): hide GNS3 internal bridge interfaces from Cloud node
+* feat(builtin): NAT node returns its interface IP info in asdict()
+* fix(controller): refresh cloud/nat node interfaces from compute on GET
+* refactor(builtin): use deterministic bridge name from switch UUID
+* fix(builtin): bring kernel bridge UP after creation
+* feat: migrate builtin EthernetSwitch from Dynamips ethsw to ubridge brctl
+* fix(mcp): remove unreliable node_reload / node_reload_all tools
+* fix(rbac): guard None current_user on websocket auth failure
+* fix(mcp): thread token_version into console/download token minting
+* fix(mcp): pass user.token_version when generating temp JWT from API key
+* fix(marker): avoid reentrant-lock deadlock when uBridge starts lazily
+* fix(marker): per-link attribution via link field in MARK signals
+* fix(marker): set nio.markers on iou/dynamips/cloud nio update
+* fix(marker): reject reserved global-prefix names only on create
+* fix(marker): clean inherited markers on def delete
+* feat(marker): add highlight_duration render hint
+* fix(marker): fix inheritance hook, topology load, update sync, and asdict
+* fix(marker): export MarkerDefinitionCreate from schemas package
+* fix(marker): replace pydantic lookahead pattern with field_validator
+* feat(marker): add project-level marker definition inheritance
+* fix(marker): reserve "global" name prefix for future marker inheritance
+* fix(marker): extend marker support to dynamips and cloud nodes
+* fix(marker): enable marker support for docker nodes
+* fix(marker): tolerate port conflict on marker listener startup
+* fix(marker): validate marker name and expose enabled via REST
+* fix(marker): uniquify auto-generated marker names per link
+* feat(marker): add project-level marker aggregation endpoint
+* feat(marker): add IOU node marker support via iol_bridge
+* refactor(marker): converge to filter single-path model, remove dual-apply endpoints
+* fix(marker): restore markers from topology on project load
+* feat(marker): add optional color field to marker data model
+* fix(marker): use allowlist in _choose_marker_side, align with _get_filter_node
+* fix(marker): stop auto-deleting markers on node stop in node_updated
+* fix(marker): ride markers on NIO so they survive node restart and project reload
+* config: set marker_listen_port default to 3070 and document in config templates
+* fix(marker): add _choose_marker_side to exclude non-uBridge node types
+* Only set IOU images to be executable when importing images
+* fix(import): project import does not move images symlinks into place
+* Search for system UEFI that is compatible with Python < 3.12
+* UEFI improvements for Qemu VMs * Add OVMF firmware directory configuration * Automatically add a Random Number Generator (RNG) device when using uefi option is enabled
+* fix(docker): handle container name conflict automatically
+* fix: gns3-server crashes on startup if "Open this project in the background" is active but there is a problem with that project
+* Handle HTTPNotFound exception when retrieving compute status
+* Replace ControllerForbiddenError with aiohttp.web.HTTPForbidden for project deletion error handling
+* Fix: Check compute connectivity before open() during project deletion
+* Use typed InterfaceStatus enum and simplify stats fallback in interfaces()
+* Expose full interface address list and link state in cloud node API
+
+## 2.2.61 30/07/2026
+
+* Sync appliances
+* fix(import): unvalidated symlink creation in import_project
+* fix(qemu): fix addition of QEMU RNG device causes interface names to change
+* fix(qemu): remove trailing space from RNG object argument
+* fix: do not start nodes when deleting a project
+* fix: correct always-true state check in DockerVM.stop()
+
+## 2.2.60 15/07/2026
+
+* Sync appliances
+* Only set IOU images to be executable when importing images
+* fix(import): project import does not move images symlinks into place
+* Search for system UEFI that is compatible with Python < 3.12
+* Add OVMF firmware directory configuration
+* Automatically add a Random Number Generator (RNG) device when using uefi option is enabled
+* fix(docker): handle container name conflict automatically
+* fix: gns3-server crashes on startup if "Open this project in the background" is active but there is a problem with that project
+* Handle HTTPNotFound exception when retrieving compute status
+* Fix: Check compute connectivity before open() during project deletion
+* API endpoints to manage base configuration files for templates
+
+## 3.1.0a4 09/07/2026
+
+* Bundle web-ui v3.1.0a4
+* Add jwt_refresh_token_expire_minutes to sample configuration
+* Remove deleted web-ui files from git
+* .dockerignore ignore .dockerignore
+* typo made me reconsider and move out to env
+* defaulted DOCKERHUB_ORG repository variable
+* Remove API docs from 2.2 after merging
+* Update GitHub Actions workflows
+* Fix web-wireshark docker build broken by xpra 6.5 release
+* Update CI to install [ai-features,dev] instead of [ai-copilot,dev]
+* Make AI features (AI Copilot + MCP) optional via [ai-features] extra
+* Add refresh token mechanism documentation under docs/features/
+* Add /refresh to allowed public endpoints list in route auth test
+* Add stateless JWT refresh token mechanism
+* Add project/node/link handler tests: 39 total, covering list/get/create/delete/start/stop/suspend/reload/console/update/fields
+* Add MCP tool parameter consistency tests
+* Fix appliance_install: add version parameter
+* Add coordinate system note to docs
+* Document canvas coordinate system in node_create x/y params
+* Update docstring: batch concurrency from 10 to 100
+* Remove unused import time
+* Add list type check before nodes[0] access in _normalize_link_nodes
+* Add fields type validation in create handlers
+* Use pop() instead of pop(0) for O(1) port removal
+* Fix review issues: key_prefix length, count validation, WAL log, timeout comment, pointless temp var
+* Fix: pass name from TemplateUsage to add_node_from_template
+* Remove unused imports (logging, log, select)
+* Add warning for unconsumed pre-allocated UDP ports after link creation
+* Remove FIXME comment about middleware in server.py
+* Rename device_command_run_handler → device_show_run_handler to match tool name
+* Rename device_command_run → device_show_run for clarity
+* Fix device_command_run KeyError('commands'): tool desc said show_commands but backend expects commands
+* Fix template_list return type annotation to match _run_handler_sync envelope
+* Add performance optimization documentation
+* Update MCP service docs: API key format, auth flow, tool parameters, concurrency
+* Increase HTTP connection pool to 500/1000
+* Increase BATCH_MAX_WORKERS and Pool concurrency from 20 to 100
+* Remove final timing artifact in projects.py
+* Remove remaining dead timing variables and imports
+* Remove database warmup (proven ineffective - real bottleneck was bcrypt blocking event loop)
+* Clean up all timing/debug logs
+* Add memory: import validation best practice
+* Fix: add missing UUID imports
+* Generate fresh JWT on API key auth instead of returning raw key
+* Optimize API key auth: O(1) lookup via UUID-embedded key format
+* Fix: offload bcrypt.checkpw to thread pool to prevent blocking event loop
+* Add timing to API key auth path and log api_keys count
+* Replace SELECT 1 warmup with full database file read to warm OS page cache
+* Add timing logs to auth dependency chain to identify 6s pre-handler delay
+* Add granular timing to get_template: separate execute vs fetch time
+* Warm up database connection pool on startup to avoid 8s cold-start penalty on first API request
+* Fix: register WAL PRAGMA on sync_engine instead of Engine class for async compat
+* Add timing logs to get_template to identify DB query bottleneck
+* Add timing middleware to log slow requests (>1s) with [CTRL-TIMING] prefix
+* Fix: _time → time in compute.py timing log
+* Add [CTRL-TIMING] logs to controller create_node flow
+* Fix: pass template_id to batch mode handler so top-level template_id works as default
+* Add detailed timing logs to MCP node creation and HTTP client
+* Add fields filter to template_list tool with description for AI
+* Fix: add missing _filter_link_response function
+* Pass name parameter through to controller API when creating node from template
+* Add validation to compact link format with clear error messages
+* Add compact array format for link node entries to reduce token usage
+* Add fields filter to link_create tool
+* Reduce md5sum cache write failure log level from error to warning
+* Add fields filter to node_create tool description for AI
+* Optimize MCP create_node: support inherited template_id and default fields filter
+* Increase MCP HTTP client timeout from 10s to 30s
+* Enable SQLite WAL mode to fix 'database is locked' errors under concurrent API requests
+* Cache IOU image default values per image path to avoid redundant subprocess calls
+* Increase node and link creation concurrency from 5 to 20
+* Fix: revert IOU lock optimization, serialize IOU node creation for correct application_id assignment
+* Performance: accelerate project opening with parallel link creation and batch UDP port allocation
+* feat: Add batch link_ids to link_delete/link_reset, fields filter to link_list
+* feat: Add fields filter to link_list
+* feat: Add batch node_ids to node_delete
+* fix: Convert http to ws scheme in node_console WebSocket URL
+* feat: Add batch link_ids to link_capture_download
+* feat: Add batch link_ids to link_capture_start/stop
+* fix: Store username in gns3_ctx during auth, use for short-lived download JWTs
+* fix: Generate independent short-lived JWT for pcap download
+* revert: Remove _configs_map changes in tools_v2 (handled by template renderer now)
+* fix: Merge commands for duplicate device_names in _configs_map
+* fix: Actually pass template param to device_config/command handlers
+* fix: Correct Jinja2 template commands_field per tool type
+* feat: Jinja2 template support in device_command_run
+* feat: Jinja2 template support in device_config_send
+* feat: Add batch node_ids support to node_start/stop/reload/suspend
+* feat: Add fields filter to appliance_list
+* feat: Add fields filter to node_list
+* feat: node_get fields filter — match controller Node schema fields
+* fix: Set auto_close=False on project_create so projects stay open when clients disconnect
+* feat: Add batch mode to node_create and link_create (parallel, max 10 workers)
+* fix: Pass API key directly instead of generating short-lived JWT
+* feat: API key lifecycle — revoke/restore/delete
+* fix: Rename revoke_api_key → delete_api_key
+* fix: Hard-delete API keys instead of soft delete (revoked flag)
+* feat: Support API keys in REST API authentication (reuse gns3_ prefix keys)
+* fix: Lazily access db engine for API key validation
+* fix: Add missing updated_at column to api_keys table
+* fix: Export ApiKeyCreate from schemas package
+* feat: Add API Key support for MCP authentication
+* fix: Validate JWT token exp claim — was silently ignored after migration to joserfc
+* fix: Add image field to template_create, document type-specific params in description
+* fix: Remove .json() calls on 204 responses for prune/install images
+* fix: Skip always-running nodes in start_all/stop_all
+* fix: Add missing rotation parameter to drawing_update MCP tool
+* fix: Map MCP device_command_run parameter to tool's expected field name
+* fix: Update link_reset description to match actual behavior (delete + recreate)
+* fix: Remove unsupported description param from project_create
+* fix: Fix symbol_get/upload/delete handlers for correct API paths
+* feat: Log registered MCP tools at startup
+* fix: Type compute_id as uuid.UUID to reject non-UUID values at MCP input layer
+* fix: Require UUID for compute_get/images, remove 'local' string default
+* feat: Add device configuration MCP tools (config_send, command_run, vpcs_config_set)
+* refactor: unify MCP tool naming to <module>_<action> convention
+* feat: Add symbol upload/delete, project load, and locked check MCP tools
+* feat: Add image management MCP tools
+* feat: Add symbol and appliance MCP tools
+* feat: Add node bulk ops, project lock, and server info MCP tools
+* feat: Add snapshot and drawing MCP tools
+* refactor: unify MCP handlers to use http_call directly, relocate node file ops to Node class
+* feat: Add node file operations as MCP tools (list, get, write, delete)
+* Add comment about rootful Docker permissions at container start
+* Fix _fix_permissions test: set process.returncode=0 and update assertion
+* Fix list_node_files PermissionError on os.scandir
+* Fix _fix_permissions error handling and list_node_files PermissionError
+* Add async_iterable_to_stream utility to avoid aiohttp compatibility issues
+* Add descriptive detail to 403 errors in compute file endpoints
+* Fix silent file write failure in write_compute_project_file
+* feat: Node file streaming, recursive listing, file type detection, and file delete
+* Update README tool descriptions: .txt → .md
+* Update README tool descriptions to mention Markdown format
+* Add MCP project tools: update, duplicate, and README operations
+
+## 3.1.0a3 06/06/2026
+
+* Bundle web-ui v3.1.0a3
+* fix: update MCP link tools descriptions with detailed filter info
+* fix: correct MCP nodes and links tool parameter handling for nested kwargs
+* fix: correct MCP template tool parameter handling for nested kwargs
+* feat: add client information logging to MCP connection rejection
+* refactor: replace MCP ready state polling with asyncio.Event
+* fix: revert duplicate image check to fix failing tests
+* fix (templates): Add ordering to handle the duplicate cases gracefully
+* fix(templates): Database error detected when saving a template with a disk image change
+* fix: return 503 error on MCP server ready timeout
+* fix: add MCP server ready check to prevent initialization errors
+* fix: resolve MCP server URL host via default route IP when bound to 0.0.0.0
+* fix: correct MCP transport security config to actually allow all hosts by default
+* feat: add configurable MCP transport security settings via gns3_server.conf
+* fix: add load_feature_skills() to properly load network planning features
+* refactor: convert all MCP tool parameter descriptions to Annotated+Field
+* fix: remove platformdirs upper bound to resolve fastmcp-slim dependency conflict
+* fix: add missing fastmcp dependency to resolve CI test failures
+* refactor: move all imports to top of __init__.py
+* test: add /v3/mcp/ to allowed public endpoints
+* fix: remove console_host/port from get_node_console_info
+* feat: add get_node_console_info tool
+* feat: add 3 Compute MCP tools - Add list_computes, get_compute, get_compute_images - Total MCP tools: 29
+* feat: add 5 Template MCP tools
+* feat: add Node and Link MCP tools, update copyright - Add 9 node tools and 5 link tools - Update copyright year to 2026, add author
+* feat: complete MCP SSE transport with JWT auth
+* feat: support Authorization header and query param for MCP token
+* feat: implement standard MCP protocol with SSE transport
+* feat: add MCP (Model Context Protocol) service with project tools
+* Add project memory: Docker container stop delay analysis
+* Remove extra blank line from merge
+* Revert container state detection in create()
+* Fix Docker VM tests for container status detection on node creation
+* Add running project check for fast duplication
+* Move running project check before fast duplication
+* Add running project check for fast duplication
+* Fix Docker container status detection on node creation
+* Fix web-ui update script to handle custom GitHub URL changes
+* Fix unnecessary Docker container recreation when renaming a project
+* Fix project rename and duplicate issues
+* Fix double deletion issue in remove_resource_from_pool
+* Complete fix: delete resource records when deleting resource pool
+* Apply fix from PR #2315: delete resource from resource table when removing from pool
+* Remove deprecated 'PermissionsStartOnly' setting for Systemd service. Ref #1830
+* Optimize project loading by implementing parallel node creation
+* Fix delay filter validation: ensure delay: [0, X] returns proper error message
+* Fix packet filter validation tests: use correct ubridge filter type names
+* Update tests to match show_interface_labels default change
+* Set default value of show_interface_labels to True
+* Optimize project variable updates to use parallel node processing
+* Fix ghost Docker nodes causing 60-second VNC timeout on variable updates
+* Fix Docker container variable compatibility with Pydantic models
+* Fix delay latency minimum: ubridge rejects latency <= 0
+* Improve packet filter validation: use tcpdump, handle multi-line BPF, safe project load
+* Add packet filter parameter validation to prevent ubridge errors
+* chore: update GNS3 skills repository to official organization
+* docs: update RBAC user isolation design doc to match actual implementation
+* docs: update skills repo URL in command-security.md
+* docs: remove Chinese overview docs, keep only English versions
+* docs: add overview docs for packet analysis, fault injection, and AI assistant
+* feat: add mermaid-to-SVG conversion script with environment setup
+* test: fix privilege count assertions after adding LLMConfig privileges
+* docs: add user node limit roadmap
+* test: fix RBAC test to match implementation logic
+* test: add --prefix and --cleanup-only parameters to benchmark script
+* perf: batch RBAC permission checking for GET /projects
+* test: add benchmark script for GET /projects performance testing
+* fix: prevent duplicate projects when user projects are in resource pools
+* fix: check both regular ACEs and resource pool ACEs for proper access control
+* test: update RBAC test to use test_user.username for user isolation
+* docs: add Phase 9 and 10 user self-registration and email service
+* docs: add Phase 8 per-user project namespace to roadmap
+* docs: add Phase 7 resource pool renaming to roadmap
+* feat: add alembic migration for LLMConfig privileges
+* feat: add independent LLMConfig permissions for AI profile management
+* docs: add Phase 6 frontend permission query API to roadmap
+* docs: add Phase 5 ACE architecture refactoring plan to roadmap
+* feat: remove resource pools from 'all endpoints' list
+* refactor: add efficient get_aces_for_path method for resource pool checks
+* feat: prevent deletion of resource pools used by ACE configurations
+* docs: update RBAC user isolation roadmap and add design memory
+* feat: fix permission check logic to properly handle ACE and user isolation
+* feat: implement layered permission checks for proper user isolation and sharing
+* feat: implement simple user isolation based on project ownership
+* fix: clean BPF syntax error message and specify loopback interface
+* feat: add BPF syntax validation using tshark
+* feat: add show_filters_icon parameter to packet filter tool
+* docs: add GNS3 appliance loading mechanism to memory
+* feat: add packet filter management tool for GNS3-Copilot fault injection
+* fix: update test_json expected output to include show_filters_icon field
+* fix: add getattr fallback to show_filters_icon property for backward compatibility
+* feat: add show_filters_icon property to Link for controlling Web UI filter icon display
+* fix: ensure show_filters_icon is always returned in API responses
+* feat: add show_filters_icon property to Link for controlling Web UI filter icon display
+* fix: remove explicit paramiko pin to resolve dependency conflict with netmiko
+* fix: update netmiko to 4.7.0 and pin paramiko>=5.0.0 to fix CVE-2026-44405
+* fix: close DockerHTTPClient session to prevent UnixConnector leak in Web Wireshark
+
+
+## 3.1.0a2 12/05/2026
+
+* Bundle web-ui v3.1.0a2
+* fix: surface tshark stderr errors to LLM, not just log them
+* fix: hint LLM about -c behavior when tshark returns empty with -c
+* fix: update search_fields examples to use existing field names
+* fix: reject multi-keyword search_fields, single keyword only
+* fix: document action/query params in PacketAnalysisTool description
+* feat: add search_fields action to PacketAnalysisTool for real-time field lookup
+* feat: validate tshark -e field names before running analysis
+* fix: document -c behavior caveat in PacketAnalysisTool description
+* fix: demote loader-level load logs to DEBUG, info already reported by manager
+* fix: promote skills/prompts load logs to INFO level
+* fix: load packet analysis protocols during skills initialization
+* feat: add PacketAnalysisSkillsTool
+* fix: remove remaining quoted example from tool input docstring
+* fix: use shlex.split for tshark_args parsing
+* feat: add packet analysis workflow to tool description
+* refactor: remove old PacketCaptureTool, replaced by PacketAnalysisTool
+* feat: add protocol-oriented packet analysis tool
+* docs: add roadmap docs for planned features
+* feat: require superadmin for /reload/skills endpoint
+* fix: remove background init timeout and allow skills reload retry
+* deps: add PyYAML and GitPython to ai-requirements.txt
+* feat: add fault injection system and external skills repository
+* fix: Disable DeepSeek thinking mode to avoid reasoning_content errors
+* fix: Skip offline compute nodes during project import
+* fix: Import status module in project.py
+* fix: Handle connection errors when stopping node console
+* refactor: Remove MD5 calculation from node files listing
+* fix: Export NodeFile schema to schemas module
+* feat: Add detailed metadata to node files listing
+* feat: Add API endpoint to list node files
+* Fix snapshot restore does not work after export/import of project
+* Warn to use 64-bit IOU images. Fixes #2716 32-bit IOU image support has been removed from the GNS3 VM.
+* Fix: Improve Docker container deletion error logging
+* Fix: Add exponential backoff to compute reconnection attempts
+* Fix: Check compute connectivity before node creation in open()
+* Fix: Check compute connectivity before open() during project deletion
+* Fix: Add error logging when closing/deleting projects on computes
+* Fix: Skip add_compute for existing computes when opening projects
+* feat: add AI provider config files to .gitignore
+* Fix: Use _computes instead of _project_created_on_compute for deletion check
+* Fix: Check compute connection status before project deletion
+* fix: extend remote compute image path conversion to all node types
+* fix: send relative image path to remote compute nodes
+* fix: handle directory access for static web-ui routes
+* fix: add duplicate name validation when updating templates
+* fix: avoid AttributeError when password is not provided in compute update
+* fix: improve hostname validation error messages with allowed characters
+* feat(compute):  Fix Dynamips to listen on the internal port when ssh is used for auxiliary console
+* feat(compute): Fix ambiguous log message related to the  active console transport.
+* feat(compute): Updated server host key to use the secure ssh-ed25519 instead of old ssh-rsa algorithm
+* feat(compute):  Fix missing SSH wrapping for auxiliary console
+* feat(compute): Added AsyncioSSHServer dedicated tests
+* feat(compute): add SSH console type support
+* fix: include error details in LLM model config failure response
+* Fix telnet console silent-proxy hang on non-ConnectionError exit (#2344)
+
+## 2.2.59 08/05/2026
+
+* Sync appliances
+* Fix snapshot restore does not work after export/import of project
+* Warn to use 64-bit IOU images. Fixes #2716 32-bit IOU image support has been removed from the GNS3 VM.
+* Fix telnet console silent-proxy hang on non-ConnectionError exit (#2344)
+
+## 3.1.0a1 25/04/2026
+
+* New completely revamped Web interface.
+* Add GNS3 Copilot AI agent back-end
+* Web-wireshark: packet capture and live traffic analysis in the browser
+* Fix using SSL with remote computes. Fixes https://github.com/GNS3/gns3-gui/issues/3733
+* Add --url and --branch parameters to update-bundled-web-ui.sh
+* Fix bug when custom_adapters is None in port_factory.py
+* Have optional body in start node API endpoint
+* Fix snapshots after merging
+* Potential fix for pull request finding 'CodeQL / Information exposure through an exception'
+* Refactored the way snapshots are handled in the server
+* fix(symbols): add authentication to symbol raw endpoint
+* fix(symbols): add CORS headers to symbol file responses
+* Allow to find new project in sub dirs
+* Enhancement: Refresh projects list without restarting the GNS3 server
+* Fix accessing username in authentication.py
+* Improved exception handling and telnet client disconnect
+* Use get method for registry_version to avoid KeyError
+* Add support for appliance format version 8
+* Convert database template fields from PickleType to JSON
+* feat(statistics): distinguish open vs closed project nodes
+* fix(statistics): handle closed projects where nodes/links are dicts
+* feat(controller): extend /statistics API with project, node and link stats
+* Use FastAPI Lifespan Events
+* feat(link): add control_offset field to LinkStyle
+* feat(symbols): add DELETE API for removing custom symbol files
+* Enhancement: Re-write current Telnet server implementation using telnetlib3 library
+* feat: improve error handling for API configuration errors
+* Enhancement Added link type support on the server side
+* Ignore HTTPException received when closing a project
+* Prevent router to be duplicated when running and add tests
+* Fixed issue #1605 regarding Cisco slots causing configs to break
+* feat: add VNC WebSocket console support for Docker and QEMU nodes
+* Return 405 error for unsupported actions for other node types
+* feat(telnet_server): improve error handling and connection management
+* fix(telnet): handle connection race condition during broadcast
+* Change first() to one_or_none() for image query
+* Fix for duplicating Qemu nodes
+* Minor optimizations to logic
+* Fixed an issue with the server causing errors when uploading large images + Preparation for a smarter check when uploading images
+* Implemented a smarter node_type system
+* docs: restructure copilot docs and update node tools
+* fix(acl): correct endpoint paths for users, groups, and roles
+* fix(iou): return 405 error for unsupported suspend operation
+* feat(api): enhance max_tokens field with robust null handling
+* feat(docs): add AI prompting guide for configuration templates
+* Deactivate 'use default IOU values' by default and update RAM/NVRAM values
+* Make sure the node shows as stopped when the wrap console cannot be stopped. Ref https://github.com/GNS3/gns3-registry/pull/1010
+* chore: update author name and copyright headers
+* feat(docs): enhance AI chat API documentation with examples and details
+* feat: add .claude directory to gitignore for API key security
+* Revert "Fix QEMU serial console artifacts by filtering ANSI CPR responses in …"
+* docs: add troubleshooting guide for datetime timezone issue
+* Drop support for Python 3.9
+* feat: add multi-user concurrency control design document
+* docs: add troubleshooting guide for force kill residual processes
+* Fixed the path traversal check
+* Fix image handling
+* Qemu VMs: only compute MD5 checksums for existing disks
+* Copy config files and database from a previous version if it exists
+* Add enable_http_auth in gns3_server.conf sample
+* feat(compute): option to disable compute authentication
+* tests(controller,port): short_name finishes successfully when port name is None
+* fix(controller,port): handle None port name to prevent TypeError in short_name method
+* fix(docker): handle container name conflict automatically
+* feat(virtualbox): add fallback for VBoxManage executable detection
+* feat: simplify port name assignment logic
+* feat(ports): add null checks for port name in short name generation
+* Remove unneeded rbac_repo in get_templates
+* Use lists for tags instead of dicts
+* Fix for resizing Qemu VM disks
+* feat(templates): safely access settings dict keys
+* feat(api): fix ETag handling and JSON serialization in template endpoint
+* feat(api): add tag filtering to nodes and templates endpoints
+* Update project schema and fix tests
+* Add 'created_by' field to track project creator
+* Fix updating packet filters
+* Add vendor, model and netmiko_device_type fields to templates
+* fix: handle RuntimeError in notification_manager emit()
+* fix: busybox static link detection on Alpine/musl
+* Fix bug when updating compute password to be empty
+* Cancel tasks if controller cannot be started
+* Enable parallel compression with zstandard. Fixes #2324
+* Add Dynamips to Dockerfile dependencies
+* Take populated disks into consideration when calculating PCI device ID
+* Fix telnet keepalive options on macOS
+
+## 2.2.58.1 12/04/2026
+
+* Sync appliances
+
+## 2.2.58 10/04/2026
+
+* Bundle web-ui v2.2.58
+* Sync appliances
+* Snapshot refactoring
+
+## 2.2.57 23/03/2026
+
+* feat(telnet_server): improve error handling and connection management
+* Deactivate 'use default IOU values' by default and update RAM/NVRAM values
+* Make sure the node shows as stopped when the wrap console cannot be stopped
+* tests(controller,port): short_name finishes successfully when port name is None
+* fix(controller,port): handle None port name to prevent TypeError in short_name method
+* fix: busybox static link detection on Alpine/musl
+* Take populated disks into consideration when calculating PCI device ID
+
+## 2.2.56.1 28/01/2026
+
+* Fix telnet keepalive options on macOS
+* Upgrade dependencies
+* Drop Python 3.8 support
+
+## 3.0.6 28/01/2026
+
+* Sync appliances
+* Fix creating Qemu disk image. Fixes #2542
+* Disable checking for available disk space. Ref #2548
+* Set default location of udhcpc in "/etc/network/udhcpc". Fixes #2582
+* Support for Python 3.14
+* Fix non-ASCII characters in project names
+* Increase DB engine pool size and max overflow
+* Enable ip cef in IOU L2 and IOU L3 base configs
+
+## 2.2.56 21/01/2026
+
+* Set default location of udhcpc in "/etc/network/udhcpc". Fixes #2582
+* Upgrade pywin32 to v311
+
+## 2.2.55 19/11/2025
+
+* Docker API version requirements and process to handle older daemons
+* Use docker_name property when creating a container
+* Set name of container in Docker
+* Support for Python 3.14
+* Enable ip cef in IOU L2 and IOU L3 base configs
+* Only build and push Docker image when releasing a new version
+* Fix pushing Docker image to Docker hub
+* Update security issues in README.md. Fixes #2535
+* Add missing 'nat' template type in schema. Fixes #2529
+* Resolve deprecation warnings of regex library
+
+## 3.0.5 14/05/2025
+
+* Bundle web-ui v3.0.5
+* Sync appliances
+* Use Ubuntu 24.04 LTS in Dockerfile. Ref #2523
+* Fix tests and require Qemu version >= 2.4
+* Fix adding pci_bridges to qemu vms
+* Resolve deprecation warnings of regex library
+* Remove OVMF_CODE_4M.secboot.fd and associated code
+* Add edk2-stable202502 UEFI firmwares and try to first use firmwares from the ovmf package if installed. Fixes #2494
+* Prettify TPM error message
+* Fix bug in qemu_stdout message
+* Try to detect swtpm and AppArmor issue. Ref https://github.com/GNS3/gns3-gui/issues/3725
+* Fix Docker logs decoding. Ref #2522
+* Add delay after starting a Docker container and adding connections in uBridge. Ref #2522
+* Fix TypeError when reading Docker container logs. Ref #2522
+* Allow an image to be uploaded to the controller again even if it is already in the database
+* Fix controller not reporting an error if invalid options are passed to Qemu command line. Fixes #2517
+* Replace "Docker hub" by "Docker repository" because it is possible to use different repositories
+* Fix unable to add NAT cloud after configuring “allowed_interfaces” in configuration file. Fixes #2508
+* Fix interface information API endpoint for Cloud/NAT devices
+* Upgrade Jinja2 to v3.1.6. Fixes #2515
+* Fix packet capture for links connected to a cloud node. Fixes #2513
+* fix: check if remote-install.sh is being run as root
+
+## 2.2.54 21/04/2025
+
+* Bundle web-ui v2.2.54
+* Add new method to find the IP address of a VBox GNS3 VM + allow NAT Network
+* Add edk2-stable202502 UEFI firmwares and try to first use firmwares from the ovmf package if installed. Fixes #2494
+* Try to detect swtpm and AppArmor issue. Ref https://github.com/GNS3/gns3-gui/issues/3725
+* Fix Docker logs decoding. Ref #2522
+* Add delay after starting a Docker container and adding connections in uBridge. Ref #2522
+* Fix TypeError when reading Docker container logs. Ref #2522
+* Replace "Docker hub" by "Docker repository" because it is possible to use different repositories
+* Upgrade dependencies
+* Improvements for remote-install.sh
+
+
+## 3.0.4 25/02/2025
+
+* Require minimum 8 characters for passwords
+* Bundle web-ui v3.0.4
+* Upgrade dependencies
+* Fix auto idle-pc for IOS templates
+* Update schemas to add constraints for values like ram, nvram etc.
+* Install custom symbols. Fixes #2492
+* Fix VMware add ubridge connection. Fixes #2490
+
+## 3.0.3 22/01/2025
+
+* Bundle web-ui v3.0.3
+* Refactor command line arguments parsing
+* Fix capture on IOU/IOL links. Fixes #2477
+* Use Python 3.9 to publish API documentation
+* Upgrade dependencies
+
+## 2.2.53 21/01/2025
+
+* Bundle web-ui v2.2.53
+* Add more information when patching .vbox file. Ref https://github.com/GNS3/gns3-gui/issues/3542
+* Increase timeout to run compute HTTP queries. Fixes #2461
+* Use 'allow_methods="*"' in aiohttp_cors.ResourceOptions(). Fixes #2459
+* Upgrade dependencies
+* Update remote-install.sh to support a custom repository and the deb822 source format
+* Fix: do not use the iourc file if IOU licence check is not enabled
+
 ## 3.0.2 03/01/2025
 
 * Bundle web-ui v3.0.2
@@ -31,7 +736,6 @@
 ## 2.2.52 02/12/2024
 
 * Bundle web-ui v2.2.52
-* Sync appliances
 * Remove restrictions based on file extension when listing images and fix ELF header checks
 * Fix use project name instead of ID for fast duplication when running local server. Fixes #2446
 * Overwrite user resources when the originals have changed.

Dockerfile

@@ -1,4 +1,4 @@
-FROM ubuntu:focal
+FROM ubuntu:noble
 
 WORKDIR /gns3server
 
@@ -31,7 +31,7 @@ RUN add-apt-repository ppa:gns3/ppa && apt update && DEBIAN_FRONTEND=noninteract
 
 COPY . /gns3server
 
-RUN mkdir -p ~/.config/GNS3/3.0/
-RUN cp scripts/gns3_server.conf ~/.config/GNS3/3.0/
+RUN mkdir -p ~/.config/GNS3/3.1/
+RUN cp scripts/gns3_server.conf ~/.config/GNS3/3.1/
 
-RUN python3 -m pip install .
+RUN python3 -m pip install --break-system-packages --ignore-installed .

PROJECT_CONTEXT.md

@@ -0,0 +1,370 @@
+# GNS3 Server - Project Context for Claude Code
+
+> This document provides project context information for the Claude Code AI assistant to work more efficiently.
+
+---
+
+## Project Overview
+
+**Project Name**: GNS3 Server
+**Description**: Network simulation server supporting the GNS3 network virtualization platform
+**Primary Language**: Python
+**Current Branch**: `feature/ai-copilot-bridge`
+**Main Branch**: `master`
+
+---
+
+## Project Structure
+
+```
+gns3server/
+├── agent/                          # AI Copilot related modules
+│   └── gns3_copilot/              # GNS3-Copilot AI Assistant
+│       ├── agent/                  # LangGraph Agent implementation
+│       ├── tools_v2/               # Tool collection (device config, display commands, etc.)
+│       ├── utils/                  # Utility functions and helper modules
+│       ├── gns3_client/            # GNS3 API client
+│       ├── prompts/                # AI prompt templates
+│       ├── agent_service.py        # Agent service layer
+│       └── project_agent_manager.py # Project Agent manager
+│
+├── api/                            # API routes
+│   └── routes/controller/          # Controller API
+│       └── chat.py                 # AI Chat API endpoint
+│
+├── controller/                     # Core controller
+│   ├── project.py                  # Project management
+│   └── ...
+│
+├── schemas/                        # Pydantic data models
+│   └── controller/
+│       └── chat.py                 # Chat API Schema
+│
+├── db/                             # Database module
+│   └── tasks.py                    # Database tasks
+│
+└── docs/                           # Documentation
+    └── gns3-copilot/               # AI Copilot documentation
+```
+
+---
+
+## Key Module Descriptions
+
+### 1. AI Copilot Data Flow
+
+```
+Tool Layer → Agent Layer → Service Layer → API Layer → Frontend
+```
+
+**Tool Output Format**: All tools return `dict` or `list[dict]`, automatically serialized to JSON in the Service layer
+
+**Key Files**:
+- `agent/gns3_copilot/tools_v2/*.py` - Tool implementations
+- `agent/gns3_copilot/agent_service.py:460-473` - Event conversion logic
+- `agent/gns3_copilot/utils/parse_tool_content.py` - Tool result parsing
+
+### 2. SSE Event Types
+
+| Type | Description |
+|------|-------------|
+| `content` | AI text streaming output |
+| `tool_call` | LLM tool invocation (progressive parameters) |
+| `tool_start` | Tool execution started |
+| `tool_end` | Tool execution completed (output as JSON) |
+| `error` | Error message |
+| `done` | Stream ended |
+
+### 3. Important Tools
+
+| Tool Name | File | Function |
+|-----------|------|----------|
+| `ExecuteMultipleDeviceCommands` | `display_tools_nornir.py` | Read-only diagnostic commands |
+| `ExecuteMultipleDeviceConfigCommands` | `config_tools_nornir.py` | Configuration commands |
+| `VPCSMultiCommands` | `vpcs_tools_telnetlib3.py` | VPCS virtual PC commands |
+| `GNS3TemplateTool` | `gns3_get_node_temp.py` | Get GNS3 templates |
+| `GNS3CreateNodeTool` | `gns3_create_node.py` | Create nodes |
+
+---
+
+## Code Standards
+
+### Static Code Analysis (Flake8)
+
+The project uses **flake8** for static code analysis. You must run checks before committing code.
+
+#### Running Flake8
+
+```bash
+# Activate virtual environment
+source venv/bin/activate
+
+# Check a single file
+flake8 path/to/file.py
+
+# Check the entire project
+flake8 gns3server/
+
+# Check a specific directory
+flake8 gns3server/utils/
+```
+
+#### Common Flake8 Error Codes
+
+| Code | Description | Example |
+|------|-------------|---------|
+| **F401** | Module imported but unused | `import os` never used |
+| **F841** | Local variable assigned but never used | `x = 1` not used later |
+| **F824** | `global` declaration never assigned | `global _bar` never assigned in scope |
+| **E501** | Line too long (>79 characters) | Single line exceeds 79 characters |
+
+#### Fix Examples
+
+```python
+# F401: Remove unused imports
+# Bad
+import os  # Never used
+# Good: Delete this line
+
+# F841: Mark as intentionally unused
+# Bad
+def foo():
+    x = 1  # Never used
+
+# Good: Use or mark as intentionally unused
+def foo():
+    x = 1
+    _ = x  # Mark as intentionally unused
+
+# F824: Remove unnecessary global declaration
+# Bad
+def foo():
+    global _fernet  # Never assigned in this scope
+
+# Good: Remove global statement (if only reading)
+def foo():
+    # Just read the global variable, no global declaration needed
+    pass
+
+# E501: Break long lines
+# Bad
+raise RuntimeError("Encryption not initialized. Call init_encryption() first.")
+
+# Good
+raise RuntimeError(
+    "Encryption not initialized. Call init_encryption() first."
+)
+```
+
+#### Ruff (Alternative)
+
+[Ruff](https://docs.astral.sh/ruff/) is a faster Python linter that can replace flake8, isort, black, and more.
+
+```bash
+# Install
+pip install ruff
+
+# Usage
+ruff check gns3server/          # Check code
+ruff check --fix gns3server/    # Auto-fix
+ruff format gns3server/         # Format code
+```
+
+### Python Code Style
+
+```python
+# 1. Type annotations
+def process_data(input_data: dict[str, Any]) -> list[dict[str, Any]]:
+    pass
+
+# 2. Error handling
+try:
+    result = tool.invoke(args)
+except Exception as e:
+    logger.error("Tool failed: %s", e, exc_info=True)
+    return {"error": str(e)}
+
+# 3. JSON serialization
+if not isinstance(output, str):
+    output = json.dumps(output, ensure_ascii=False, indent=2)
+```
+
+### Import Order
+
+```python
+# 1. Standard library
+import asyncio
+import json
+import logging
+
+# 2. Third-party libraries
+from langchain.tools import BaseTool
+from pydantic import BaseModel
+
+# 3. Local modules
+from gns3server.agent.gns3_copilot.agent import agent_builder
+from gns3server.controller import Controller
+```
+
+### Copyright Header
+
+```python
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# GNS3-Copilot - AI-powered Network Lab Assistant for GNS3
+#
+# Copyright (C) 2025 Yue Guobin (岳国宾)
+# Author: Yue Guobin (岳国宾)
+#
+# Project Home: https://github.com/yueguobin/gns3-copilot
+```
+
+---
+
+## Git Commit Standards
+
+### Commit Message Format
+
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+### Type Categories
+
+| Type | Description | Example |
+|------|-------------|---------|
+| `feat` | New feature | `feat(copilot): add user authentication` |
+| `fix` | Bug fix | `fix(api): correct JSON serialization` |
+| `docs` | Documentation update | `docs: update API design doc` |
+| `refactor` | Refactoring | `refactor(agent): simplify state management` |
+| `chore` | Build/toolchain | `chore: update dependencies` |
+
+### Example
+
+```
+fix(copilot): serialize tool output to standard JSON format
+
+Changed tool output serialization in AgentService._convert_event_to_chunk()
+from str() to json.dumps() to ensure structured data is properly formatted.
+
+Changes:
+- Added json import to agent_service.py
+- Modified on_tool_end event handling
+
+Benefits:
+- Frontend can parse tool results with JSON.parse()
+- Chinese characters are preserved (not escaped)
+
+Co-Authored-By: YueGuobin <yueguobin@outlook.com>
+```
+
+### IMPORTANT: Use Your Own Git Account for Commits
+
+When creating git commits, **ALWAYS** use your own git account information for authorship.
+
+**Before committing**, verify your git configuration:
+
+```bash
+# Check current git user configuration
+git config user.name
+git config user.email
+
+# If incorrect, set your own information
+git config user.name "Your Name"
+git config user.email "your.email@example.com"
+```
+
+**For this project**, the current configured user is:
+```
+Name:  YueGuobin
+Email: yueguobin@outlook.com
+```
+
+You may use `Co-Authored-By` to credit contributors, but the `Author` field should always be **your own account**:
+
+```bash
+git commit -m "feat: add new feature
+
+Co-Authored-By: ContributorName <contributor@example.com>"
+```
+
+---
+
+## Development Notes
+
+### 1. When Modifying Tool Output Format
+
+**Must update the following locations**:
+- `agent/gns3_copilot/tools_v2/*.py` - Tool implementation
+- `agent/gns3_copilot/agent_service.py` - Event conversion
+- `docs/gns3-copilot/ai-chat-api-design.md` - API documentation
+
+### 2. Data Serialization Principles
+
+- **Tool Layer**: Return Python `dict`/`list`
+- **Service Layer**: Use `json.dumps()` for serialization
+- **API Layer**: Use Pydantic validation then serialize to SSE
+
+### 3. Logging
+
+```python
+logger.info("Operation started: project_id=%s", project_id)
+logger.debug("Detailed info: data=%s", data)
+logger.error("Error occurred: %s", error, exc_info=True)
+```
+
+### 4. Security Considerations
+
+- Prohibit dangerous commands (reload, erase startup-config, etc.)
+- Use `filter_forbidden_commands()` to filter commands
+- Validate user input (project_id format, etc.)
+
+---
+
+## Common Commands
+
+```bash
+# Run tests
+pytest tests/
+
+# Static code analysis (must run before committing)
+source venv/bin/activate
+flake8 gns3server/
+
+# Check a single file
+flake8 path/to/file.py
+
+# Syntax check
+python3 -m py_compile gns3server/agent/gns3_copilot/agent_service.py
+
+# Check git status
+git status
+
+# View git history
+git log --oneline -15
+
+# View file modification history
+git blame file.py -L 100,120
+
+# Commit code (verify your git user info first!)
+git config user.name && git config user.email
+git add files...
+git commit -m "type(scope): description"
+```
+
+---
+
+## Related Documentation
+
+- [AI Chat API Design](./docs/gns3-copilot/ai-chat-api-design.md)
+- [Command Security Policy](./docs/gns3-copilot/command-security.md)
+- [LLM Model Configuration](./docs/gns3-copilot/llm-model-configs-api.md)
+- [Context Window Management](./docs/gns3-copilot/context-window-management.md)
+
+---
+
+**Document Maintenance**: Please update this document promptly when project structure or development standards change.

README.md

@@ -1,7 +1,7 @@
 # GNS3 server repository
 
 [![Style](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
-[![GitHub Actions tests](https://github.com/GNS3/gns3-server/workflows/testing/badge.svg?branch=3.0)](https://github.com/GNS3/gns3-server/actions?query=workflow%3Atesting+branch%3A3.0)
+[![GitHub Actions tests](https://github.com/GNS3/gns3-server/workflows/testing/badge.svg?branch=3.1)](https://github.com/GNS3/gns3-server/actions?query=workflow%3Atesting+branch%3A3.0)
 [![Latest PyPi version](https://img.shields.io/pypi/v/gns3-server.svg)](https://pypi.python.org/pypi/gns3-server)
 [![Snyk scanning](https://snyk.io/test/github/GNS3/gns3-server/badge.svg)](https://snyk.io/test/github/GNS3/gns3-server)
 
@@ -54,7 +54,50 @@ python3 -m pip install gns3-gui
 python3 -m pip install gns3-server
 ```
 
-The downside of this method is you will have to manually install all dependencies (see below).
+#### Optional Features
+
+GNS3 server supports optional features that can be installed as needed:
+
+**AI Features** (Optional — includes AI Copilot and MCP):
+```shell
+python3 -m pip install gns3-server[ai-features]
+```
+AI-powered assistant for network topology design, automation, and MCP protocol support for AI agent integration.
+
+**Development** (For contributors):
+```shell
+python3 -m pip install gns3-server[dev]
+```
+
+**Web Wireshark** (Optional):
+```shell
+pip install gns3-server && gns3server-web-wireshark-setup
+```
+Browser-based packet capture analysis using Wireshark in a Docker container.
+
+**Combination Installation**:
+You can install multiple optional features together:
+```shell
+python3 -m pip install gns3-server[ai-features,dev]
+```
+
+**Why optional?**
+- Reduces installation size for users who don't need specific features
+- Supports restricted environments (government, education, corporate) where certain libraries may not be allowed
+- Faster installation for basic GNS3 usage
+- Allows users to choose only the features they need
+
+**Note:** If you install without optional extras, the server will work normally but optional features will be disabled. You can add features later by running the appropriate install command.
+
+**Uninstalling AI Features:**
+
+To remove AI Features dependencies (AI Copilot + MCP):
+
+```shell
+gns3server-uninstall-ai-features
+```
+
+This will remove all AI Copilot and MCP dependencies while keeping the core functionality intact. The server will continue to work, but AI features will be disabled.
 
 Please see our [documentation](https://docs.gns3.com/docs/getting-started/installation/linux) for more details.
 
@@ -77,18 +120,30 @@ Note that Docker needs the script program (`bsdutils` or `util-linux` package),
 
 ### Setting up
 
-These commands will install the server as well as all Python dependencies:
+These commands will install the server with core Python dependencies:
 
 ```shell
 git clone https://github.com/GNS3/gns3-server
 cd gns3-server
-git checkout 3.0
+git checkout 3.1
 python3 -m venv venv-gns3server
 source venv-gns3server/bin/activate
 python3 -m pip install .
 python3 -m gns3server
 ```
 
+**For AI Copilot development**, install with additional dependencies:
+
+```shell
+python3 -m pip install .[ai-features,dev]
+```
+
+**For development (tests and linting)**:
+
+```shell
+python3 -m pip install .[dev]
+```
+
 You will have to manually install other software dependencies (see above), for Dynamips, VPCS and uBridge the easiest is to install from our PPA.
 
 ### Docker container
@@ -99,6 +154,12 @@ Alternatively, you can run the GNS3 server in a container
 bash scripts/docker_dev_server.sh
 ```
 
+#### use Docker Compose
+
+``` {.bash}
+docker compose up -d
+```
+
 ### Running tests
 
 First, install the development dependencies:
@@ -131,4 +192,4 @@ Bug fixes or small improvements pull requests go here.
 
 3.x development brand for the next major release.
 
-**Never** use this branch for production. Pull requests for major new features go here.
+**Never** use this branch for production. Pull requests for major new features go here.

ai-requirements.txt

@@ -0,0 +1,50 @@
+# ==============================================================================
+# GNS3 Copilot AI Agent Dependencies
+# ==============================================================================
+# Install with: pip install gns3-server[ai-features]
+# Or directly: pip install -r ai-requirements.txt
+# ==============================================================================
+
+# Core AI and Automation Framework
+# Note: aiosqlite is in core requirements.txt
+langchain>=1.2.10
+langchain-core>=1.2.16
+langgraph>=1.0.9
+langgraph-checkpoint>=4.0.0
+langgraph-checkpoint-sqlite>=3.0.3
+langgraph-checkpoint-postgres>=3.0.4
+
+# Model Providers
+langchain-openai>=1.1.10
+langchain-anthropic>=1.3.4
+langchain-google-genai>=4.2.1
+langchain-aws>=1.3.1
+langchain-ollama>=1.0.1
+langchain-deepseek>=1.0.1
+langchain-xai>=1.2.2
+
+# Token Counting
+tiktoken>=0.8.0
+
+# LangSmith SDK
+langsmith>=0.7.7
+
+# Network Automation
+netmiko>=4.7.0
+nornir>=3.5.0
+nornir-netmiko>=1.0.1
+nornir-utils>=0.2.0
+nornir-salt>=0.23.0
+
+# Environment & Configuration
+python-dotenv>=1.2.1
+
+# Authentication
+PyJWT>=2.10.1
+psycopg-pool>=3.1.0
+
+# Skills Repository Management
+PyYAML>=6.0.0
+GitPython>=3.1.0
+
+# Note: httpx is only for testing (in dev-requirements.txt)

compose.yaml

@@ -0,0 +1,7 @@
+services:
+  gen3-server:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    ports:
+      - "8001:3080"

dev-requirements.txt

@@ -1,7 +1,6 @@
-pytest==8.3.3
-flake8==7.1.1
-pytest-timeout==2.3.1
-pytest-asyncio==0.21.2
-requests==2.32.3
-httpx==0.27.2 # version 0.24.1 is required by httpx_ws
-httpx_ws==0.6.2
+pytest==9.1.1
+flake8==7.3.0
+pytest-timeout==2.4.0
+pytest-asyncio==1.4.0
+httpx==0.28.1
+httpx_ws==0.7.2  # upgrading leads to failures in tests

docs/LICENSE

@@ -0,0 +1,443 @@
+Creative Commons Attribution-ShareAlike 4.0 International
+
+Copyright (c) 2026 GNS3 Web UI Project
+
+=======================================================================
+
+Creative Commons Attribution-ShareAlike 4.0 International
+
+Copyright (C) 2025 Creative Commons Corporation
+
+Creative Commons Corporation ("Creative Commons") is not a law firm and
+does not provide legal services or legal advice. Distribution of
+Creative Commons public licenses does not create a lawyer-client or
+other relationship. Creative Commons makes its licenses and related
+information available on an "as-is" basis. Creative Commons gives no
+warranties regarding its licenses, any material licensed under their
+terms and conditions, or any related information. Creative Commons
+disclaims all liability for damages resulting from their use to the
+fullest extent possible.
+
+Using Creative Commons Public Licenses
+
+Creative Commons public licenses provide a standard set of terms and
+conditions that creators and other rights holders may use to share
+original works of authorship and other material subject to copyright
+and certain other rights specified in the public license below. The
+following considerations are for informational purposes only, are not
+exhaustive, and do not form part of our licenses.
+
+     Considerations for licensors: Our public licenses are
+     intended for use by those authorized to give the public
+     permission to use material in ways otherwise restricted by
+     copyright and certain other rights. Our licenses are
+     irrevocable. Licensors should read and understand the terms
+     and conditions of the license they choose before applying it.
+     Licensors should also secure all rights necessary before
+     applying our licenses so that the public can reuse the
+     material as expected. Licensors should clearly mark any
+     material not subject to the license. This includes other CC-
+     licensed material, or material used under an exception or
+     limitation to copyright. More considerations for licensors:
+     wiki.creativecommons.org/Considerations_for_licensors
+
+     Considerations for the public: Our public licenses are
+     intended for use by those authorized to give the public
+     permission to use material in ways otherwise restricted by
+     copyright and certain other rights. Our licenses are
+     irrevocable. Licensors should read and understand the terms
+     and conditions of the license they choose before applying it.
+     Licensors should also secure all rights necessary before
+     applying our licenses so that the public can reuse the
+     material as expected. Licensors should clearly mark any
+     material not subject to the license. This includes other CC-
+     licensed material, or material used under an exception or
+     limitation to copyright. More considerations for licensors:
+     wiki.creativecommons.org/Considerations_for_licensors
+
+Creative Commons Attribution-ShareAlike 4.0 International Public
+License
+
+By exercising the Licensed Rights (defined below), You accept and agree
+to be bound by the terms and conditions of this Creative Commons
+Attribution-ShareAlike 4.0 International Public License ("Public
+License"). To the extent this Public License may be interpreted as a
+contract, You are granted the Licensed Rights in consideration of Your
+acceptance of these terms and conditions, and the Licensor grants You
+such rights in consideration of benefits the Licensor receives from
+making the Licensed Material available under these terms and conditions.
+
+Section 1 – Definitions.
+
+a. Adapted Material means material subject to Copyright and Similar
+   Rights that is derived from or based upon the Licensed Material
+   and in which the Licensed Material is translated, altered,
+   arranged, transformed, or otherwise modified in a manner requiring
+   permission under the Copyright and Similar Rights held by the
+   Licensor. For purposes of this Public License, where the Licensed
+   Material is a musical work, performance, or sound recording,
+   Adapted Material is always produced where the Licensed Material is
+   synched in timed relation with a moving image.
+
+b. Adapter's License means the license You apply to Your Copyright
+   and Similar Rights in Your contributions to Adapted Material in
+   accordance with the terms and conditions of this Public License.
+
+c. Copyright and Similar Rights means copyright and/or similar rights
+   closely related to copyright including, without limitation,
+   publication, distribution, public performance, public display, and
+   adaptation rights, and rights in database extensions and
+   collections.
+
+d. Licensed Material means the artistic or literary work, database,
+   or other material to which the Licensor applied this Public
+   License.
+
+e. Licensed Rights means rights granted to You subject to the terms
+   and conditions of this Public License, which are limited to all
+   Copyright and Similar Rights that apply to Your use of the
+   Licensed Material and that the Licensor has authority to license.
+
+f. Licensor means the individual(s) or entity(ies) granting rights
+   under this Public License.
+
+g. Share means to provide material to the public by any means or
+   process that requires permission under the Licensed Rights, such
+   as reproduction, public display, public performance, distribution,
+   dissemination, communication, or importation, and to make material
+   available to the public including in ways that members of the
+   public may access the material from a place and at a time
+   individually chosen by them.
+
+h. Sui Generis Database Rights means rights other than copyright
+   resulting from Directive 96/9/EC of the European Parliament and
+   of the Council of 11 March 1996 on the legal protection of
+   databases, as amended and/or succeeded, as well as other
+   essentially equivalent rights anywhere in the world.
+
+i. You means the individual or entity exercising the Licensed Rights
+   under this Public License. Your has a corresponding meaning.
+
+Section 2 – Scope.
+
+a. License grant.
+
+      1. Subject to the terms and conditions of this Public License,
+         the Licensor hereby grants You a worldwide, royalty-free,
+         non-sublicensable, non-exclusive, irrevocable license to
+         exercise the Licensed Rights in the Licensed Material to:
+
+            a. reproduce and Share the Licensed Material, in whole or
+               in part; and
+
+            b. produce, reproduce, and Share Adapted Material.
+
+      2. Exceptions and Limitations. For the avoidance of doubt,
+         where Exceptions and Limitations apply to Your use, this
+         Public License does not apply, and You do not need to
+         comply with its terms and conditions.
+
+      3. Term. The term of this Public License is specified in
+         Section 6(a).
+
+      4. Media and formats; technical modifications allowed. The
+         Licensor authorizes You to exercise the Licensed Rights in
+         all media and formats whether now known or hereafter created,
+         and to make technical modifications necessary to do so. The
+         Licensor waives and/or agrees not to assert any right or
+         authority to forbid You from making technical modifications
+         necessary to exercise the Licensed Rights, including
+         technical modifications necessary to circumvent Effective
+         Technological Measures. For purposes of this Public License,
+         simply making modifications authorized by this Section 2(a)
+         (4) never produces Adapted Material.
+
+      5. Downstream recipients.
+
+            a. Offer from the Licensor – Licensed Material. Every
+               recipient of the Licensed Material automatically
+               receives an offer from the Licensor to exercise the
+               Licensed Rights under the terms and conditions of this
+               Public License.
+
+            b. Additional offer from the Licensor – Adapted Material.
+               Every recipient of Adapted Material from You
+               automatically receives an offer from the Licensor to
+               exercise the Licensed Rights in the Adapted Material
+               under the conditions of the Adapter's License You
+               apply.
+
+      6. No endorsement. Nothing in this Public License constitutes or
+         may be construed as permission to assert or imply that You
+         are, or that Your use of the Licensed Material is, connected
+         with, or sponsored, endorsed, or granted official status by,
+         the Licensor or others designated to receive attribution as
+         provided in Section 3(a)(1)(A)(i).
+
+b. Other rights. Moral rights, such as the right of integrity, are
+   not licensed under this Public License, nor are publicity,
+   privacy, and/or other similar personality rights; however, to the
+   extent possible, the Licensor waives and/or agrees not to assert
+   any such rights held by the Licensor to the limited extent
+   necessary to allow You to exercise the Licensed Rights, but not
+   otherwise.
+
+c. Patent and trademark rights are not licensed under this Public
+   License.
+
+d. To the extent possible, the Licensor waives any right to collect
+   royalties from You for the exercise of the Licensed Rights,
+   whether directly or through a collecting society under any
+   voluntary or waivable statutory or compulsory licensing scheme.
+   In all other cases the Licensor expressly reserves any right to
+   collect such royalties.
+
+Section 3 – License Conditions.
+
+Your exercise of the Licensed Rights is expressly made subject to
+the following conditions.
+
+a. Attribution.
+
+      1. If You Share the Licensed Material (including in modified
+         form), You must:
+
+            a. retain the following if it is supplied by the
+               Licensor with the Licensed Material:
+
+                  i. identification of the creator(s) of the
+                     Licensed Material and any others designated to
+                     receive attribution, in any reasonable manner
+                     requested by the Licensor (including by
+                     pseudonym if designated);
+
+                 ii. a copyright notice;
+
+                iii. a notice that refers to this Public License;
+
+                 iv. a notice that refers to the disclaimer of
+                     warranties;
+
+                  v. a URI or hyperlink to the Licensed Material to
+                     the extent reasonably practicable;
+
+            b. indicate if You modified the Licensed Material and
+               retain an indication of any previous modifications; and
+
+            c. indicate the Licensed Material is licensed under this
+               Public License, and include the text of, or the URI
+               or hyperlink to, this Public License.
+
+      2. You may satisfy the conditions in Section 3(a)(1) in any
+         reasonable manner based on the medium, means, and context in
+         which You Share the Licensed Material. For example, it may
+         be reasonable to satisfy the conditions by providing a URI
+         or hyperlink to a resource that includes the required
+         information.
+
+      3. If requested by the Licensor, You must remove any of the
+         information required by Section 3(a)(1)(A) to the extent
+         reasonably practicable.
+
+      4. If You Share Adapted Material You produce, the Adapter's
+         License You apply must not prevent recipients of the
+         Adapted Material from complying with this Public License.
+
+b. ShareAlike.
+
+   In addition to the conditions in Section 3(a), if You Share
+   Adapted Material You produce, the following conditions also apply.
+
+      1. The Adapter's License You apply must be a Creative Commons
+         license with the same License Elements, this version or
+         later, or a BY-SA Compatible License.
+
+      2. You must include the text of, or the URI or hyperlink to,
+         the Adapter's License You apply. You may satisfy this
+         condition in any reasonable manner based on the medium,
+         means, and context in which You Share Adapted Material.
+
+      3. You may not offer or impose any additional or different terms
+         or conditions on, or apply any Effective Technological
+         Measures to, Adapted Material that restrict exercise of the
+         rights granted under the Adapter's License You apply.
+
+Section 4 – Sui Generis Database Rights.
+
+Where the Licensed Rights include Sui Generis Database Rights that
+apply to Your use of the Licensed Material:
+
+a. for the avoidance of doubt, Section 2(a)(1) grants You the right
+   to extract, reuse, reproduce, and Share all or a substantial
+   portion of the contents of the database;
+
+b. if You include all or a substantial portion of the database
+   contents in a database in which You have Sui Generis Database
+   Rights, then the database in which You have Sui Generis Database
+   Rights (but not its individual contents) is Adapted Material; and
+
+c. You must comply with the conditions in Section 3(a) if You Share
+   all or a substantial portion of the contents of the database.
+
+For the avoidance of doubt, this Section 4 supplements and does not
+replace Your obligations under this Public License where the Licensed
+Rights include other Copyright and Similar Rights.
+
+Section 5 – Disclaimer of Warranties and Limitation of Liability.
+
+a. Unless otherwise separately undertaken by the Licensor, to the
+   extent possible, the Licensor offers the Licensed Material as-is
+   and as-available, and makes no representations or warranties of
+   any kind concerning the Licensed Material, whether express,
+   implied, statutory, or other. This includes, without limitation,
+   warranties of title, merchantability, fitness for a particular
+   purpose, non-infringement, absence of latent or other defects,
+   accuracy, or the presence or absence of errors, whether or not
+   known or discoverable. Where disclaimers of warranties are not
+   allowed in full or in part, this disclaimer may not apply to You.
+
+b. To the extent possible, in no event will the Licensor be liable
+   to You on any legal theory (including, without limitation,
+   negligence) or otherwise for any direct, special, indirect,
+   incidental, consequential, punitive, exemplary, or other losses,
+   costs, expenses, or damages that arise out of this Public License
+   or use of the Licensed Material, even if the Licensor has been
+   advised of the possibility of such losses, costs, expenses, or
+   damages. Where a limitation of liability is not allowed in full
+   or in part, this limitation may not apply to You.
+
+c. The disclaimer of warranties and limitation of liability provided
+   above shall be interpreted in a manner that, to the extent
+   possible, most closely approximates an absolute disclaimer and
+   waiver of all liability.
+
+Section 6 – Term and Termination.
+
+a. This Public License applies for the term of the Copyright and
+   Similar Rights licensed here. However, if You fail to comply
+   with this Public License, then Your rights under this Public
+   License terminate automatically.
+
+b. Where Your right to use the Licensed Material has terminated
+   under Section 6(a), it reinstates:
+
+      1. automatically as of the date the violation is cured,
+         provided it is cured within 30 days of Your discovery of
+         the violation; or
+
+      2. upon express reinstatement by the Licensor.
+
+   For the avoidance of doubt, this Section 6(b) does not affect any
+   right the Licensor may have to seek remedies for Your violations
+   of this Public License.
+
+c. For the avoidance of doubt, the Licensor may also offer the
+   Licensed Material under separate terms or conditions or stop
+   distributing the Licensed Material at any time; however, doing so
+   will not terminate this Public License.
+
+d. Sections 1, 5, 6, 7, and 8 survive termination of this Public
+   License.
+
+Section 7 – Other Terms and Conditions.
+
+a. The Licensor shall not be bound by any additional or different
+   terms or conditions communicated by You unless expressly agreed.
+
+b. Any arrangements, understandings, or agreements regarding the
+   Licensed Material not stated herein are separate from and
+   independent of the terms and conditions of this Public License.
+
+Section 8 – Interpretation.
+
+a. For the avoidance of doubt, this Public License does not, and
+   shall not be interpreted to, reduce, limit, restrict, or impose
+   conditions on any use of the Licensed Material that could lawfully
+   be made without permission under this Public License.
+
+b. To the extent possible, if any provision of this Public License
+   is deemed unenforceable, it shall be automatically reformed to
+   the minimum extent necessary to make it enforceable. If the
+   provision cannot be reformed, it shall be severed from this
+   Public License without affecting the enforceability of the
+   remaining terms and conditions.
+
+c. No term or condition of this Public License will be waived and
+   no failure to comply consented to unless expressly agreed to by
+   the Licensor.
+
+d. Nothing in this Public License constitutes or may be interpreted
+   as a limitation upon, or waiver of, any privileges and immunities
+   that apply to the Licensor or You, including from the legal
+   processes of any jurisdiction or authority.
+
+=======================================================================
+
+Creative Commons is not a party to its public licenses. Notwithstanding,
+Creative Commons may elect to apply one of its public licenses to
+material it publishes and in those instances will be considered the
+"Licensor." The text of the Creative Commons public licenses is
+dedicated to the public domain under the CC0 Public Domain Dedication.
+The text of the Creative Commons public licenses is dedicated to the
+public domain under the CC0 Public Domain Dedication. Except for the
+limited purpose of indicating that material is shared under a Creative
+Commons public license or as otherwise permitted by the Creative Commons
+policies published at creativecommons.org/policies, Creative Commons
+does not authorize the use of the trademark "Creative Commons" or any
+other trademark or logo of Creative Commons without its prior written
+consent including, without limitation, in connection with any
+unauthorized modifications to any of its public licenses or any other
+arrangements, understandings, or agreements concerning use of licensed
+material. For the avoidance of doubt, this paragraph does not form part
+of the public licenses.
+
+Creative Commons may be contacted at creativecommons.org.
+
+=======================================================================
+
+For the GNS3 Web UI documentation:
+
+- Documentation License: CC BY-SA 4.0
+- Project License: GPLv3 (see root LICENSE file)
+- License URL: https://creativecommons.org/licenses/by-sa/4.0/
+
+All documentation files in this directory are licensed under the
+Creative Commons Attribution-ShareAlike 4.0 International License
+(CC BY-SA 4.0).
+
+=======================================================================
+
+IMPORTANT: ShareAlike Requirements for Software Derivatives
+
+Under the CC BY-SA 4.0 ShareAlike condition, if you create derivative
+works based on this documentation, including software that is considered
+a derivative of the documentation, you must:
+
+1. **License your derivative work under CC BY-SA 4.0 or a compatible
+   license** (such as GPLv3, which is compatible with CC BY-SA 4.0)
+
+2. **Attribute the original documentation** to the GNS3 Web UI Project
+
+3. **Indicate if you modified the documentation** and retain
+   indications of previous modifications
+
+4. **Include the license notice** and link to the CC BY-SA 4.0 license
+
+What constitutes a derivative work:
+- Translations of the documentation
+- Adaptations, modifications, or enhancements to the documentation
+- Software that incorporates substantial portions of the documentation
+- Works based on the documentation's structure, organization, or content
+
+Compatible licenses include:
+- CC BY-SA 4.0 or later
+- GPLv3 (GNU General Public License version 3)
+- AGPLv3 (GNU Affero General Public License version 3)
+- Other licenses approved as compatible by Creative Commons
+
+For more information on CC BY-SA compatibility, see:
+https://creativecommons.org/compatiblelicenses
+
+If you are unsure whether your use constitutes a derivative work or
+which license to apply, please consult the full CC BY-SA 4.0 license
+text above or seek legal advice.

docs/README.md

@@ -0,0 +1,130 @@
+<!--
+SPDX-License-Identifier: CC-BY-SA-4.0
+See LICENSE file for licensing information.
+-->
+
+> This documentation is organized by AI with reference to actual code. AI can make mistakes — please verify against the source code when in doubt.
+
+# GNS3 Server Documentation
+
+---
+
+## License
+
+This documentation is licensed under the **Creative Commons Attribution-ShareAlike 4.0 International License (CC BY-SA 4.0)**.
+
+⚠️ **Important - ShareAlike Requirement**: If you create derivative works based on this documentation (including software that incorporates substantial portions of the documentation), your work must also be licensed under **CC BY-SA 4.0 or a compatible license** (such as GPLv3).
+
+- 📄 **Full License Text**: See [docs/LICENSE](./LICENSE)
+- 🔗 **License URL**: https://creativecommons.org/licenses/by-sa/4.0/
+- 📖 **Compatibility**: https://creativecommons.org/compatiblelicenses
+
+**Dual License Structure**:
+- 📚 **Documentation**: CC BY-SA 4.0 (this directory)
+- 💻 **Software Code**: GPLv3 (see root [LICENSE](../LICENSE))
+
+---
+
+Technical documentation for the GNS3 server project, covering features, AI Copilot, development setup, and known issues.
+
+## Directory Structure
+
+```
+docs/
+├── README.md                                    # This file
+├── development-setup.md                         # Ubuntu 24.04 development environment setup
+├── openapi.json                                 # OpenAPI specification
+├── features/                                    # Feature documentation
+│   ├── compute-controller-setup.md              # Controller + Compute architecture & configuration
+│   ├── statistics-api.md                        # Aggregated statistics API for monitoring
+│   ├── vnc-websocket-console.md                 # Browser-based VNC console via WebSocket
+│   └── web-wireshark-business-process.md        # Web Wireshark (Docker + xpra packet capture)
+├── gns3-copilot/                                # AI Copilot feature documentation
+│   ├── netmiko_devices.md                       # Netmiko supported devices (366 types)
+│   ├── template-based-configuration-roadmap.md  # Future: template-based config with HITL
+│   └── implemented/                             # Implemented features
+│       ├── chat-api.md                          # Chat API (SSE, session management)
+│       ├── llm-model-configs.md                 # LLM model configuration system
+│       ├── command-security.md                  # Command security and filtering
+│       ├── context-window-management.md         # Context window optimization
+│       ├── node-control-tools.md                # Node start/stop/suspend tools
+│       └── multi-vendor-device-support.md       # Multi-vendor device support
+└── bugs/                                        # Known issues & bug reports
+    └── telnet-server-connection-race-condition.md
+```
+
+---
+
+## Features
+
+### Controller + Compute Setup (`features/compute-controller-setup.md`)
+Architecture and minimum configuration for setting up GNS3 Controller with remote Compute nodes. Covers compute node config, controller registration, and multi-compute deployment.
+
+### Statistics API (`features/statistics-api.md`)
+Aggregated server statistics API (`GET /v3/statistics`) for monitoring dashboards. Collects compute resources, project/node/link counts, and Web Wireshark container status in a single request.
+
+### VNC WebSocket Console (`features/vnc-websocket-console.md`)
+Browser-based VNC console access via WebSocket. The Controller acts as WebSocket-to-WebSocket relay, and Compute bridges WebSocket to TCP for QEMU/Docker VMs. Supports noVNC clients.
+
+### API Error Responses (`features/api-error-responses.md`)
+Unified error response format across all GNS3 API endpoints. Documents HTTP status codes, error types, and client-side error handling patterns.
+
+### Web Wireshark (`features/web-wireshark-business-process.md`)
+Web-based packet capture analysis using Docker + xpra HTML5 client. Zero-install Wireshark experience directly in the browser, integrated with GNS3 topologies.
+
+### Marker (Traffic Insight) (`features/marker-traffic-insight.md`)
+Real-time traffic insight via per-link BPF markers and project-level inherited definitions. A marker taps a link in uBridge, emitting match notifications and pcap capture on BPF hit; definitions fan out to every capable link automatically.
+
+### Docker exec Console (Vendor NOS) (`features/docker-exec-console.md`)
+Console for vendor NOS containers (SR Linux, XRd, …) whose CLI is a TUI off PID 1: runs the vendor CLI via the Docker exec API, plus `GNS3_SKIP_INIT`/`GNS3_INTERFACE_NAMES` boot knobs and SKIP_INIT volume persistence.
+
+### Cisco XRd Control Plane (`features/vendor-nos-xrd.md`)
+Cisco XRd as a GNS3 Docker router: vendor path + shm/device injection (`GNS3_SHM_SIZE`/`GNS3_DEVICES`), config-file injection (`extra_configs`), udev masking (`GNS3_MASK_UDEV`) so privileged systemd containers don't disturb the host, and the host-readiness check.
+
+---
+
+## GNS3 AI Copilot (`gns3-copilot/`)
+
+### Implemented Features
+
+| Feature | Description | Status |
+|---------|-------------|--------|
+| [Chat API](gns3-copilot/implemented/chat-api.md) | SSE streaming, session management, token statistics | Implemented |
+| [LLM Model Configs](gns3-copilot/implemented/llm-model-configs.md) | Multi-level model config (system/group/user) | Implemented |
+| [Command Security](gns3-copilot/implemented/command-security.md) | Command filtering, dangerous operation detection, HITL | Implemented |
+| [Context Window Management](gns3-copilot/implemented/context-window-management.md) | Token optimization, content filtering, compression | Implemented |
+| [Node Control Tools](gns3-copilot/implemented/node-control-tools.md) | Start/stop/suspend with batch ops and progress tracking | Implemented |
+| [Multi-Vendor Support](gns3-copilot/implemented/multi-vendor-device-support.md) | Cisco, Huawei, Ruijie, VPCS with custom Netmiko drivers | Implemented |
+
+### Reference
+
+- [Netmiko Supported Devices](gns3-copilot/netmiko_devices.md) — 366 device types (154 SSH, 55 Telnet, 3 custom GNS3 drivers)
+
+### Roadmap
+
+- [Template-Based Configuration with HITL](gns3-copilot/template-based-configuration-roadmap.md) — Jinja2 templates with human-in-the-loop confirmations for device configuration and node creation
+
+---
+
+## Known Issues (`bugs/`)
+
+- [Telnet Server Connection Race Condition](bugs/telnet-server-connection-race-condition.md) — `getpeername()` error when client disconnects during connection setup (High severity, Open)
+- [Docker Link UDP Self-Loop](bugs/link-udp-self-loop.md) — intermittent one-way link (both ends handed the same UDP port by an allocation race); **fixed** (Medium severity)
+
+---
+
+## Development Setup (`development-setup.md`)
+
+Quick-start guide for Ubuntu 24.04: install via PPA, set up dependencies, and run gns3-server from source.
+
+---
+
+## Related Documentation
+
+- [GNS3 Server API Documentation](https://api.gns3.com/) — Interactive API docs (also available locally via `redoc.html`)
+- [GNS3 Web UI Documentation](https://docs.gns3.com/)
+- [LangGraph Documentation](https://langchain-ai.github.io/langgraph/)
+
+---
+
+_Last updated: 2026-08-14_

docs/bugs/link-udp-self-loop.md

@@ -0,0 +1,101 @@
+<!--
+SPDX-License-Identifier: CC-BY-SA-4.0
+See LICENSE file for licensing information.
+-->
+
+> This documentation is organized by AI with reference to actual code. AI can make mistakes — please verify against the source code when in doubt.
+
+# Docker Link UDP Self-Loop Bug (One-Way Link)
+
+## Bug Report
+
+**Date**: 2026-08-14
+**Severity**: Medium (one-way connectivity, CPU burn from packet duplication; intermittent)
+**Status**: **Fixed** — root cause found and unit-tested (same day)
+**Component**: UDP port allocation — `gns3server/compute/port_manager.py`
+(`get_free_udp_port` find-then-add race); secondary: `gns3server/controller/udp_link.py`
+(`_prepare` accumulated stale `_link_data` on reset)
+
+## Symptoms
+
+Two Docker nodes (observed with Cisco XRd; node-type agnostic) linked on the
+same compute cannot ping each other. Packet capture on the link shows only **one**
+side sending ARP. The other side's traffic never appears on the link at all.
+
+## Evidence (from the live occurrence)
+
+Captured simultaneously on both nodes' uBridge `bridge1` (see diagnostics below):
+
+| Direction | Result |
+|---|---|
+| A → B | works — A's ARP requests arrive at B's bridge, B replies |
+| B → A | dead — B's replies/ICMP appear only on **B's own bridge** (duplicated ×2–×3), nothing arrives at A |
+| B's `ethN` counters | RX ≈ TX ≈ 5000+ — B receives its own transmissions back |
+| A's `ethN` counters | TX > 0, RX = 0 — never receives anything |
+
+## Root Cause (confirmed)
+
+**`PortManager.get_free_udp_port` had an unguarded find-then-add sequence.**
+A link allocates the UDP port for **both ends concurrently**
+(`asyncio.gather` in `UDPLink._prepare` → two `POST /ports/udp`). The route
+handler is a sync `def`, so FastAPI executes the two requests **in parallel
+threads**. Both threads ran `find_unused_port` (socket-probing, GIL-releasing)
+before either reached `_used_udp_ports.add(port)` — the set add is idempotent,
+so no error was raised and **both ends were handed the same port number**:
+`lport == rport` on both NIOs, a literal self-loop.
+
+Why it was *silent* and *asymmetric*:
+
+- uBridge sets `SO_REUSEADDR` on UDP NIO sockets (`ubridge/src/nio_udp.c`), so
+  the second bind of the same port **succeeds** instead of failing with
+  `EADDRINUSE` — link creation returned success.
+- With two sockets bound to the same port, the kernel delivers to one of them
+  (last bound wins). The node that started later — in the live case B,
+  restarted ~77 s after A — received **everything**: A's packets *and* its own
+  transmissions echoed back. The 77 s restart did not cause the corruption; it
+  only decided which end starves.
+- The same-compute condition is part of the trigger: both allocations hit the
+  same `PortManager` instance (a cross-compute link races two processes and
+  cannot self-collide).
+
+A second, smaller defect was found while auditing: `UDPLink._prepare()`
+**appended** to `self._link_data` but the committed NIOs are always taken from
+indices 0/1 — after `reset()` (delete + create on the same object) the stale,
+already-released port pair was re-committed and the freshly allocated ports
+were leaked.
+
+## Fix
+
+| Change | Where |
+|---|---|
+| `threading.RLock` making find-then-add (and reserve/release) atomic for TCP and UDP | `gns3server/compute/port_manager.py` |
+| `_prepare()` rebuilds `_link_data` from scratch instead of appending | `gns3server/controller/udp_link.py` |
+| Regression tests: threaded allocation never returns duplicates (red on the old code); `reset()` commits the fresh mirrored pair with `lport != rport` | `tests/compute/test_port_manager.py`, `tests/controller/test_udp_link.py` |
+
+## Diagnostics (uBridge console is the fast path)
+
+1. **uBridge console** — each node's uBridge listens on a Unix socket
+   `/run/user/1000/gns3/ubridge-<node_id>.sock`; connect and send:
+   `bridge list` (NIO count per bridge), and
+   `bridge start_capture bridge<N> "/tmp/ub-<node>.pcap"` /
+   `bridge stop_capture bridge<N>` to capture what the bridge actually forwards.
+   Comparing the two ends' pcaps localizes the break immediately.
+2. **Container counters** — `docker exec <cid> ip -s link show ethN`:
+   TX>0/RX=0 → peer never returns; RX≈TX huge with µs-scale duplicates → self-loop.
+3. **UDP sockets** — `ss -uln` (no `-p`; uBridge runs setuid-root so process names
+   are hidden, ports are visible): a two-node link owns exactly two "orphan" UDP
+   ports. **One port instead of two = this bug.**
+4. **Recovery** — delete and re-create the link (or stop/start both nodes);
+   with the fix, the corruption no longer occurs in the first place.
+
+Note: a Docker node's in-container `ethN` is a **TAP device** whose file descriptor
+lives inside uBridge (the interface is created host-side, then moved into the
+container namespace and renamed). There is no veth host end to look for — do not
+waste time hunting for one in the host namespace.
+
+## Related
+
+- `docs/features/vendor-nos-xrd.md` — troubleshooting table entry pointing here.
+- Link-create batch optimization (`controller/udp_link.py`, project-open bulk path)
+  was exonerated: the pool path allocates sequentially in one handler and cannot
+  self-collide.

docs/bugs/telnet-server-connection-race-condition.md

@@ -0,0 +1,316 @@
+<!--
+SPDX-License-Identifier: CC-BY-SA-4.0
+See LICENSE file for licensing information.
+-->
+
+> This documentation is organized by AI with reference to actual code. AI can make mistakes — please verify against the source code when in doubt.
+
+
+# Telnet Server Connection Race Condition Bug
+
+## Bug Report
+
+**Date**: 2026-03-14
+**Severity**: High
+**Status**: Open
+**Component**: Telnet Server (`gns3server/utils/asyncio/telnet_server.py`)
+
+## Error Logs
+
+```
+2026-03-14 15:21:31 ERROR asyncio:1879 Unhandled exception in client_connected_cb
+transport: <_SelectorSocketTransport fd=67 read=polling write=<idle, bufsize=0>>
+Traceback (most recent call last):
+  File "/home/yueguobin/myCode/GNS3/gns3-server/gns3server/utils/asyncio/telnet_server.py", line 215, in run
+    await self._process(network_reader, network_writer, connection)
+  File "/home/yueguobin/myCode/GNS3/gns3-server/gns3server/utils/asyncio/telnet_server.py", line 305, in _process
+    client_info = connection_key.get_extra_info("socket").getpeername()
+  File "/usr/lib64/python3.13/asyncio/trsock.py", line 77, in getpeername
+    return self._sock.getpeername()
+           ~~~~~~~~~~~~~~~~~~~~~~^^
+OSError: [Errno 107] Transport endpoint is not connected
+```
+
+## Root Cause Analysis
+
+### Architecture
+
+The GNS3 Telnet server architecture supports multiple concurrent client connections to a single node console:
+
+```
+┌──────────────────────────────────────────────────────────┐
+│  Node (VPCS/Docker/Router/Switch, etc.)                  │
+│  - Independent process                                   │
+│  - Normal operation, processing business logic           │
+└────────────────────┬─────────────────────────────────────┘
+                     │ stdout (device output)
+                     │
+        ┌────────────▼─────────────────────────────────────┐
+        │   AsyncioTelnetServer (Telnet Proxy Server)      │
+        │   - Reads output from Node                        │
+        │   - Broadcasts to all connected clients           │
+        │   - ← ← Bug occurs at this layer ← ←             │
+        └────────────┬─────────────────────────────────────┘
+                     │
+        ┌────────────┼────────────┬──────────────────┐
+        │            │            │                  │
+    Web Console   Auto Script   Client 1           Client 2
+   (long-lived)  (quick disco)  (normal)           (normal)
+```
+
+### The Race Condition
+
+The bug occurs in the broadcast logic when a client disconnects while the server is iterating through connections:
+
+**Timeline**:
+```
+t1: Clients A, B, C connect to the same Telnet port
+t2: Device has output (e.g., log message)
+t3: Client A receives data and script immediately disconnects (FIN sent)
+t4: Server hasn't read EOF yet (event loop hasn't checked this connection)
+t5: Server iterates through connections to broadcast data
+t6: When iterating to Client A, getpeername() is called → OSError!
+```
+
+### Code Location
+
+**File**: `gns3server/utils/asyncio/telnet_server.py`
+**Line**: 305
+
+**Problematic Code**:
+```python
+# Line 304-305
+for connection_key in list(self._connections.keys()):
+    client_info = connection_key.get_extra_info("socket").getpeername()  # ← OSError here
+    connection = self._connections[connection_key]
+
+    try:
+        connection.writer.write(data)
+        await asyncio.wait_for(connection.writer.drain(), timeout=10)
+    except:
+        log.debug(f"Timeout while sending data to client: {client_info}, closing and removing from connection table.")
+        connection.close()
+        del self._connections[connection_key]
+```
+
+### The Core Issue
+
+The `getpeername()` call is **outside** the try-except block, so any OSError from it is not caught.
+
+Additionally, the top-level exception handler at line 216 only catches `ConnectionError`:
+
+```python
+# Line 212-227
+try:
+    await self._write_intro(network_writer, echo=self._echo, binary=self._binary, naws=self._naws)
+    await connection.connected()
+    await self._process(network_reader, network_writer, connection)
+except ConnectionError:  # ← Only catches ConnectionError
+    async with self._lock:
+        network_writer.close()
+        if self._reader_process == network_reader:
+            self._reader_process = None
+        if self._current_read is not None:
+            self._current_read.cancel()
+
+    await connection.disconnected()
+    del self._connections[network_writer]
+```
+
+**Python Exception Hierarchy**:
+```
+BaseException
+ └─ Exception
+    ├─ ConnectionError  ← Only this is caught
+    │  ├─ ConnectionResetError
+    │  ├─ BrokenPipeError
+    │  └─ ...
+    └─ OSError  ← Actually thrown! (not a subclass of ConnectionError)
+       └─ [Errno 107] Transport endpoint is not connected
+```
+
+Since `OSError` is **not** a subclass of `ConnectionError`, it propagates uncaught to the asyncio event loop.
+
+## Impact Assessment
+
+### Immediate Effects
+
+| Impact | Severity | Description |
+|--------|----------|-------------|
+| Connection interrupted | 🔴 High | The connection triggering the exception is terminated |
+| Resource leak | 🟠 Medium | socket/connection not properly cleaned up |
+| Other clients affected | 🟡 Low | Other clients on same port may miss broadcast data |
+| Service stability | 🟡 Low | Long-running may accumulate zombie connections |
+
+### User-Reported Symptoms
+
+After this error occurs, users report:
+
+1. **Cannot open the affected node** - Clicking on the node fails
+2. **Cannot close the node** - Close button doesn't work
+3. **"Node not found" errors** - Operations on the node return 404
+4. **Refresh fixes it temporarily** - Reloading the page restores functionality
+
+### Why This Happens
+
+When the uncaught `OSError` occurs, the cleanup code at lines 217-227 **never executes**:
+
+```python
+except ConnectionError:
+    async with self._lock:
+        network_writer.close()           # ✗ Not executed
+        if self._reader_process == network_reader:
+            self._reader_process = None  # ✗ Not executed
+        if self._current_read is not None:
+            self._current_read.cancel()  # ✗ Not executed
+    await connection.disconnected()      # ✗ Not executed
+    del self._connections[network_writer]  # ✗ Not executed
+```
+
+This leads to:
+- **Resource leaks**: socket and writer not closed, file descriptors leaked
+- **State inconsistency**: `_connections` dictionary retains disconnected connections
+- **Potential deadlocks**: Locks may not be released if exception occurs while holding them
+- **Subsequent operation failures**: Future operations may access zombie connections
+
+### Effect on Node Process
+
+**The Node process itself is NOT affected**:
+- Node continues running normally
+- Node's stdout has already been read by the proxy
+- The bug occurs during the broadcast phase, after data has been read
+
+The issue is in the **Telnet Proxy layer**, not the node itself.
+
+## Trigger Conditions
+
+This error is more likely to occur with:
+
+| Scenario | Probability | Reason |
+|----------|-------------|--------|
+| **Automated scripts** | 🔴 High | Fast connect → execute → disconnect, small time window |
+| **Manual operation** | 🟡 Medium | Can occur (e.g., closing terminal, network fluctuation) |
+| **Normal usage** | 🟢 Low | Human operations slower, server usually detects EOF first |
+
+### Typical Scenario
+
+1. User opens Web Console (long-lived connection)
+2. Automated script connects → executes command → quickly disconnects
+3. While script disconnects, device has output that needs broadcasting
+4. During connection iteration, script connection already closed
+5. `getpeername()` call fails with OSError
+
+## Related Issues
+
+A secondary issue was found in the error handler:
+
+**File**: `gns3server/api/server.py`
+**Line**: 162
+
+```python
+@app.exception_handler(ControllerNotFoundError)
+async def controller_not_found_error_handler(request: Request, exc: ControllerNotFoundError):
+    log.error(f"Controller not found error in {request.url.path} ({request.method}): {exc}")
+    #                                                               ^^^^^^^^^^^^^^^
+    return JSONResponse(...)
+```
+
+**Problem**: `request.method` only exists in HTTP requests, not WebSocket connections.
+
+When a WebSocket request triggers this exception handler:
+```
+ControllerNotFoundError: Node ID xxx doesn't exist
+                  ↓
+Attempt to log error
+                  ↓
+AttributeError: 'WebSocket' object has no attribute 'method'
+```
+
+This masks the original error with an attribute error.
+
+## Proposed Fix
+
+### Primary Fix (Telnet Server)
+
+Move `getpeername()` inside the try block and catch OSError:
+
+```python
+# Lines 303-314
+for connection_key in list(self._connections.keys()):
+    connection = self._connections[connection_key]
+    client_info = None
+
+    try:
+        client_info = connection_key.get_extra_info("socket").getpeername()
+        connection.writer.write(data)
+        await asyncio.wait_for(connection.writer.drain(), timeout=10)
+    except (OSError, ConnectionError, asyncio.TimeoutError) as e:
+        log.debug(f"Error sending data to client {client_info}: {e}, closing and removing from connection table.")
+        connection.close()
+        del self._connections[connection_key]
+```
+
+### Secondary Fix (Top-level Exception Handler)
+
+Catch OSError in the main handler to ensure cleanup:
+
+```python
+# Lines 212-227
+try:
+    await self._write_intro(network_writer, echo=self._echo, binary=self._binary, naws=self._naws)
+    await connection.connected()
+    await self._process(network_reader, network_writer, connection)
+except (ConnectionError, OSError):  # ← Add OSError
+    async with self._lock:
+        network_writer.close()
+        if self._reader_process == network_reader:
+            self._reader_process = None
+        if self._current_read is not None:
+            self._current_read.cancel()
+
+    await connection.disconnected()
+    del self._connections[network_writer]
+```
+
+### Tertiary Fix (API Error Handler)
+
+Fix the WebSocket error handler:
+
+```python
+@app.exception_handler(ControllerNotFoundError)
+async def controller_not_found_error_handler(request: Request, exc: ControllerNotFoundError):
+    method = getattr(request, 'method', 'WebSocket')
+    log.error(f"Controller not found error in {request.url.path} ({method}): {exc}")
+    return JSONResponse(
+        status_code=status.HTTP_404_NOT_FOUND,
+        content={"message": str(exc)},
+    )
+```
+
+## Reproduction Steps
+
+**To be documented** after testing.
+
+Potential reproduction scenario:
+1. Start a GNS3 node with console enabled (e.g., VPCS)
+2. Open web console to keep a long-lived connection
+3. Run automated script that:
+   - Connects to the same console port
+   - Executes a command
+   - Immediately disconnects
+4. While script is disconnecting, trigger device output
+5. Observe the error in logs
+
+## References
+
+- **Files**:
+  - `gns3server/utils/asyncio/telnet_server.py:305` (primary issue)
+  - `gns3server/utils/asyncio/telnet_server.py:216` (exception handler)
+  - `gns3server/api/server.py:162` (secondary issue)
+
+- **Related Commits**:
+  - Recent telnet-related work on feature branch
+
+- **Error Patterns**:
+  - Race condition in connection management
+  - Incomplete exception handling in asyncio code

docs/development-setup.md

@@ -0,0 +1,146 @@
+# Ubuntu 24.04 GNS3 Development Environment Setup
+
+## Simplified Development Environment Setup
+
+### 1. Add PPA
+
+```bash
+sudo apt update
+sudo apt install software-properties-common
+sudo add-apt-repository ppa:gns3/ppa
+sudo apt update
+```
+
+### 2. Install Dependencies
+
+Binary tools (Dynamips, VPCS, uBridge, etc.) are automatically installed as gns3-server dependencies
+
+```bash
+sudo apt install gns3-server tshark
+```
+
+### 3. Remove gns3-server While Keeping Dependencies
+
+If you only want to run the server from source:
+
+```bash
+# Remove main package only, keep dependencies
+sudo apt remove gns3-server
+
+# Mark dependencies as manual to prevent autoremove deletion
+sudo apt-mark manual ubridge dynamips vpcs libvirt
+```
+
+### 4. Install and Start Docker
+
+```bash
+sudo apt install docker.io
+sudo systemctl enable --now docker
+```
+
+#### Configure Docker Mirror Accelerator (China Mainland)
+
+If Docker Hub is inaccessible, configure mirror accelerators:
+
+```bash
+sudo mkdir -p /etc/docker
+sudo tee /etc/docker/daemon.json <<'EOF'
+{
+  "registry-mirrors": [
+    "https://docker.1ms.run",
+    "https://docker.xuanyuan.me"
+  ]
+}
+EOF
+sudo systemctl daemon-reload
+sudo systemctl restart docker
+```
+
+Verify:
+
+```bash
+docker info | grep -i mirror
+```
+
+### 5. Add User to Groups
+
+```bash
+# If running as gns3 user (created by PPA install):
+sudo usermod -aG ubridge,docker,kvm gns3
+
+# If running as your own user, add yourself to these groups:
+sudo usermod -aG ubridge,docker,kvm $USER
+
+# Then logout and login again for group membership to take effect
+```
+
+### 6. Install Python venv
+
+```bash
+sudo apt install python3.12-venv
+```
+
+### 7. Run Development Version from Source
+
+Clone the repository (official or your fork):
+
+```bash
+# Official repository
+git clone https://github.com/GNS3/gns3-server.git
+
+# Or your forked repository
+git clone https://github.com/yourname/gns3-server.git
+cd gns3-server
+git checkout your-branch
+```
+
+Setup virtual environment and install dependencies:
+
+```bash
+python3 -m venv venv
+source venv/bin/activate
+
+# For China mainland users, use mirror:
+# pip install -e . -i https://mirrors.aliyun.com/pypi/simple/
+
+pip install -e . && gns3server-web-wireshark-setup
+pip install -e .[ai-features]
+pip install -e .[dev]
+```
+
+Run the server:
+
+```bash
+python3 -m gns3server
+```
+
+## Optional: Install AI Features Development Dependencies
+
+```bash
+python3 -m pip install .[ai-features,dev]
+```
+
+## Optional: Expand LVM Root Partition
+
+If the root partition is low on space but the volume group has unallocated space:
+
+Check LVM status:
+
+```bash
+sudo lvm pvdisplay
+sudo lvm vgdisplay
+sudo lvm lvdisplay
+```
+
+Extend the root LV using all free space:
+
+```bash
+sudo lvm lvextend -l +100%FREE /dev/mapper/ubuntu--vg-ubuntu--lv
+sudo resize2fs /dev/mapper/ubuntu--vg-ubuntu--lv
+```
+
+Verify:
+
+```bash
+df -h
+```

docs/features/api-error-responses.md

@@ -0,0 +1,80 @@
+# API Error Response Format
+
+## Overview
+
+GNS3 Server uses a unified error response format across all API endpoints. All error responses return a JSON object with a `message` field containing the error details.
+
+## Response Format
+
+```json
+{
+  "message": "Error description here"
+}
+```
+
+## Error Types
+
+| Error Type | HTTP Status | Description |
+|------------|-------------|-------------|
+| `ControllerBadRequestError` | 400 | Invalid request parameters (e.g., validation failure) |
+| `ControllerUnauthorizedError` | 401 | Missing or invalid authentication |
+| `ControllerForbiddenError` | 403 | User lacks required privileges |
+| `ControllerNotFoundError` | 404 | Resource not found |
+| `ControllerError` | 409 | General conflict (e.g., duplicate name) |
+| `ControllerTimeoutError` | 408 | Operation timed out |
+| `ComputeConflictError` | 409 | Compute node returned a conflict |
+| `RequestValidationError` | 422 | Pydantic/FastAPI validation error (field missing or type mismatch) |
+| `SQLAlchemyError` | 500 | Database error |
+
+## Error Response Examples
+
+### Template Already Exists (409)
+```json
+{
+  "message": "A template with name 'my-template' already exists"
+}
+```
+
+### Validation Error (422)
+```json
+{
+  "message": "image field is required"
+}
+```
+
+### Permission Denied (403)
+```json
+{
+  "message": "Permission denied (privilege Template.Allocate is required)"
+}
+```
+
+### Invalid Template Type (400)
+```json
+{
+  "message": "JSON schema error received while creating new template: ..."
+}
+```
+
+## Client-Side Error Handling
+
+When handling errors in the GNS3 Web UI or API clients:
+
+```javascript
+// Extract error message from response
+function extractErrorMessage(error) {
+  if (error.error && error.error.message) {
+    return error.error.message;
+  }
+  if (error.message) {
+    return error.message;
+  }
+  return 'Unknown error';
+}
+```
+
+## References
+
+- Exception handlers: `gns3server/api/server.py`
+- Template validation: `gns3server/schemas/controller/templates/`
+- Error classes: `gns3server/controller/controller_error.py`

docs/features/builtin-ethernet-switch-ubridge.md

@@ -0,0 +1,262 @@
+<!--
+SPDX-License-Identifier: CC-BY-SA-4.0
+See LICENSE file for licensing information.
+-->
+
+> This documentation is AI-generated with reference to actual code and verified
+> against real-kernel testing (Linux 7.1.2-1-default). AI can make mistakes —
+> please verify against the source code when in doubt.
+
+# Builtin Ethernet Switch — uBridge brctl Backend
+
+## Overview
+
+The historical GNS3 Ethernet Switch was an emulated L2 device inside Dynamips
+(`ethsw`). This implementation replaces it with a **real Linux kernel bridge**
+driven through uBridge's `brctl` module — one bridge per switch node.  The
+migration makes the switch a first-class builtin node (no Dynamips dependency)
+and enables native-kernel-speed L2 switching with VLAN filtering and QinQ.
+
+| | Old (Dynamips ethsw) | New (uBridge brctl) |
+|---|---|---|
+| Switching engine | Dynamips user-space emulation | Linux kernel bridge (netlink) |
+| VLAN model | ethsw ACL per port | Kernel VLAN filtering + PVID/untagged |
+| QinQ | 0x8100/0x88A8/0x9100/0x9200 | 0x8100 (802.1Q) / 0x88A8 (802.1ad) |
+| Data path | Node NIO ↔ ethsw NIO (Dynamips) | Node NIO ↔ uBridge relay ↔ TAP ↔ kernel bridge |
+| Console | Inactive (reserved TCP port) | None (console_type=none) |
+| Node type | `dynamips`-routed | `builtin` (always-on) |
+
+## Architecture
+
+```
+  ┌───────────┐     ┌──────────────┐     ┌───────────────┐     ┌───────────┐
+  │  Peer A   │     │   uBridge    │     │  Kernel       │     │  Peer B   │
+  │ (Dynamips │◄───►│  per-port    │◄───►│  Bridge       │◄───►│ (IOU /    │
+  │  / IOU /  │ UDP │  relay       │ TAP │  gns3{id[:6]}│ TAP │ QEMU / …) │
+  │  QEMU)   │     │  nio_tap↔udp │     │  vlan_filter  │     │           │
+  └───────────┘     └──────────────┘     └──────┬────────┘     └───────────┘
+                                                │
+                                          ┌─────┴─────┐
+                                          │ ... more   │
+                                          │ ports      │
+                                          └───────────┘
+```
+
+Each switch port is a **dual-role TAP** — uBridge holds the file descriptor as a
+`nio_tap` relay endpoint, and the same TAP is enslaved to the kernel bridge via
+`brctl addif`.  This is the same pattern the Cloud node already uses for host
+bridges (`cloud.py:_add_linux_ethernet`).  uBridge is **only** the per-port UDP
+transport; the kernel bridge performs the actual MAC learning, forwarding, and
+VLAN filtering.
+
+### Component map
+
+| File | Role |
+|------|------|
+| `compute/builtin/nodes/ethernet_switch.py` | Node implementation |
+| `api/routes/compute/ethernet_switch_nodes.py` | REST endpoints (repointed to Builtin) |
+| `schemas/compute/ethernet_switch_nodes.py` | Request/response models (unchanged) |
+| `controller/udp_link.py` | Link creation — pushes NIO to switch via standard adapter endpoint |
+
+## Lifecycle
+
+### `create()` → `start()`
+
+1. `_start_ubridge(require_privileged_access=True)` — launch uBridge instance
+2. `_ensure_bridge()`:
+   - Derive deterministic bridge name: `gns3` + first 6 hex chars of `self.id`
+   - `brctl delete` (best-effort — crash recovery, cleans stale interfaces)
+   - `brctl create`
+   - `link set … up` (bridge is DOWN after create)
+   - `brctl vlanfiltering … on`
+
+### `add_nio(nio, port_number)`
+
+Per port, one uBridge relay bridge `{node_id}-{port}` is wired:
+
+```
+bridge create {node_id}-{port}
+bridge add_nio_tap {node_id}-{port} "{tap}"          ← uBridge holds TAP fd
+brctl addif "{bridge}" "{tap}"                       ← enslave to kernel bridge
+brctl vlan_del/vlan_add …                            ← apply port VLAN mode
+bridge add_nio_udp {node_id}-{port} lport rhost rport
+bridge reset_packet_filters {node_id}-{port}          ← from _ubridge_apply_filters
+bridge start {node_id}-{port}
+```
+
+Captures and marker signals are applied via the existing `_ubridge_apply_filters`
+and `_ubridge_apply_markers` helpers from `BaseNode`.
+
+### `remove_nio(port_number)`
+
+```
+brctl delif "{bridge}" "{tap}"
+bridge delete {node_id}-{port}
+release_udp_port(nio.lport)
+```
+
+### `close()`
+
+```
+for each port: release UDP port
+brctl delete "{self._bridge_name}"     ← kernel bridge teardown
+_stop_ubridge()                        ← destroys remaining TAPs
+```
+
+**Cleanup paths:**
+
+| Scenario | Bridge cleanup | TAP cleanup |
+|----------|---------------|-------------|
+| Normal project close | `close()` → `brctl delete` | uBridge stops → TAP fd closed → kernel destroys |
+| gns3server crash / kill | Next `_ensure_bridge()` → `brctl delete` before `create` | uBridge dies → TAP fd closed by kernel |
+| Manual project-file deletion after crash | Leaked (no GNS3 record of `gns3{id[:6]}`) | Leaked (same — but uBridge probably dead, TAPs gone with it) |
+
+## Port mode → VLAN translation
+
+All VLAN operations ride on the `brctl` hypervisor module (`../ubridge/doc/brctl.md`).
+The kernel bridge must have `vlan_filtering on` before any `vlan_*` call.
+
+### access VLAN N
+
+```
+brctl vlan_del {br} {tap} 1          ← remove default PVID 1
+brctl vlan_add {br} {tap} N pvid untagged
+```
+
+### dot1q trunk (native VLAN V)
+
+A dot1q trunk in ESW is "admit all VLANs tagged, native VLAN PVID + untagged":
+```
+brctl vlan_del {br} {tap} 1
+brctl vlan_add {br} {tap} 1 vid 4094     ← admit all VIDs tagged
+brctl vlan_add {br} {tap} V pvid untagged ← override native
+```
+
+### qinq (outer VLAN O, ethertype 0x88A8)
+
+Bridge-level (once):
+```
+brctl setvlanproto {br} 0x88a8          ← switch to 802.1ad (outer S-tag)
+```
+
+Port-level:
+```
+brctl vlan_del {br} {tap} 1
+brctl vlan_add {br} {tap} O pvid untagged  ← S-tag push for untagged ingress
+```
+
+Ethertype 0x8100 qinq ports are treated as plain access ports (the bridge
+defaults to 0x8100; no `setvlanproto` needed).  Ethertype 0x9100/0x9200 are
+not supported by the kernel bridge — see § Limitations.
+
+### Runtime reconfiguration (`update_port_settings`)
+
+On `ports_mapping` update, existing port VLANs are reset before re-apply:
+```
+brctl delif {br} {tap}                  ← release from bridge (clears VLAN state)
+brctl addif {br} {tap}                  ← re-enslave (resets to default PVID 1)
+brctl vlan_del/vlan_add …               ← apply new mode
+```
+
+This prevents stale VLAN membership from a previous mode leaking into the new
+configuration (e.g., access→trunk transition leaving old access VLAN behind).
+
+## Bridge naming
+
+Deterministic from the switch's UUID: `gns3` + first 6 hex chars (no dashes).
+
+```
+gns3a1b2c3          ← bridge (10 chars, ≤ 15 IFNAMSIZ limit)
+gns3a1b2c3-0        ← tap for port 0 (12 chars)
+gns3a1b2c3-1        ← tap for port 1 (12 chars)
+```
+
+- 6 hex = 48 bits of entropy — collision risk is astronomically low even with
+  thousands of switches on the same host.
+- **Crash recovery**: `brctl delete` (best-effort, ignore if not found) then
+  `brctl create` — stale interfaces from a previous abnormal shutdown are
+  reclaimed automatically when the switch is re-created.
+
+## Controller integration
+
+No controller or API contract changes are required. The migration is entirely
+compute-internal:
+
+- `node_types.BUILTIN_NODE_TYPES` already classified `ethernet_switch` as a
+  builtin, always-running node.
+- `udp_link.create()` pushes the NIO to the switch via the standard
+  `POST /adapters/0/ports/{p}/nio` endpoint (same as Dynamips).
+- The REST API paths, request/response schemas, and port model
+  (`EthernetSwitchPort`: type/vlan/ethertype) are unchanged.
+- `/start`, `/stop`, `/suspend`, `/reload` return 405 (switch is always-on).
+
+The sole observable difference: the `console` field in the response is now
+`null` (the switch has no console; `console_type="none"` makes `BaseNode`
+skip TCP port reservation).  The old Dynamips ethsw returned an unused TCP
+port number.  Both are valid under `Optional[int]`.
+
+## Known limitations
+
+### Default PVID 1 must be deleted explicitly
+
+A port freshly enslaved to a `vlan_filtering` bridge inherits default PVID 1
+(PVID + Egress Untagged).  Access/trunk mode application must issue
+`vlan_del … 1` first — `vlan_add … pvid` moves the PVID but does not remove
+the old PVID's membership.  This matches iproute2 semantics and is documented
+in `../ubridge/doc/brctl.md#limitations`.
+
+### QinQ is outer-tag (S-VLAN) only
+
+With `setvlanproto 0x88a8` the bridge filters on the outer S-tag; the inner
+C-tag passes through transparently.  Selective QinQ (inner-VLAN classification
+or remapping) requires `IFLA_BRIDGE_VLAN_TUNNEL_INFO` which is not implemented.
+Documented in `../ubridge/doc/brctl.md#limitations`.
+
+### Ethertype 0x9100 / 0x9200
+
+The GNS3 schema allows legacy QinQ ethertypes `0x9100` and `0x9200`, but the
+Linux kernel bridge only supports `0x8100` (802.1Q) and `0x88a8` (802.1ad).
+Configuring these on a qinq port produces a `NodeError` at creation/update
+time.  Handling policy (map to 0x88A8 + warn vs. reject with error) is
+pending per design discussion.
+
+### No FDB read/write
+
+The `brctl` module exposes no `fdb_show`/`fdb_flush`.  The kernel bridge
+learns and ages MAC entries autonomously; uBridge has never exposed MAC-table
+access and gns3-server does not consume it.  Consumers that need the FDB
+(e.g., a WebUI switch view) should read `/sys/class/net/<br>/brforward` or
+`bridge fdb show dev <br>` directly, without uBridge involvement.
+
+## Troubleshooting
+
+### Docker iptables: FORWARD chain DROP
+
+Docker sets the iptables `FORWARD` chain default policy to `DROP` when the
+Docker daemon starts.  This blocks **all** forwarded traffic through kernel
+bridges on the host, including `gns3*` bridges.
+
+**Symptoms**: nodes can send frames into the bridge (visible in `tcpdump -i
+gns3*`) but never receive unicast replies.  ARP and multicast may work
+because they flood, but unicast forwarding silently fails.
+
+**Fix**:
+```bash
+sudo iptables -P FORWARD ACCEPT
+```
+
+### Bridge left DOWN after creation
+
+`brctl create` creates the bridge but leaves it administratively DOWN.
+The node now sends `link set … up` after `brctl create`.  If forwarding
+is not working, verify:
+```bash
+ip -d link show gns3* | grep -E "state|vlan_filtering"
+```
+
+### Kernel version differences
+
+This implementation has been tested on Linux 7.1.2-1-default (x86_64) with
+uBridge installed via `make install` (cap_net_admin,cap_net_raw=ep).  The
+ubridge `brctl` module has a 168-test suite covering kernel-side VLAN
+behaviour on this kernel.

docs/features/compute-controller-setup.md

@@ -0,0 +1,146 @@
+<!--
+SPDX-License-Identifier: CC-BY-SA-4.0
+See LICENSE file for licensing information.
+-->
+
+> This documentation is organized by AI with reference to actual code. AI can make mistakes — please verify against the source code when in doubt.
+
+
+# Controller + Compute Setup
+
+This document describes the minimum configuration required to set up a GNS3 Controller with remote Compute nodes.
+
+## Architecture Overview
+
+- **Compute**: Runs individual nodes (QEMU, Docker, etc.) and provides resource monitoring
+- **Controller**: Manages multiple computes, projects, and provides the REST API
+- **Database**: Controller uses SQLite to store projects, nodes, and compute registration
+
+## Minimum Configuration
+
+### 1. Compute Node Configuration
+
+Create the configuration file at `~/.config/GNS3/3.1/gns3_server.conf`:
+
+```ini
+[Server]
+host = 0.0.0.0
+port = 3080
+compute_username = gns3
+compute_password = gns3
+```
+
+Start the Compute:
+```bash
+gns3server
+```
+
+### 2. Controller Node Configuration
+
+Create the configuration file at `~/.config/GNS3/3.1/gns3_server.conf`:
+
+```ini
+[Server]
+host = 192.168.1.140
+port = 3080
+compute_username = gns3
+compute_password = gns3
+```
+
+Start the Controller:
+```bash
+gns3server
+```
+
+### 3. Register Compute with Controller
+
+Use the API to register a remote compute:
+
+```bash
+POST /v3/computes
+{
+  "protocol": "http",
+  "host": "192.168.1.x",
+  "port": 3080,
+  "user": "gns3",
+  "password": "gns3"
+}
+```
+
+## Important Notes
+
+### Host Configuration
+
+- **Controller `host`**: If set to `0.0.0.0`, the controller will register itself as `127.0.0.1`, which breaks remote compute connections
+- **Symptom**: Compute nodes report "No common subnet for compute X (controller) and Y" even when on the same network
+- **Solution**: Always use the actual LAN IP address for the Controller's `host` field (e.g., `host = 192.168.1.104`)
+- **Dynamic IP**: If the controller machine uses DHCP, set a static lease on the router or use mDNS (`.local` domain)
+
+### Password Configuration
+
+- If `compute_password` is not set, a random 16-character password is auto-generated on startup
+- The Controller must use the same credentials as the Compute's configuration
+
+### Network Requirements
+
+- Controller and Compute must be on the same LAN for cross-compute links to work
+- UDP tunnel is used for cross-compute links, requiring network connectivity on UDP ports
+
+### Configuration File Location
+
+- Default location: `~/.config/GNS3/3.1/gns3_server.conf`
+- Version `3.0` uses `~/.config/GNS3/3.0/`
+
+## Troubleshooting
+
+### 401 Unauthorized on Compute Connect
+
+1. Check that Compute's `compute_username` and `compute_password` match what was passed to the API
+2. Verify the Compute's configuration file is correctly loaded
+3. Ensure the `[Server]` section is used (not `[Controller]`)
+
+### No Common Subnet Error
+
+If compute nodes report:
+```
+Cannot get an IP address on same subnet: No common subnet for compute X (controller) and Y
+```
+
+1. **Primary cause**: Controller's `host` is set to `0.0.0.0` - it registers as `127.0.0.1` which is unreachable from compute nodes
+2. Check the controller's `/v3/version` endpoint - if `controller_host` shows `127.0.0.1`, this is the issue
+3. Set the Controller's `host` to its actual LAN IP address (e.g., `192.168.1.104`)
+4. Verify both machines are on the same network and can ping each other
+5. Check firewall rules allow TCP/UDP communication on required ports
+
+### WebSocket Console Authentication Failed
+
+When connecting to a remote compute node's console via WebSocket, the connection may fail with errors in the logs:
+
+**Controller log:**
+```
+New client 192.168.1.104:33268 has connected to controller console WebSocket
+Forwarding console WebSocket to 'ws://192.168.1.3:3080/v3/compute/projects/.../console/ws'
+Client 192.168.1.104:33268 has disconnected from controller console WebSocket
+```
+
+**Compute log:**
+```
+WebSocket /v3/compute/projects/.../console/ws" [accepted]
+ERROR gns3server.api.routes.compute.dependencies.authentication:103 Could not authenticate while connecting to compute WebSocket: Could not validate credentials
+```
+
+**Cause**: The Controller forwards its own `compute_username` and `compute_password` credentials when connecting to the Compute's WebSocket endpoint. If the Compute node does not have matching credentials configured, authentication fails.
+
+**Solution**: Ensure the Compute node's configuration file has matching credentials:
+
+```ini
+[Server]
+enable_http_auth = True
+compute_username = gns3
+compute_password = your_password
+```
+
+The Controller automatically uses its configured `compute_username` and `compute_password` when establishing WebSocket connections to remote computes (see `gns3server/api/routes/controller/nodes.py` lines 627-628).
+
+**Note**: If `compute_password` is not explicitly set in the Compute's config, a random 16-character password is auto-generated at startup, making authentication impossible for any external Controller.
+

docs/features/docker-exec-console.md

@@ -0,0 +1,465 @@
+<!--
+SPDX-License-Identifier: CC-BY-SA-4.0
+See LICENSE file for licensing information.
+-->
+
+> This documentation is organized by AI with reference to actual code. AI can make mistakes — please verify against the source code when in doubt.
+
+
+# Docker exec Console (Vendor NOS Containers)
+
+## Overview
+
+GNS3 Docker nodes normally expose their console by attaching to the container's
+PID 1 stdio. That works for CLIs that run as PID 1 (e.g. FRR's `vtysh`), but it
+does **not** work for vendor NOS containers (Nokia SR Linux, Arista cEOS,
+Juniper cRPD, …) whose CLI is a separate, full-screen TUI process that is *not*
+on PID 1. For those, attaching to PID 1 only shows boot logs and never yields a
+CLI prompt.
+
+The `docker_exec` console type solves this. It runs a chosen command inside the
+running container via the Docker exec API (with a pty) and bridges it to the
+GNS3 console, so the vendor's native TUI CLI renders in the Web UI (xterm.js)
+exactly as if you had run `docker exec -it <container> <cli>` in a real
+terminal.
+
+Two companion environment knobs (`GNS3_SKIP_INIT`, `GNS3_INTERFACE_NAMES`) make
+the container itself boot and wire correctly for vendor NOS images. Together
+they let a vendor NOS run as a first-class GNS3 Docker router node.
+
+> Prototype status: the knobs are environment-driven and intentionally avoid
+> schema changes, so existing Docker nodes (FRR, ipterm, …) are unaffected.
+> `console_type: "docker_exec"` is added to the `ConsoleType` enum.
+
+## The three environment knobs
+
+All three are read from the node's `environment` field. Entries prefixed with
+`GNS3_` are **not** forwarded into the container (existing GNS3 behaviour), so
+they stay host-side configuration.
+
+| Variable | Purpose |
+|----------|---------|
+| `GNS3_SKIP_INIT=1` | Do **not** prepend `/gns3/init.sh` to the entrypoint. Vendor NOS images must run their own entrypoint (e.g. SR Linux's `sr_linux`); GNS3's init script (busybox bootstrap, `ifup`, eth wait) interferes with them. |
+| `GNS3_INTERFACE_NAMES=mgmt0,e1-1,e1-2,e1-3` | Rename the injected interfaces in adapter order instead of the default `eth{N}`. SR Linux expects `mgmt0` + `e1-N`; without this it does not recognise its datapath. |
+| `GNS3_CONSOLE_CMD=/opt/srlinux/bin/sr_cli` | Command run by the `docker_exec` console inside the container. |
+
+## Architecture: `VendorDockerVM` subclass
+
+All vendor-specific logic lives in a `VendorDockerVM(DockerVM)` subclass in
+`gns3server/compute/docker/vendor_docker_vm.py` — `docker_vm.py` itself stays
+on its baseline behaviour and is never touched by this feature.
+
+`DockerVM` exposes four small extension hooks (pure refactorings, zero
+behaviour change for existing nodes):
+
+| Hook | Baseline behaviour | `VendorDockerVM` override |
+|------|--------------------|---------------------------|
+| `_prepare_init_and_interface_env(params)` | prepend `/gns3/init.sh`, set `GNS3_MAX_ETHERNET=eth{N-1}` | conditional init.sh (`GNS3_SKIP_INIT`), `GNS3_MAX_ETHERNET` follows the interface rename |
+| `_start_console_server()` | telnet/ssh/http console dispatch | adds the `docker_exec` branch |
+| `_get_container_ifname(adapter_number)` | `eth{N}` | `GNS3_INTERFACE_NAMES` lookup, fallback `eth{N}` |
+| `_cleanup_console_resources()` | no-op | closes the docker-exec pty socket before restart/stop |
+
+### Class selection
+
+The Docker manager picks the class per node in `Docker.create_node()`
+(`gns3server/compute/docker/__init__.py`):
+
+```python
+def _select_node_class(self, **kwargs):
+    if kwargs.get("console_type") == "docker_exec":
+        return VendorDockerVM
+    return DockerVM
+```
+
+`console_type == "docker_exec"` is the **only** trigger — every other console
+type (telnet, vnc, ssh, http, …) keeps using the unmodified `DockerVM`. All
+vendor features are opt-in: without the `GNS3_*` environment variables a
+`VendorDockerVM` instance behaves identically to `DockerVM` (init.sh still
+runs, interfaces stay `eth{N}`, the exec command defaults to `/bin/sh`), so a
+regular container can use `docker_exec` too.
+
+## The `docker_exec` console type
+
+Setting `console_type: "docker_exec"` makes the node's primary console port run
+`_start_docker_exec_console()` instead of the attach-to-PID-1 path.
+
+### Console architecture
+
+```mermaid
+graph LR
+    A[Web UI xterm.js] -->|console WS| B[GNS3 Compute telnet server]
+    B -->|binary pty stream| C[Docker exec API]
+    C -->|Tty:true pty| D[sr_cli / vendor CLI]
+    A -.->|NAWS size| B
+    B -.->|POST exec/.../resize| C
+```
+
+The console uses GNS3's **existing shared/broadcast telnet model**: a single
+exec instance (one CLI session) is broadcast to every console client, exactly
+like the primary console shares one PID 1. There is deliberately **no
+per-client session isolation** — this matches how every other GNS3 console
+behaves.
+
+### Implementation
+
+**File**: `gns3server/compute/docker/vendor_docker_vm.py` —
+`_start_docker_exec_console()`
+
+A small subclass `_LazyExecTelnetServer(AsyncioTelnetServer)` implements the
+console. Key points:
+
+1. **Lazy exec creation.** The exec is created on the **first client
+   connection** (`client_connected_hook`), not when the node starts. This is
+   essential: vendor CLIs (e.g. `sr_cli` via `prompt_toolkit`) send a
+   cursor-position request (`\e[6n`, CPR) during startup and block waiting for
+   the terminal's answer. If the exec starts at node-start time there is no
+   xterm.js client to answer, the probe times out, and the TUI degrades (no
+   status bar, "Terminal doesn't support CPR" warning). Creating the exec on
+   first connect means the probe runs with a real xterm.js attached, which
+   answers CPR → full TUI. After creation the exec is shared by all clients.
+
+2. **Exec API with a pty.** `POST containers/{cid}/exec` with
+   `Tty: true`, `User: "root"` (vendor CLIs reject the image's default
+   unprivileged user — SR Linux returns *"User 'user' is not authorized to use
+   CLI"* otherwise), and `Env: ["TERM=xterm"]` (the TUI library needs a
+   recognised terminal).
+
+3. **No while-true wrapper.** The command runs as `sh -c "<cmd>"` (no
+   restart loop). When the CLI exits (`quit`, the NOS's own idle timeout, or a
+   crash) the exec pty closes, the broadcast task ends, and the next client
+   connection **recreates** the exec (see *Reconnection*). A `while true`
+   wrapper would restart the CLI mid-session with no client attached to
+   answer its startup CPR probe, producing a blank/degraded screen on
+   reconnect.
+
+### Reconnection
+
+The exec is created lazily and **recreated on reconnect if it has died**.
+`client_connected_hook` checks `_upstream_alive()` (exec id set, writer open,
+broadcast task not done) before each connect:
+
+- **First connect / dead upstream** → (re)create the exec. Because a client is
+  now attached, the CLI's startup CPR probe is answered by xterm.js → full
+  TUI. A half-dead writer is closed first to avoid a socket leak.
+- **Live upstream** → reuse the existing exec, just send `Ctrl-L` to redraw
+  for the new client.
+
+This is what makes the console survive `quit`, idle timeout, and CLI
+crashes: the death is detected (pty EOF ends the broadcast task) and the
+next connection spins up a fresh exec with a terminal present. The
+`_LazyExecTelnetServer` is extracted to module level specifically so this
+reconnect logic is unit-tested.
+
+4. **Hijacked raw-HTTP start.** The exec is started with
+   `POST exec/{eid}/start` sent as a raw HTTP upgrade over the Docker unix
+   socket (`asyncio.open_unix_connection`), the same approach docker-py uses.
+   This is required because aiohttp's websocket client (`ws_connect`) is
+   rejected by Docker's exec-start endpoint (HTTP 400), while a raw POST
+   upgrade succeeds (101). With `Tty:true` the response body is a raw,
+   non-multiplexed bidirectional pty byte stream — no frame demux needed.
+
+5. **NAWS → exec resize.** The telnet server runs with `naws=True`; the
+   `window_size_changed_callback` calls `POST exec/{eid}/resize?h=&w=` so the
+   TUI lays out for the xterm.js window size.
+
+6. **Binary passthrough + redraw.** `binary=True` so TUI escape sequences reach
+   xterm.js intact; `echo=False` (the pty echoes). On every client (re)connect
+   a `Ctrl-L` (`\x0c`) is sent to the pty so a TUI that already drew its
+   screen for a previous client redraws for the new one (otherwise a
+   reconnect shows a blank screen until the next output).
+
+**File**: `gns3server/compute/base_node.py` — the console WebSocket guard now
+allows `docker_exec` (alongside `telnet`/`ssh`), since the WS bridge connects to
+the console TCP port exactly as it does for telnet.
+
+### Why earlier approaches failed (context)
+
+- `script` + `docker exec -it`: the `script` pty had size 0 (no NAWS) → the TUI
+  could not lay out → blank.
+- `docker exec -i` (no `-t`) + `sr_cli -d` (dumb mode): line-mode output was
+  block-buffered and visually messy.
+- Direct pipe relay: telnet `CRLF` polluted line input.
+
+The exec-API approach fixes all of these: a real pty (`Tty:true`), a real size
+(NAWS resize), and a real terminal emulator (xterm.js answering CPR).
+
+## Configuration
+
+### SR Linux node example
+
+```json
+{
+  "name": "srlinux-1",
+  "node_type": "docker",
+  "image": "ghcr.io/nokia/srlinux:latest",
+  "adapters": 4,
+  "console_type": "docker_exec",
+  "start_command": "sudo -E bash -c 'touch /.dockerenv && /opt/srlinux/bin/sr_linux'",
+  "environment": "GNS3_SKIP_INIT=1\nGNS3_INTERFACE_NAMES=mgmt0,e1-1,e1-2,e1-3\nGNS3_CONSOLE_CMD=/opt/srlinux/bin/sr_cli"
+}
+```
+
+- `start_command` is the SR Linux launch line (as used by containerlab).
+- Connect the node's ports as usual — links still use GNS3's UDP NIO datapath
+  (container-agnostic); the rename only affects the in-container interface name.
+- For the Web UI port **labels** to match (display `mgmt0`/`e1-1` instead of
+  `Ethernet0..3`), set `custom_adapters` per port
+  (`{"adapter_number": 0, "port_name": "mgmt0"}`, …). Port labels are a
+  controller-side concept, independent of the compute-side interface rename.
+
+### Appliance (`gns3a`) packaging
+
+A SR Linux appliance lives in `gns3-registry/appliances/srlinux.gns3a`
+(`registry_version: 6`). It sets the full chassis — **35 adapters**
+(`mgmt0` + `e1-1`..`e1-34`) — with matching `GNS3_INTERFACE_NAMES` and 35
+`custom_adapters` entries (`mgmt0`, `e1-1`..`e1-34`) so the canvas labels,
+the kernel interface names and the `ethernet-1/N` CLI names all line up.
+
+Three appliance-schema fixes are required for this appliance to load (all on
+the gns3-server side; the registry JSON schema is unchanged because its docker
+block allows `additionalProperties`):
+
+1. **`DockerConsoleType`** (`schemas/controller/appliances.py`) must include
+   `docker_exec`, or the Pydantic appliance model rejects the file at import.
+2. **`ApplianceV1_6.custom_adapters`** must be declared on the top-level
+   appliance model, or `GET /appliances` (response_model=`schemas.Appliance`)
+   strips `custom_adapters` from the API response even though the file and the
+   server-side template conversion handle it. (Node creation still worked
+   because `appliance_to_template._add_docker_config` reads it from the raw
+   dict; only the GET response was lossy.)
+3. `extra_volumes` rides inside the `docker` block (passed through by
+   `new_config.update(appliance_config["docker"])`); no schema change needed.
+
+> **Symbol theme caveat.** An appliance `symbol` that starts with
+> `:/symbols/` is forcibly rewritten at load time
+> (`appliance_manager._load_appliances`) to the current theme's default for the
+> appliance category — so `:/symbols/affinity/circle/blue/router_cloud.svg` (or
+> `router2.svg`) becomes `:/symbols/affinity/circle/blue/router.svg`, because
+> the theme maps only the canonical name `"router"`. This is intentional: it
+> lets theme switching re-skin every node consistently. To use a non-default
+> icon (e.g. `router_cloud`), install it as a **custom symbol** under the
+> configured `symbols_path` and reference it by filename (no `:/symbols/`
+> prefix) — custom symbols do not participate in re-theming. The SR Linux
+> appliance uses `router.svg`.
+
+### Persistent state
+
+For SR Linux, persist `/etc/opt/srlinux` (config / AAA users / TLS certs) and
+`/var/log/srlinux` (logs, optional) by adding them to the node's
+`extra_volumes`. The image also declares its own `VOLUME` directories
+(e.g. `/opt/srlinux/appmgr`), which GNS3 persists automatically.
+
+## Volume persistence with `GNS3_SKIP_INIT`
+
+This is the one place where skipping init.sh changes behaviour beyond boot:
+`/gns3/init.sh` normally performs the volume-persistence bridge, and without it
+**nothing writes through to the host** — the container writes to its overlay
+filesystem and the data is lost on stop.
+
+The bridge (see init.sh lines 35–52) has two parts:
+
+```
+host  ──Docker bind mount──▶  /gns3volumes/etc/opt/srlinux   (always mounted)
+                                  │  init.sh: mount --bind
+                                  ▼
+                              /etc/opt/srlinux               (where the NOS writes)
+```
+
+`VendorDockerVM` replicates this for SKIP_INIT containers:
+
+1. **`_setup_skip_init_volumes()`** — runs once per start, right after the
+   container is up (`VendorDockerVM.start()`). For each persistent volume it
+   `docker exec`s a busybox script that:
+   - seeds the host directory with the container's original files on first
+     start (`cp -a` + `.gns3_perms` marker), exactly like init.sh;
+   - `mount --bind /gns3volumes<path> <path>` to bridge persistent storage
+     back to the in-container path — on subsequent starts the persisted data
+     replaces the fresh overlay content;
+   - restores the permissions recorded in `.gns3_perms` at the previous stop
+     (best-effort).
+
+2. **Container-side `_fix_permissions()` override targeting `/gns3volumes`**
+   — `DockerVM._fix_permissions` operates on the in-container paths
+   (`/etc/opt/srlinux`, …), which only resolve to persistent storage while
+   the `mount --bind` bridge is up; after a container restart the bridge is
+   gone and it would chown the overlay copy instead of the host files. It
+   also restarts an exited container just to chown. The override instead
+   runs the same busybox record/chmod/chown script **inside the container
+   (as root) on the `/gns3volumes<path>` paths** — the Docker bind-mount
+   targets, which exist for the whole container lifetime and need no bridge.
+   A stopped/exited container is **not** restarted: the pass is skipped and
+   the next start fixes ownership. It runs at start (so the controller can
+   read project files while the node runs) and at stop (for files written
+   during runtime).
+
+> The fix must run container-side: files written by the container are
+> host-side root-owned, and an unprivileged GNS3 process cannot chown them
+> from the host. Container-side root (with GNS3's `UsernsMode: host`) can.
+
+With `GNS3_SKIP_INIT`, GNS3's hardcoded `/etc/network` volume (see
+`docker_vm.py` `_mount_binds()`) is dropped entirely by
+`VendorDockerVM._mount_binds()`: it holds GNS3's own network config for
+init.sh's `ifup`, which never runs for SKIP_INIT containers — the NOS
+manages its own interfaces. The override removes the bind, filters the
+volume out of `self._volumes`, and deletes the host-side skeleton directory
+the base class just created. Without `GNS3_SKIP_INIT` the mount is kept
+(behaviour matches the base class).
+
+### Lifecycle summary
+
+| Phase | Normal Docker node | `VendorDockerVM` + `GNS3_SKIP_INIT` |
+|-------|--------------------|--------------------------------------|
+| start | init.sh seeds + bind-mounts + restores perms (in-container, before the app starts) | `docker exec` after start: seed + bind-mount + restore perms; then container-side chown on `/gns3volumes` |
+| stop | container-side `_fix_permissions` on in-container paths (restarts an exited container) | container-side `_fix_permissions` on `/gns3volumes` paths (skips dead containers, no restart) |
+| volume config | identical `_mount_binds` (host → `/gns3volumes<path>`) | identical |
+
+### Runtime ownership safety
+
+The start-time fix pass chowns the volume files to the host user **while the
+container is running** — a deliberate deviation from the standard model, where
+init.sh restores container-native ownership at start and the container never
+sees host-owned files during runtime. Verified harmless for SR Linux:
+
+1. **Most processes run as root** (`sr_linux`, appmgr) — root ignores file
+   ownership entirely.
+2. **Self-healing daemons.** SR Linux's `aaamgr` rewrites its managed files
+   with its own ownership at boot: after the start-time pass chowned
+   `etc/opt/srlinux/aaamgr_local_user.json` to the host user, the daemon
+   re-created it as `srlinux:srlinux` (uid 1002, mode 700) within seconds.
+3. **ACL-based access.** The directory carries a default ACL
+   (`default:group:srlinux:rwx`, `default:other::rwx`), so named group ACL
+   entries grant access independently of the owner uid; the observed file ACL
+   (`group:srlinux:rwx`, owner `srlinux`) survives chown.
+
+Caveat: a NOS that strictly validates ownership of its files (e.g. "SSH keys
+must be root:root 600 or refuse to start") would not tolerate this. If that
+ever matters, drop the start-time pass and keep only the stop-time one
+(standard behaviour — the trade-off is mid-run `Permission denied` in the
+file browser, identical to regular Docker nodes).
+
+### Boot-ordering caveat
+
+The volume bridge (`mount --bind`) is established **after** the vendor
+entrypoint has started (there is no init.sh to do it before), so the NOS's
+early boot reads the overlay copy of the volume paths — default image
+content, not the persisted data. Whether the persisted config takes effect
+depends on the NOS re-reading those files after the bridge is up (SR Linux's
+daemons do re-read/write their managed files during boot, as observed).
+Always verify the closed loop when adopting a new image: `save` a config →
+stop the node → start it → confirm the config is actually applied, not just
+present on the host.
+
+## Troubleshooting
+
+**1. Console shows only boot logs, no CLI**
+- You are on the primary attach console. Set `console_type: "docker_exec"` and
+  use `GNS3_CONSOLE_CMD` to point at the vendor CLI.
+
+**2. `User '...' is not authorized to use CLI`**
+- The exec must run as root. The implementation sets `User: "root"`; if you
+  fork it, keep that.
+
+**3. `Terminal doesn't support cursor position requests (CPR)`**
+- This means the exec was started without an xterm.js client connected (the
+  startup probe had no one to answer). The lazy-start design avoids this; if you
+  see it, ensure the exec is created on first connect, not at node start.
+
+**4. Reconnecting the Web console shows a blank screen**
+- A `Ctrl-L` is sent on each connect to force a TUI redraw. If the TUI does not
+  redraw, verify the `client_connected_hook` still writes `\x0c` to the pty.
+
+**5. `aiohttp WSServerHandshakeError: 400` on exec start**
+- Do **not** use the websocket client to start an exec. Use the hijacked raw
+  HTTP upgrade over the unix socket (see Implementation).
+
+**6. SR Linux data interfaces stay down**
+- SR Linux defaults its data ports to `admin-state disable`; enable them in the
+  CLI (`interface ethernet-1/1 admin-state enable`) and bind the interface to a
+  network-instance before ping works. This is SR Linux behaviour, not a GNS3
+  issue.
+
+**7. "Session has been idle, will logout in 300 seconds" → Connection closed**
+- SR Linux's own CLI idle timeout logs the CLI out, the exec pty closes, and
+  the console disconnects. Reopening the console recreates the exec (see
+  *Reconnection*) and gives a fresh login. To keep a permanent session,
+  disable the timeout in the CLI: `enter candidate` →
+  `/system cli idle-timeout disable` → `commit now`.
+
+**8. Controller logs `Permission denied` reading files under the node's
+   project directory while the node runs**
+- Root-written files inside a persistent volume. The container-side
+  `_fix_permissions` pass runs at start (fixes the seeded files) and at stop;
+  files created by the container *during* runtime become readable after the
+  next stop.
+- Concrete example: SR Linux's `aaamgr` daemon rewrites
+  `etc/opt/srlinux/aaamgr_local_user.json` during boot, **after** the
+  start-time pass, as the image's `srlinux` user (uid 1002, mode 700) — so
+  the host-side file stays `1002:1002` until the stop-time pass chowns it.
+- The log line comes from the file-browser API chain: Web UI *Show in file
+  manager* → `GET /v3/projects/{pid}/nodes/{nid}/files`
+  (`controller/nodes.py:538`) → `project.list_node_files`
+  (`compute/project.py:510`), where `magic.from_file()` cannot read the
+  file and the `file_type` field is left empty for that entry. The MCP
+  `list_node_files` tool uses the same code path. Size/modified-at fields
+  and everything else keep working; only the type sniff and one warning
+  line are affected — same behaviour as any regular Docker node writing
+  root-owned files at runtime.
+
+**9. Persistent volume empty on the host after `save` + stop**
+- Ensure `GNS3_SKIP_INIT=1` is set (so the host-side bridge path is taken) and
+  the volume path is in `extra_volumes`; check the compute log for
+  `Volume '<path>' bound to persistent storage`.
+
+**10. Persisted config present on the host but not applied after restart**
+- The volume bridge is established after the NOS has booted (see
+  *Boot-ordering caveat*); the NOS may have already loaded the overlay's
+  default config into memory. Verify with a visible change (hostname,
+  interface description): `save` → stop → start → check the change took
+  effect. If it does not, the image needs the bridge earlier (a
+  vendor-specific entrypoint wrapper, not covered by this prototype).
+
+## Limitations
+
+1. **Shared session (broadcast).** All console clients share one CLI session
+   and can see each other's input — identical to GNS3's existing primary
+   console model. There is no per-client independent session.
+2. **`reset_console` not wired.** The console-reset action only handles
+   `telnet`/`ssh`; it is a no-op for `docker_exec` (non-blocking; reconnect
+   works fine).
+3. **Prototype knobs.** `GNS3_SKIP_INIT` / `GNS3_INTERFACE_NAMES` /
+   `GNS3_CONSOLE_CMD` are environment-driven; they are not yet first-class node
+   schema fields and are not declared in the appliance (`gns3a`) schema.
+4. **Rootful-Docker assumption** (`UsernsMode: host`, set for all GNS3
+   Docker nodes) so the container-side chown acts on the host files' real
+   uid/gid (see the volume-persistence section).
+5. **Post-boot volume bridge.** The bind-mount bridge is established after the
+   vendor entrypoint has started (init.sh would do it before). A NOS that
+   strictly requires its persisted files at its very first read may need a
+   different boot arrangement (see *Boot-ordering caveat*).
+
+## References
+
+- `gns3server/compute/docker/vendor_docker_vm.py` — `VendorDockerVM`:
+  `_start_docker_exec_console`, `_LazyExecTelnetServer`,
+  `_setup_skip_init_volumes`, container-side `_fix_permissions` on
+  `/gns3volumes`, `start()`.
+- `gns3server/compute/docker/docker_vm.py` — `DockerVM` extension hooks
+  (`_prepare_init_and_interface_env`, `_start_console_server`,
+  `_get_container_ifname`, `_cleanup_console_resources`).
+- `gns3server/compute/docker/__init__.py` — `Docker._select_node_class` /
+  `create_node` factory.
+- `gns3server/compute/base_node.py` — console WebSocket guard.
+- `gns3server/schemas/common.py` — `ConsoleType.docker_exec`.
+- containerlab `nodes/srl/srl.go` — reference for SR Linux launch command and
+  interface naming.
+
+## Version History
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 1.5 | 2026-08-13 | Add appliance (`gns3a`) packaging section: 35-adapter full-chassis design, the three server-side schema fixes (DockerConsoleType, ApplianceV1_6.custom_adapters, extra_volumes passthrough), and the symbol-theme caveat (any `:/symbols/` symbol is rewritten to the category default at load). |
+| 1.4 | 2026-08-13 | Reconnect fix: drop the while-true wrapper (it restarted the CLI with no client to answer CPR → blank screen on reconnect); the exec is now recreated on connect when the upstream has died. `_LazyExecTelnetServer` extracted to module level and unit-tested. |
+| 1.3 | 2026-08-12 | Document runtime ownership safety (root processes, self-healing daemons, ACL evidence for SR Linux), the boot-ordering caveat (bridge after boot → verify save/stop/start closed loop), and troubleshooting #10. |
+| 1.2 | 2026-08-12 | `_fix_permissions` rewritten: container-side (as root) on the `/gns3volumes` bind-mount targets instead of host-side — host-side chown cannot touch root-owned files when GNS3 is unprivileged. Dead containers are skipped instead of restarted. |
+| 1.1 | 2026-08-12 | Refactor: vendor logic extracted from `DockerVM` into `VendorDockerVM` subclass with 4 hook points + class-selection factory. Add SKIP_INIT volume persistence (`_setup_skip_init_volumes` + `_fix_permissions`) and lifecycle comparison. Add troubleshooting entries for idle timeout and permission-denied files. |
+| 1.0 | 2026-08-12 | Initial documentation of the `docker_exec` console and vendor NOS knobs. |

docs/features/marker-traffic-insight.md

@@ -0,0 +1,378 @@
+<!--
+SPDX-License-Identifier: CC-BY-SA-4.0
+See LICENSE file for licensing information.
+-->
+
+> This documentation is organized by AI with reference to actual code. AI can make mistakes — please verify against the source code when in doubt.
+
+# Marker (Traffic Insight)
+
+## Overview
+
+A **marker** is a passive traffic-insight tap attached to a link. It runs a libpcap BPF
+expression inside uBridge; on every match uBridge emits a real-time `MARK` signal and
+appends the matching packet to a per-marker pcap file. Markers exist at two layers that
+coexist on the same link: **per-link private markers** and **project-level definitions**
+that are inherited by every capable link.
+
+## Architecture
+
+```mermaid
+graph TB
+    UI["Web UI"]
+
+    subgraph Controller["Controller"]
+        DEF["Project definitions<br/>(inheritance templates)"]
+        LNK["Per-link markers"]
+    end
+
+    Compute["Compute Node"]
+    UB["uBridge<br/>mark filter"]
+    PCAP[("pcap file")]
+    LSTN["Marker listener<br/>(UDP, per compute)"]
+
+    UI -->|"REST + notifications ws"| Controller
+    DEF -.->|"fan-out: global-{name}"| LNK
+    LNK -->|"node.post /markers"| Compute
+    Compute --> UB
+    UB -->|"BPF match"| PCAP
+    UB -->|"UDP MARK signal"| LSTN
+    LSTN -->|"marker.match"| UI
+```
+
+Inheritance is a controller-only fan-out: a definition CRUD loops over links and reuses the
+existing per-link marker operations, so the compute side sees an ordinary marker and is
+unchanged. Each compute process runs one UDP listener serving every uBridge on that host; the
+`node` and `link` fields in each signal together identify the source link (see
+[Per-link attribution](#per-link-attribution)).
+
+## Business Process
+
+```mermaid
+sequenceDiagram
+    participant UI as Web UI
+    participant C as Controller
+    participant L as Capable Link
+    participant N as Compute / uBridge
+
+    UI->>C: POST /marker-definitions {name, bpf, ...}
+    C->>C: store definition
+    loop every capable link
+        C->>L: start_marker("global-{name}")
+        L->>N: install mark filter (BPF + pcap)
+    end
+    C-->>UI: 201 + link_ids
+
+    Note over N: later: a packet matches the BPF
+    N->>N: emit MARK signal + append pcap
+    N-->>UI: marker.match notification (per-project ws)
+```
+
+Updating a definition syncs `bpf / tag / color / highlight_duration` to every inherited
+copy; deleting a definition removes every inherited copy. A newly created link inherits all
+existing definitions automatically.
+
+## Per-link attribution
+
+A uBridge `MARK` signal carries `node`, `filter`, `link`, `tag`, and `len` — but no bridge
+name. When one node is the capture side for several links — the common case for a project-level
+`global-{name}` marker on a multi-interface router — `node` + `filter` alone are identical
+across those links, so they cannot tell the signals (or pcap files) apart. The `link` field
+resolves this:
+
+1. At install time the controller stamps each filter with its link id
+   (`mark <bpf> [tag <id>] link <link_id> [pcap <path>]`).
+2. uBridge treats `link` as opaque and echoes it verbatim in the signal (`link=<link_id>`).
+3. The listener takes the signal's `link=` as the **authoritative** `link_id` of the
+   `marker.match` event, falling back to its registry only for legacy signals that carry no
+   `link=`.
+
+This is also why the pcap path is keyed on link —
+`<project>/markers/<node_id>_<link_id>_<filter>.pcap`, not on `bridge`+`filter`: a single
+uBridge bridge can serve several links, and only the link id keeps their captures distinct.
+
+### IOU: one bridge, many interfaces
+
+IOU runs a single `IOL-BRIDGE` per node shared by every interface, so `bridge`+`filter` are
+identical across that node's links. uBridge keeps a separate filter list **per port
+(bay/unit)** within the bridge, so each interface gets its own `global-{name}` filter, its own
+pcap file, and its own `link=`. The shared bridge name is irrelevant to attribution. Other
+capable node types (`qemu`, `docker`, `vpcs`, `cloud`) already use one bridge per link; `link`
+applies uniformly to all of them.
+
+## Direction
+
+A `MARK` signal optionally carries `dir=<tx|rx>` — the matched packet's travel direction
+**relative to the capture node** (the `node=<id>` in the same signal, i.e. the node whose
+uBridge hosts the marker):
+
+| `dir` | Ingress NIO | Meaning |
+|-------|-------------|---------|
+| `tx`  | device side (`source_nio` on a generic bridge; the IOL instance on an IOU `IOL-BRIDGE`) | capture node is **sending** |
+| `rx`  | link side (`destination_nio` on a generic bridge; the NIO side on an IOU `IOL-BRIDGE`) | capture node is **receiving** |
+
+A marker is single-sided: only the chosen capture node's uBridge installs the `mark` filter,
+yet both directions of the link transit that one bridge (it carries exactly two NIOs — the
+device side and the link side), so that single uBridge observes and classifies both
+directions. The `marker.match` event forwards `dir` through unchanged; the Web UI combines it
+with the link's two endpoints and the capture `node_id` to draw an arrow:
+
+- `dir=tx` → `capture_node → far_node`
+- `dir=rx` → `far_node → capture_node`
+- `dir` absent (older uBridge) → undirected highlight (current behaviour)
+
+Because the listener ignores unknown keys, `dir` is **additive**: an older server silently
+drops it and an older uBridge simply omits it — either way the system falls back to
+undirected rendering with no error.
+
+### Choosing the capture node
+
+Since `dir` is relative to the capture node, *which* endpoint is the observer decides what
+`tx`/`rx` mean. By default the server auto-picks (first started marker-capable endpoint, in
+link-endpoint order). To pin it — e.g. so `dir=tx` unambiguously means "vpcs1 is sending" —
+pass `capture_node_id` on marker **create**:
+
+```json
+{ "bpf": "icmp", "direction": "tx", "capture_node_id": "<vpcs1 node uuid>" }
+```
+
+The value must be one of the link's two endpoints and a marker-capable type (`vpcs`, `qemu`,
+`docker`, `iou`, `dynamips`, `cloud`); any other id is rejected with `409`. Omit it to keep
+the auto-pick. The chosen id is echoed back as `capture_node_id` in the marker entry and in
+each `MARK` signal's `node=<id>`, so the Web UI always knows the observer regardless of who
+picked it.
+
+`capture_node_id` is **create-only**: it is fixed once the marker exists (changing the
+observer would silently flip the meaning of stored `direction`, so recreate the marker
+instead). It is not accepted on project-level definitions — a definition is link-agnostic and
+has no endpoints to choose from, so inherited markers always auto-pick per link.
+
+For the same reason, a definition **rejects `direction: tx|rx`** (HTTP 409): each inherited
+copy auto-picks its capture node, so a fixed tx/rx would denote different session directions
+on different links. A definition is `both` only; encode the direction you want in the BPF
+instead — e.g. `icmp and icmp[icmptype]==8` for echo requests, a packet-intrinsic property
+that is consistent on every link regardless of capture node. tx/rx remains available on
+per-link markers, where the capture node is fixed.
+
+## Pause & resume
+
+Two levels of silencing, both instant (no NIO rebuild, no pcap flush):
+
+- **Per-marker (private)** — `PUT /v3/projects/{pid}/links/{lid}/markers/{name}`
+  with `{"enabled": false}` flips that one filter off in place (uBridge
+  `enable_packet_filter … off`): no signal, no pcap, but traffic still relays —
+  a paused `mark` is a no-op tap, not a drop. `{"enabled": true}` flips it back.
+  A change to `enabled` alone is a single command (the pcap identity and emitted
+  counter are preserved). Changing `bpf`, `tag`, or `direction` rebuilds just that
+  one filter (`delete_packet_filter` + add) — only that marker's own pcap reopens
+  (a new capture session for the new BPF); changing `color`/`highlight_duration`
+  is UI-only, nothing is pushed to uBridge.
+- **Per-definition (inherited)** — `POST /v3/projects/{pid}/marker-definitions/{name}/pause`
+  and `/resume` toggle **every** inherited `global-{name}` copy across all links
+  at once (same `enable_packet_filter on|off`, fanned out per copy). Use to
+  pause or resume a whole rule independently of the others. The definition's
+  `paused` flag is persisted to the `.gns3` and echoed on the definition object,
+  so links created later inherit it already paused, and the Web UI renders the
+  per-rule button from server truth.
+
+| Action | signal | pcap | sink |
+|--------|--------|------|------|
+| per-marker `enabled: false` | stop | stop | n/a |
+| per-def `pause` (all `global-{name}` copies) | stop | stop | n/a |
+| per-def `resume` | resume | resume | n/a |
+
+## Capture files
+
+Each marker appends matches to `<project>/project-files/markers/<node_id>_<link_id>_<filter>.pcap`.
+Removing a marker — per-link `DELETE .../markers/{name}` or deleting a definition (which
+removes every inherited copy) — deletes that marker's pcap too, even with the capture node
+stopped (the filter is removed with `delete_packet_filter`, the file is unlinked). uBridge's
+`reset_packet_filters` (run on NIO/filter changes) preserves mark filters, so unrelated
+changes no longer close/reopen any marker's pcap.
+
+## API Endpoints
+
+All endpoints require a JWT bearer token (`POST /v3/access/users/authenticate`). The
+`Auth` column lists the required privilege.
+
+### Per-link markers
+
+| Method | Path | Description | Auth |
+|--------|------|-------------|------|
+| GET | `/v3/projects/{pid}/links/{lid}/markers` | List markers on a link | Link.Audit |
+| POST | `/v3/projects/{pid}/links/{lid}/markers` | Attach a marker | Link.Modify |
+| PUT | `/v3/projects/{pid}/links/{lid}/markers/{name}` | Update a marker | Link.Modify |
+| DELETE | `/v3/projects/{pid}/links/{lid}/markers/{name}` | Remove a marker | Link.Modify |
+
+### Project-level definitions
+
+| Method | Path | Description | Auth |
+|--------|------|-------------|------|
+| GET | `/v3/projects/{pid}/marker-definitions` | List definitions + bound `link_ids` | Project.Audit |
+| POST | `/v3/projects/{pid}/marker-definitions` | Create definition (fans out to every link) | Project.Modify |
+| PUT | `/v3/projects/{pid}/marker-definitions/{name}` | Update definition (syncs all copies) | Project.Modify |
+| DELETE | `/v3/projects/{pid}/marker-definitions/{name}` | Delete definition (clears all copies) | Project.Modify |
+| POST | `/v3/projects/{pid}/marker-definitions/{name}/pause` | Pause every inherited copy (instant, persisted) | Project.Modify |
+| POST | `/v3/projects/{pid}/marker-definitions/{name}/resume` | Resume every inherited copy | Project.Modify |
+
+### Aggregation
+
+| Method | Path | Description | Auth |
+|--------|------|-------------|------|
+| GET | `/v3/projects/{pid}/markers` | All markers across links, flat | Project.Audit |
+
+The link object returned by `GET /v3/projects/{pid}/links[/{lid}]` also carries a `markers`
+field (including inherited markers), so the Web UI can render a link's markers without an
+extra request.
+
+## Request / Response
+
+**Marker create body** (`MarkerCreate`, shared by per-link POST and PUT):
+
+```json
+{
+  "name": "icmp",
+  "bpf": "icmp",
+  "tag": 1,
+  "direction": "tx",
+  "capture_node_id": "a37e2235-e21f-46c9-a2ab-ba0f8c5465e6",
+  "color": "#ff5722",
+  "highlight_duration": 800,
+  "enabled": true
+}
+```
+
+`direction` and `capture_node_id` are both optional and create-only (see
+[Direction](#direction)).
+
+**Definition create body** (`MarkerDefinitionCreate`, shared by POST and PUT):
+
+```json
+{
+  "name": "arp",
+  "bpf": "arp",
+  "tag": 5,
+  "color": "#ff5722",
+  "highlight_duration": 1200
+}
+```
+
+**Marker entry** (returned by GET/POST/PUT, and the value of each link's `markers[name]`):
+
+```json
+{
+  "bpf": "icmp",
+  "tag": 1,
+  "enabled": true,
+  "color": "#ff5722",
+  "highlight_duration": 800,
+  "capture_node_id": "a37e2235-e21f-46c9-a2ab-ba0f8c5465e6",
+  "inherited_from": null
+}
+```
+
+**Definition GET response** (adds `link_ids`):
+
+```json
+{
+  "arp": {
+    "bpf": "arp",
+    "tag": 5,
+    "color": null,
+    "highlight_duration": 1200,
+    "direction": null,
+    "paused": false,
+    "link_ids": ["656ed826-...", "6bd9d156-..."]
+  }
+}
+```
+
+## Field Reference
+
+### Marker entry
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `bpf` | string | libpcap BPF expression (required) |
+| `tag` | int \| null | Correlation id echoed in `MARK` signals |
+| `enabled` | bool | Whether the marker is active. Toggle is instant: `false` flips the uBridge filter off in place (no signal/pcap), `true` back on — no NIO rebuild (see [Pause & resume](#pause--resume)) |
+| `color` | string \| null | Hex color render hint, e.g. `#ff5722` |
+| `highlight_duration` | int \| null | UI highlight duration in ms after a match; `null` = UI default |
+| `direction` | string \| null | `tx` / `rx` filter relative to the capture node; `null` = both |
+| `capture_node_id` | string | Node whose uBridge hosts the marker — caller-set on create, else auto-picked |
+| `inherited_from` | string | Source definition name — present on inherited markers only |
+
+### Definition
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `bpf` | string | libpcap BPF expression (required) |
+| `tag` | int \| null | Correlation id |
+| `color` | string \| null | Hex color render hint |
+| `highlight_duration` | int \| null | UI highlight duration in ms; `null` = UI default |
+| `direction` | string \| null | `tx` / `rx` filter relative to the capture node; `null` = both |
+| `paused` | bool | Per-definition mute flag — `true` mutes every inherited copy (persisted) |
+| `link_ids` | string[] | Links currently carrying an inherited copy (GET only) |
+
+### Notifications
+
+| Event | Payload | Delivered to |
+|-------|---------|--------------|
+| `link.updated` | Link object (its `markers` field is the source of truth) | Project notification ws |
+| `marker.match` | `project_id`, `node_id`, `link_id`, `filter`, `tag`, `ts`, `len`, `dir` | Project notification ws only |
+
+The `marker.match` `link_id` is taken from the signal's `link=` field (authoritative); see
+[Per-link attribution](#per-link-attribution). The `dir` field is the matched packet's travel
+direction relative to the capture node; see [Direction](#direction).
+
+## Error Responses
+
+| Status | Description |
+|--------|-------------|
+| 401 | Not authenticated |
+| 404 | Link / marker / definition not found |
+| 409 | Per-link edit or delete of an inherited marker; reserved (`global`) name or duplicate name on create |
+| 422 | Validation failure (name format, `highlight_duration < 1`, missing `bpf`) |
+
+## Notes
+
+- **Marker name is immutable.** It is the identifier across the controller, the uBridge
+  filter, the pcap filename, and `MARK` signal routing — so rename is a delete + recreate,
+  not a field update. PUT ignores the body `name`; the `{name}` path parameter identifies
+  the target, and only `bpf / tag / color / enabled / highlight_duration` are changeable.
+  Names are 1–32 chars (`[A-Za-z0-9][A-Za-z0-9_.-]*`); inherited copies carry a `global-`
+  prefix, so their filter names reach ~39.
+- **`global` prefix reserved.** User-chosen names may not start with `global`; inherited
+  markers are stored as `global-{definition_name}` so the two namespaces cannot collide.
+  Omitting `name` on create yields an auto-generated, prefix-free name.
+- **Inherited markers are read-only per-link.** PUT/DELETE on an inherited marker returns
+  409 — edit them through the definitions API.
+- **Render hints are not enforced.** `color` and `highlight_duration` (milliseconds, `>= 1`)
+  are stored on the link and never sent to uBridge; `null` lets the UI apply its own
+  default. A partial PUT (e.g. changing only `bpf`) leaves them untouched.
+- **BPF is validated once per source.** A private per-link marker validates its BPF inline
+  on create/update. A definition validates its BPF once at create/update (and once per
+  definition on project load, dropping any whose BPF has gone invalid); the inherited
+  fan-out to every link then skips re-validation, so creating a definition over *N* links
+  runs one `tcpdump -d` rather than *N*. (uBridge still runs `pcap_compile` itself at
+  install time, so an invalid expression can never slip through.)
+- **Supported node types.** A marker needs a uBridge bridge: `vpcs`, `qemu`, `docker`,
+  `iou`, `dynamips`, `cloud` (one capable endpoint suffices). Types without a uBridge are
+  silently skipped by the inheritance fan-out. IOU uses one shared `IOL-BRIDGE` per node but
+  keeps filters, pcap files, and `link=` ids per port, so multi-interface nodes are handled
+  (see [Per-link attribution](#per-link-attribution)).
+- **Shared capture-side node.** When one node hosts markers for several links (typical for
+  `global-*` definitions on a router), each filter is stamped with its `link_id` so signals
+  and pcap files stay link-distinct; the controller never collapses them to a single link.
+- **Persistence.** Definitions and private markers persist in the topology; inherited
+  markers are re-created from definitions on project load, so reopening a project restores
+  the same configuration and stale inherited copies cannot survive on disk.
+- **Log interpretation across node types.** Each node type logs its startup and link
+  operations differently — do not mistake sparse logs from one type for inactivity.
+  QEMU prints `set_link gns3-<N> on` via its QEMU monitor, which is the most visible
+  startup log among all types. VPCS, Docker, IOU, Dynamips, and Cloud each have their own
+  startup paths (fork + ubridge, container veth, iouyap, Dynamips hypervisor, and TAP
+  device respectively) and none of them emit QEMU-monitor-style logs. To verify marker
+  operations (toggle, pause, resume) on non-QEMU types, either inspect uBridge's
+  own log for `enable_packet_filter` / `marker pause` / `marker resume` commands, or
+  watch the gns3server log for the corresponding compute-route calls at INFO level.

docs/features/mcp-service.md

@@ -0,0 +1,480 @@
+# MCP (Model Context Protocol) Service
+
+## Overview
+
+GNS3 Server provides a standard [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) interface, allowing AI assistants like Claude to interact with GNS3 network simulations through SSE (Server-Sent Events) transport.
+
+The MCP service exposes GNS3 project management operations as MCP tools that can be discovered and called by MCP clients.
+
+## Endpoints
+
+| Path | Method | Description |
+|------|--------|-------------|
+| `/v3/mcp/` | GET | MCP service metadata |
+| `/v3/mcp/transport/sse` | GET | SSE stream (MCP connection) |
+| `/v3/mcp/transport/messages/` | POST | JSON-RPC messages |
+
+## Authentication
+
+The SSE endpoint supports two types of credentials, passed the same way.
+
+1. **Authorization header** (recommended):
+   ```
+   Authorization: Bearer <jwt_or_api_key>
+   ```
+
+2. **Query parameter** (for clients that don't support custom headers):
+   ```
+   GET /v3/mcp/transport/sse?token=<jwt_or_api_key>
+   ```
+
+### Option 1: JWT Token (24h expiry)
+
+```bash
+curl -X POST http://localhost:3080/v3/access/users/authenticate \
+  -H "Content-Type: application/json" \
+  -d '{"username": "admin", "password": "admin"}'
+```
+
+Default lifetime is **1440 minutes (24 hours)**. Configurable in `gns3_server.conf`:
+```ini
+jwt_access_token_expire_minutes = 1440  ; 24 hours
+```
+
+### Option 2: API Key (permanent, revocable) — Recommended for MCP
+
+API keys never expire and can be revoked individually. Format: `gns3_<api_key_id>_<random_secret>` — the embedded UUID enables O(1) lookup without scanning all keys.
+
+Create one via the REST API:
+
+```bash
+# Create an API key (requires a JWT to authenticate)
+curl -X POST http://localhost:3080/v3/access/api-keys \
+  -H "Authorization: Bearer <your_jwt>" \
+  -H "Content-Type: application/json" \
+  -d '{"name": "MCP Production"}'
+# Response: {"api_key": "gns3_550e8400-e29b-41d4-a716-446655440000_a1b2c3d4...", ...}
+# ⚠️ The key is only shown once — save it immediately.
+```
+
+API key management endpoints:
+
+| Endpoint | Description |
+|----------|-------------|
+| `POST /v3/access/api-keys` | Create a new key (returns plaintext once) |
+| `GET /v3/access/api-keys` | List all your keys |
+| `POST /v3/access/api-keys/{id}/revoke` | Revoke a key (can be restored) |
+| `POST /v3/access/api-keys/{id}/restore` | Restore a revoked key |
+| `DELETE /v3/access/api-keys/{id}` | Permanently delete a key |
+
+Both JWT tokens and API keys work for MCP and REST API endpoints interchangeably.
+
+### Authentication Flow
+
+When connecting with an API key:
+
+```
+SSE connect → Authorization: Bearer gns3_<uuid>_<secret>
+  ↓
+MCP auth wrapper extracts UUID → single DB query → 1 bcrypt (thread pool)
+  ↓
+Generates a fresh short-lived JWT → stored in ContextVar for the session
+  ↓
+All subsequent tool handler REST API calls use this JWT → zero extra bcrypt
+```
+
+### Concurrency
+
+| Setting | Value |
+|---------|-------|
+| MCP batch workers | 100 (`BATCH_MAX_WORKERS`) |
+| MCP HTTP client timeout | 30s |
+| HTTP connection pool (`pool_connections`/`pool_maxsize`) | 500 / 1000 |
+| REST API node/link creation pool | 100 (`Pool(concurrency=100)`) |
+
+## Available Tools
+
+**82 tools** across 12 categories:
+
+### Project (15)
+
+| Tool | Description |
+|------|-------------|
+| `project_list` | List all projects |
+| `project_get` | Get project details |
+| `project_create` | Create a project |
+| `project_delete` | Delete a project |
+| `project_open` | Open a closed project |
+| `project_close` | Close an open project |
+| `project_stats` | Get project statistics |
+| `project_update` | Update project properties |
+| `project_duplicate` | Duplicate a project |
+| `project_readme_get` | Get project README content |
+| `project_readme_update` | Update project README |
+| `project_lock` | Lock project (prevent edits) |
+| `project_unlock` | Unlock project |
+| `project_load` | Load project from path |
+| `project_locked` | Check if project is locked |
+
+### Node (22)
+
+| Tool | Description |
+|------|-------------|
+| `node_list` | List all nodes (`fields` to filter columns, e.g. `["name","status"]`) |
+| `node_get` | Get node details (`fields` to filter columns) |
+| `node_create` | Create node(s) — single via `template_id` or batch via `nodes` array. Supports `fields` to filter response. Top-level `template_id` applies as default in batch mode. Pass `name` to override template naming. Coordinates: left-handed Cartesian (origin at canvas center, X right-positive, Y down-positive). |
+| `node_delete` | Delete a node |
+| `node_update` | Update node properties |
+| `node_start` | Start node(s) — `node_id` or `node_ids` array |
+| `node_stop` | Stop node(s) — `node_id` or `node_ids` array |
+| `node_suspend` | Suspend node(s) — `node_id` or `node_ids` array |
+| `node_console` | Get WebSocket console URL |
+| `node_file_list` | List files in node directory |
+| `node_file_get` | Read a file (with offset/limit) |
+| `node_file_write` | Write a file |
+| `node_file_delete` | Delete a file |
+| `node_start_all` | Start all nodes |
+| `node_stop_all` | Stop all nodes |
+| `node_suspend_all` | Suspend all nodes |
+| `node_duplicate` | Duplicate a node |
+| `node_isolate` | Isolate a node (suspend links) |
+| `node_unisolate` | Un-isolate a node (resume links) |
+| `node_links` | List links connected to a node |
+
+### Link (9)
+
+| Tool | Description |
+|------|-------------|
+| `link_list` | List all links (`fields` to filter columns) |
+| `link_get` | Get link details |
+| `link_create` | Create link(s) — single via `nodes` or batch via `links` array. Nodes support compact `[id, ad, pt, id, ad, pt]` format. Supports `fields` to filter response. |
+| `link_delete` | Delete link(s) — `link_id` or `link_ids` array |
+| `link_update` | Update link (suspend, filters) |
+| `link_reset` | Reset link(s) — `link_id` or `link_ids` array |
+| `link_capture_start` | Start capture(s) — `link_id` or `link_ids` array |
+| `link_capture_stop` | Stop capture(s) — `link_id` or `link_ids` array |
+| `link_capture_download` | Get PCAP download URL(s) — `link_id` or `link_ids` array |
+
+### Template (5)
+
+| Tool | Description |
+|------|-------------|
+| `template_list` | List all templates. Supports `fields` to filter response columns. |
+| `template_get` | Get template details |
+| `template_create` | Create a template (Docker needs `image`) |
+| `template_update` | Update a template |
+| `template_delete` | Delete a template |
+
+### Compute (3)
+
+| Tool | Description |
+|------|-------------|
+| `compute_list` | List registered remote computes |
+| `compute_get` | Get compute details (requires UUID) |
+| `compute_images` | List emulator images on a compute |
+
+### Snapshot (4)
+
+| Tool | Description |
+|------|-------------|
+| `snapshot_list` | List snapshots |
+| `snapshot_create` | Create a snapshot |
+| `snapshot_delete` | Delete a snapshot |
+| `snapshot_restore` | Restore a snapshot |
+
+### Drawing (5)
+
+| Tool | Description |
+|------|-------------|
+| `drawing_list` | List drawings on canvas |
+| `drawing_get` | Get drawing details |
+| `drawing_create` | Create drawing (SVG label/shape/image) |
+| `drawing_update` | Update drawing (position, rotation, SVG) |
+| `drawing_delete` | Delete a drawing |
+
+### Symbol (6)
+
+| Tool | Description |
+|------|-------------|
+| `symbol_list` | List all symbols |
+| `symbol_get` | Get symbol download URL |
+| `symbol_dimensions` | Get symbol dimensions |
+| `symbol_defaults` | Get default symbol mapping |
+| `symbol_upload` | Upload a custom symbol (SVG content) |
+| `symbol_delete` | Delete a custom symbol (built-in: 403) |
+
+### Appliance (3)
+
+| Tool | Description |
+|------|-------------|
+| `appliance_list` | List appliances (`fields` to filter, e.g. `["name","category"]`) |
+| `appliance_get` | Get appliance details |
+| `appliance_install` | Create template from appliance (images must exist locally) |
+
+### Image (5)
+
+| Tool | Description |
+|------|-------------|
+| `image_list` | List all images |
+| `image_get` | Get image details |
+| `image_delete` | Delete an image |
+| `image_prune` | Remove images not referenced by any template |
+| `image_install` | Auto-create templates from uploaded images by checksum |
+
+### Server (2)
+
+| Tool | Description |
+|------|-------------|
+| `server_version` | Get GNS3 server version |
+| `server_statistics` | Get server statistics (computes, projects, nodes) |
+
+### Device Config (3)
+
+| Tool | Description |
+|------|-------------|
+| `device_config_send` | Push config commands to devices via console (Nornir + Netmiko). Supports Jinja2 `template` + `vars` |
+| `device_show_run` | Run read-only show commands on devices. Supports Jinja2 `template` + `vars` |
+| `vpcs_config_set` | Configure VPCS devices (IP, gateway, etc.) |
+
+The tool connects to each device's console via telnet/SSH. Nodes must be in the `started` state (use `node_start` or `node_start_all`). Device type is auto-detected from the node's `device_type:<type>` tag in GNS3.
+
+#### Jinja2 Template Mode
+
+Both `device_config_send` and `device_show_run` support an optional `template` parameter. When provided, each device's `vars` dict is rendered against the template to produce commands. Entries with the same `device_name` are merged into a single device session.
+
+```python
+# Direct commands (single/batch)
+device_config_send(project_id, device_configs=[
+    {"device_name": "R1", "config_commands": ["int lo0", "ip add 1.1.1.1 255.255.255.255"]},
+])
+
+# Jinja2 template (reduces token usage for batch)
+device_config_send(project_id,
+    template="interface lo{{ n }}\nip address {{ ip }} 255.255.255.255",
+    device_configs=[
+        {"device_name": "R1", "vars": {"n": 0, "ip": "1.1.1.1"}},
+        {"device_name": "R2", "vars": {"n": 0, "ip": "2.2.2.2"}},
+    ])
+
+# Show commands with template
+device_show_run(project_id,
+    template="show ip route {{ protocol }}",
+    device_configs=[
+        {"device_name": "R1", "vars": {"protocol": "ospf"}},
+        {"device_name": "R2", "vars": {"protocol": "bgp"}},
+    ])
+```
+
+### Best Practices
+
+**Prefer template over direct commands for batch.** When ≥2 nodes share the same config structure with different values, use `template`+`vars` instead of writing `config_commands` per node. This reduces token usage and transcription errors.
+
+**Batch merging.** Multiple entries with the same `device_name` are merged into a single Nornir session. The output contains all commands' results in one block. Match results by `device_name`, not list index.
+
+**Don't rely on `status: success` alone.** It only means commands entered config mode. IOS errors (`% Invalid input`, `% overlaps`, `% Incomplete command`) appear inside `output` text — always scan for `%` lines.
+
+**Pilot before full rollout.** Test template + vars on 1–2 devices first to verify rendering and syntax, then expand to all nodes.
+
+**Config backup via file operations.** IOU and Dynamips nodes save startup config as a plain text file (`startup-config.cfg`) in the node directory after `write memory`. These can be backed up and restored via `node_file_get`/`node_file_write`.
+
+```python
+# Save config on device
+device_show_run(project_id, device_configs=[
+    {"device_name": "R1", "commands": ["write memory"]},
+])
+# Backup
+config = node_file_get(project_id, node_id, "startup-config.cfg")
+# Restore if config breaks
+node_file_write(project_id, node_id, "startup-config.cfg", config)
+node_stop(project_id, node_id)
+node_start(project_id, node_id)
+```
+
+### Device Config Workflow
+
+```mermaid
+sequenceDiagram
+    participant AI as AI Agent
+    participant MCP as MCP Handler
+    participant TM as Template Renderer
+    participant DP as Device Discovery
+    participant NR as Nornir
+    participant NM as Netmiko
+    participant D as Device Console
+
+    Note over AI: Decide: template or direct commands?
+
+    alt Direct commands
+        AI->>MCP: device_config_send(config_commands=[...])
+    else Jinja2 template
+        AI->>MCP: device_config_send(template + vars)
+        MCP->>TM: Render template per device
+        TM->>TM: Jinja2.render(**vars)
+        TM-->>MCP: device_configs with rendered commands
+    end
+
+    MCP->>DP: get_device_ports_from_topology()
+    DP-->>MCP: hosts_data (console port, device_type)
+
+    Note over MCP: Prepare Nornir inventory
+
+    MCP->>NR: InitNornir(hosts, threaded runner)
+    par Device 1 to N (parallel, max 10)
+        NR->>NM: netmiko_send_config(commands)
+        NM->>D: telnet/SSH console session
+        D-->>NM: command output
+        NM-->>NR: execution result
+    end
+    NR-->>MCP: aggregated results
+    MCP-->>AI: per-device results with output
+```
+
+## Configuration
+
+### Claude Code (CLI)
+
+```bash
+# Option A: Using API key (recommended — never expires)
+claude mcp add --transport sse My_GNS3_Server \
+  http://localhost:3080/v3/mcp/transport/sse \
+  -H "Authorization: Bearer gns3_a1b2c3d4..."
+
+# Option B: Using JWT token (expires after 24h)
+TOKEN=$(curl -s -X POST http://localhost:3080/v3/access/users/authenticate \
+  -H "Content-Type: application/json" \
+  -d '{"username": "admin", "password": "admin"}' | python3 -c \
+  "import sys,json; print(json.load(sys.stdin)['access_token'])")
+
+claude mcp add --transport sse My_GNS3_Server \
+  http://localhost:3080/v3/mcp/transport/sse \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+## Transport Security
+
+MCP server uses FastMCP's DNS rebinding protection to prevent attackers from
+exploiting DNS resolution to access the MCP endpoint through unauthorized domains.
+
+### Default Behaviour
+
+DNS rebinding protection is **disabled by default**, allowing connections from
+any host. This aligns with GNS3 server's default `host = 0.0.0.0` binding policy,
+which is designed for VM distribution scenarios where users access the server
+from various network locations.
+
+### Enabling Protection
+
+Add to `gns3_server.conf` under the `[Server]` section:
+
+```ini
+; Enable DNS rebinding protection for MCP server
+mcp_enable_dns_rebinding_protection = True
+
+; Allowed hosts (comma-separated, "host:*" port wildcard patterns only)
+mcp_allowed_hosts = 127.0.0.1:*,localhost:*,192.168.1.3:*
+
+; Allowed origins (comma-separated)
+mcp_allowed_origins = http://127.0.0.1:*,http://localhost:*,http://192.168.1.3:*
+```
+
+> **Note**: The MCP library only supports `"host:*"` port wildcard patterns
+> (e.g., `"192.168.1.3:*"`). Standalone `"*"` wildcards are not supported.
+
+### Protection Mechanism
+
+When protection is enabled, the MCP server validates the `Host` header of
+incoming SSE connection requests:
+
+```python
+# Verify the request's Host header matches allowed patterns
+validate_request → check Host header → 421 Misdirected Request if invalid
+```
+
+This prevents DNS rebinding attacks:
+1. Attacker registers `evil.com` pointing to your server's IP
+2. User's browser makes requests to `evil.com:3080`
+3. MCP server checks Host header = `"evil.com:3080"`
+4. `"evil.com:3080"` is not in `allowed_hosts` → connection rejected
+
+### Behaviour Summary
+
+| `mcp_enable_dns_rebinding_protection` | Result |
+|:---|:---|
+| `False` (default) | All hosts allowed |
+| `True` + correct hosts configured | Only configured hosts allowed |
+| `True` + missing/wrong hosts | Connections rejected with 421 |
+
+For public-facing MCP servers, set `allowed_hosts` to your server's domain name.
+
+## Architecture
+
+```mermaid
+sequenceDiagram
+    participant Client as Claude Code
+    participant MCP as MCP Service
+    participant Auth as Auth
+    participant GNS3 as GNS3 REST API
+
+    Note over Client: 1. Connect with API Key or JWT
+    Client->>MCP: GET /sse (Authorization: Bearer <key>)
+    
+    alt API Key (gns3_&lt;uuid&gt;_&lt;secret&gt;)
+        MCP->>Auth: Extract UUID → DB lookup → 1 bcrypt (thread pool)
+        Auth-->>MCP: Generate fresh JWT
+    else JWT
+        MCP->>Auth: Decode JWT
+        Auth-->>MCP: Token valid
+    end
+    
+    MCP-->>Client: event: endpoint /messages/?session_id=xxx
+
+    Note over Client: 2. Initialize & Call Tools
+    Client->>MCP: POST /messages/ (tools/call ...)
+    MCP->>GNS3: HTTP request (with JWT from step 1)
+    GNS3-->>MCP: Response
+    MCP-->>Client: event: message (tool result)
+```
+
+## Internal Implementation
+
+- **FastMCP** (Anthropic MCP SDK) is used for tool registration and SSE transport
+- The SSE app is mounted as a Starlette sub-application under `/v3/mcp/transport`
+- **Auth:** JWT validation via `auth_service`. API key (`gns3_<uuid>_<secret>`) extracts UUID for O(1) DB lookup, runs bcrypt in thread pool, returns a fresh JWT — subsequent calls use the JWT with zero extra bcrypt.
+- Tool handlers use `Gns3Connector` (from `custom_gns3fy`) to call GNS3's own REST API, keeping the MCP layer decoupled
+- The JWT token is stored in a `contextvars.ContextVar` so it is available within tool handler threads (Python ≥ 3.9 propagates contextvars through `asyncio.to_thread`)
+
+### Console WebSocket
+
+The `node_console` tool returns a WebSocket URL for connecting to a node's console. The URL includes a short-lived JWT (10 min) — reconnect if it expires. This endpoint is protocol-agnostic — it works for **telnet**, **ssh**, and **vnc** console types alike. The WebSocket simply proxies raw byte streams between the client and the compute node; protocol negotiation (e.g. SSH key exchange) happens on the compute side.
+
+The WebSocket URL is constructed using the server's `_server_url()`, which resolves the host as follows:
+
+| `Server.host` value | Resolved host in URL |
+|:---|:---|
+| Specific IP or hostname (e.g. `192.168.1.3`) | Used as-is |
+| `0.0.0.0` (IPv4 any, default) | Detected via **default route interface IP** |
+| `::` (IPv6 any) | Detected via default route interface IP |
+| Detection failure | Fallback to `127.0.0.1` |
+
+When `Server.host` is `0.0.0.0` (listen on all interfaces), the MCP server discovers the default route interface IP using a UDP socket connect to `8.8.8.8:80` — no network data is sent, the operating system simply selects the interface that would be used for the default route. This ensures the returned WebSocket URL uses a reachable address (e.g. `192.168.1.3` instead of `127.0.0.1`).
+
+If the configured host is already a specific IP or hostname (not `0.0.0.0`), it is used directly in the URL without modification.
+
+Use `websocat` to connect from the command line:
+
+```bash
+# The host in the URL is automatically resolved to a reachable address
+websocat ws://192.168.1.3:3080/v3/projects/{project_id}/nodes/{node_id}/console/ws?token=<jwt>
+```
+
+### Source Files
+
+| File | Purpose |
+|------|---------|
+| `gns3server/api/routes/mcp/__init__.py` | FastMCP server, tool decorators, SSE transport, JWT auth wrapper |
+| `gns3server/api/routes/mcp/projects.py` | Project tool handlers |
+| `gns3server/api/routes/mcp/nodes.py` | Node tool handlers |
+| `gns3server/api/routes/mcp/links.py` | Link tool handlers |
+| `gns3server/api/routes/mcp/templates.py` | Template tool handlers |
+| `gns3server/api/routes/mcp/computes.py` | Compute tool handlers |
+| `gns3server/api/server.py` | Mounts MCP routes via `register_starlette_routes()` |

docs/features/project-open-performance.md

@@ -0,0 +1,148 @@
+# Project Open Performance
+
+## Overview
+
+Optimizations to accelerate project opening (`POST /projects/{id}/open`) and node creation for topologies with many nodes and links. The main bottlenecks were sequential link creation, redundant subprocess calls, and SQLite write contention.
+
+## Before vs After
+
+| Scenario | Before | After |
+|----------|--------|-------|
+| 20 IOU nodes + 20 links (project open) | ~2s | ~1s |
+| 40 QEMU nodes creation (MCP batch) | ~40s | ~1-2s |
+
+## Optimizations
+
+### 1. Parallel Link Creation
+
+**File:** `gns3server/controller/project.py`
+
+Links were created sequentially during project loading, each requiring up to 5 HTTP round-trips to the compute. Now uses `Pool(concurrency=100)` for parallel creation.
+
+```python
+# Before: sequential loop
+for link_data in topology.get("links", []):
+    link = await self.add_link(...)
+    await link.add_node(...)
+
+# After: parallel Pool
+pool = Pool(concurrency=100)
+for link_data in topology.get("links", []):
+    pool.append(self._create_link_from_topology_data, link_data)
+await pool.join()
+```
+
+### 2. Batch UDP Port Allocation
+
+**Files:** `gns3server/api/routes/compute/compute.py`, `gns3server/controller/project.py`, `gns3server/controller/udp_link.py`
+
+During project loading, all required UDP ports are pre-allocated per compute in a single batch call before link creation begins. `UDPLink.create()` checks the pre-allocated pool first, falling back to individual allocation if unavailable.
+
+```python
+# New batch endpoint
+POST /projects/{id}/ports/udp/batch  →  {"count": N}  →  {"udp_ports": [...]}
+```
+
+### 3. IOU Image Subprocess Cache
+
+**File:** `gns3server/compute/iou/iou_vm.py`
+
+Each IOU VM creation spawned `ld-linux --verify` and `iou-image -h` subprocesses. With 20 nodes using the same image, this ran 40 redundant subprocesses. Now results are cached per image path at the class level.
+
+```python
+# Class-level caches shared across all instances
+IOUVM._loader_cache = {}           # image path → loader command
+IOUVM._default_values_cache = {}   # image path → (ram, nvram)
+```
+
+Only the first node with a given image runs the subprocesses; subsequent nodes reuse cached values.
+
+### 4. SQLite WAL Mode
+
+**File:** `gns3server/db/tasks.py`
+
+Write-Ahead Logging allows concurrent reads without blocking on writes. The PRAGMA is registered on `engine.sync_engine` instead of the `Engine` class to correctly fire for async engine connections.
+
+```python
+@event.listens_for(engine.sync_engine, "connect")
+def set_sqlite_pragma(dbapi_connection, connection_record):
+    cursor = dbapi_connection.cursor()
+    cursor.execute("PRAGMA journal_mode=WAL")
+    cursor.execute("PRAGMA foreign_keys=ON")
+    cursor.close()
+```
+
+Without WAL mode, concurrent API requests caused `sqlite3.OperationalError: database is locked`.
+
+### 5. API Key Authentication O(1) Lookup
+
+**Files:** `gns3server/api/routes/controller/api_keys.py`, `gns3server/api/routes/controller/dependencies/authentication.py`
+
+**Old format:** `gns3_<random>` — required scanning ALL keys and running bcrypt on each (O(n)).
+**New format:** `gns3_<api_key_id>_<random_secret>` — extract UUID from token, single DB query (O(1)), single bcrypt.
+
+```python
+# New auth flow
+parts = token.split("_", 2)
+key_id = UUID(parts[1])
+secret = parts[2]
+db_key = await api_keys_repo.get_api_key(key_id)  # O(1) lookup
+if await asyncio.to_thread(bcrypt.checkpw, secret.encode(), db_key.key_hash.encode()):
+    # Authenticated — 1 query + 1 bcrypt regardless of total key count
+```
+
+### 6. bcrypt in Thread Pool
+
+**File:** `gns3server/api/routes/controller/dependencies/authentication.py`
+
+`bcrypt.checkpw()` is CPU-bound (~1.3s per call) and was blocking the async event loop. With 5 API keys and 10 concurrent requests, this caused ~13s delay before any handler could start.
+
+```python
+# Before: blocking the event loop
+if bcrypt.checkpw(token.encode(), db_key.key_hash.encode()):
+    ...
+
+# After: offloaded to thread pool
+if await asyncio.to_thread(bcrypt.checkpw, secret.encode(), db_key.key_hash.encode()):
+    ...
+```
+
+### 7. Concurrency Settings
+
+| Setting | Before | After | File |
+|---------|--------|-------|------|
+| Node creation Pool | 5 | 100 | `controller/project.py` |
+| Link creation Pool | 5 | 100 | `controller/project.py` |
+| MCP BATCH_MAX_WORKERS | 10 | 100 | `api/routes/mcp/nodes.py` |
+| MCP HTTP timeout | 10s | 30s | `agent/gns3_copilot/gns3_client/custom_gns3fy.py` |
+| HTTP connection pool | 10 (default) | 500/1000 | `agent/gns3_copilot/gns3_client/custom_gns3fy.py` |
+| Start nodes Pool | 3 | 3 (unchanged) | `controller/project.py` |
+
+### 8. MCP Auth Returns JWT
+
+**File:** `gns3server/api/routes/mcp/__init__.py`
+
+When an MCP client connects with an API key, the `_resolve_token` function validates the key then returns a fresh short-lived JWT instead of the raw API key. The JWT is stored in a `ContextVar` and reused for all subsequent tool calls within the same SSE session — zero extra bcrypt.
+
+```python
+if user:
+    fresh_token = auth_service.create_access_token(user.username)
+    return fresh_token  # JWT for subsequent REST API calls
+```
+
+## Related Files
+
+| File | Changes |
+|------|---------|
+| `gns3server/controller/project.py` | Parallel link creation, batch UDP, Pool(100) |
+| `gns3server/compute/iou/iou_vm.py` | Image subprocess cache |
+| `gns3server/db/tasks.py` | WAL mode + sync_engine event listener |
+| `gns3server/api/routes/compute/compute.py` | Batch UDP endpoint |
+| `gns3server/controller/udp_link.py` | Pre-allocated port consumption |
+| `gns3server/api/routes/controller/api_keys.py` | O(1) key format |
+| `gns3server/api/routes/controller/dependencies/authentication.py` | O(1) auth + thread pool bcrypt |
+| `gns3server/api/routes/mcp/__init__.py` | Auth returns JWT, tool enhancements |
+| `gns3server/api/routes/mcp/nodes.py` | fields filter, inherited template_id, name passthrough |
+| `gns3server/api/routes/mcp/links.py` | fields filter, compact array format |
+| `gns3server/agent/gns3_copilot/gns3_client/custom_gns3fy.py` | Timeout 30s, connection pool 500/1000 |
+| `gns3server/utils/images.py` | md5sum cache error → warning |

docs/features/refresh-token-mechanism.md

@@ -0,0 +1,154 @@
+# Stateless JWT Refresh Token Mechanism
+
+## Overview
+
+GNS3 server now supports a stateless JWT refresh token mechanism for interactive sessions (e.g., Web UI). This allows clients to stay authenticated across page reloads without repeated username/password prompts, while keeping access tokens short-lived.
+
+No new database table or migration is required — refresh tokens are signed JWTs using the same secret and algorithm as access tokens.
+
+## Architecture
+
+```mermaid
+graph TD
+    Client -->|login / authenticate| API[Controller API]
+    API -->|access_token + refresh_token| Client
+    Client -->|POST /refresh| Refresh[Refresh Endpoint]
+    Refresh -->|new access_token + new refresh_token| Client
+    Client -->|Bearer access_token| Protected[Protected Endpoints]
+    Protected -->|401| Client
+    Client -->|refresh_token in body| Refresh
+    Refresh -->|401 if invalid/expired/revoked| Client
+    Refresh -->|verify type, exp, ver| AuthService[AuthService]
+    AuthService -->|check token_version| DB[(users table)]
+```
+
+## Business Process
+
+### Login / Authenticate Flow
+
+```mermaid
+sequenceDiagram
+    participant C as Client
+    participant API as Controller API
+    participant AS as AuthService
+    participant DB as Database
+
+    C->>API: POST /login or /authenticate (username + password)
+    API->>DB: authenticate_user()
+    DB-->>API: user (with token_version)
+    API->>AS: create_access_token(user, ver)
+    API->>AS: create_refresh_token(user, ver)
+    AS-->>API: access_token (type: access, exp: 15min)
+    AS-->>API: refresh_token (type: refresh, exp: 30d)
+    API-->>C: { access_token, token_type, refresh_token }
+```
+
+### Refresh Flow (Silent Renewal)
+
+```mermaid
+sequenceDiagram
+    participant C as Client
+    participant API as Controller API
+    participant AS as AuthService
+    participant DB as Database
+
+    Note over C: access_token expired
+    C->>API: POST /refresh { refresh_token }
+    API->>AS: get_token_data(refresh_token)
+    AS-->>API: { username, ver, token_use: "refresh" }
+    API->>DB: get_user_by_username()
+    DB-->>API: user (with current token_version)
+    Note over API,DB: rejects if user not found, inactive, or token_version mismatch
+    API->>AS: create_access_token(user, ver)
+    API->>AS: create_refresh_token(user, ver)
+    AS-->>API: new access_token (sliding window)
+    AS-->>API: new refresh_token (sliding window)
+    API-->>C: { access_token, token_type, refresh_token }
+    C->>API: Retry original request with new access_token
+```
+
+### Logout — Token Revocation
+
+```mermaid
+sequenceDiagram
+    participant C as Client
+    participant API as Controller API
+    participant DB as Database
+
+    C->>API: POST /logout (Bearer access_token)
+    API->>DB: logout_user(user_id) → token_version += 1
+    DB-->>API: done
+    API-->>C: 204 No Content
+    Note over C, DB: All existing access and refresh tokens with old ver are now invalid
+```
+
+## API Endpoints
+
+| Method | Path | Description | Authentication |
+|--------|------|-------------|---------------|
+| POST | `/v3/access/users/login` | Login with form data, returns access + refresh tokens | Public |
+| POST | `/v3/access/users/authenticate` | Login with JSON, returns access + refresh tokens | Public |
+| POST | `/v3/access/users/refresh` | Exchange a refresh token for a new access token + refresh token | Public (token itself proves identity) |
+| POST | `/v3/access/users/logout` | Revoke all tokens for the current user | Bearer token required |
+
+### POST /v3/access/users/refresh
+
+**Request:**
+```json
+{
+  "refresh_token": "<refresh_token>"
+}
+```
+
+**Response 200:**
+```json
+{
+  "access_token": "<new_access_token>",
+  "token_type": "bearer",
+  "refresh_token": "<new_refresh_token>"
+}
+```
+
+**Error Responses:**
+- `401` — Invalid, expired, or revoked refresh token
+- `422` — Missing `refresh_token` field in request body
+
+## Security Design
+
+### Token Claims
+
+| Claim | Access Token | Refresh Token |
+|-------|-------------|---------------|
+| `sub` | username | username |
+| `exp` | 24h (configurable) | 30d (configurable) |
+| `ver` | user's `token_version` | user's `token_version` |
+| `type` | `"access"` | `"refresh"` |
+
+### Key Security Properties
+
+- **Type-based isolation**: Access tokens (`type: access`) are rejected by `/refresh`. Refresh tokens (`type: refresh`) are rejected by HTTP and WebSocket authentication paths. This prevents a stolen long-lived refresh token from being used directly for API access.
+- **Token version integration**: Both token types carry the user's `token_version`. `logout` increments `token_version` in the database, immediately invalidating all outstanding access and refresh tokens.
+- **Stateless (no replay detection)**: Since there is no `refresh_tokens` database table, a stolen refresh token remains valid until its `exp` or until the user logs out. This is an accepted trade-off for avoiding a new table and migration.
+- **Sliding window**: Each `/refresh` call issues a new refresh token with a fresh expiry, keeping active sessions alive indefinitely until logout or inactivity.
+
+### Implementation Files
+
+- `gns3server/services/authentication.py` — `_create_token`, `create_access_token`, `create_refresh_token`, `get_token_data`
+- `gns3server/api/routes/controller/users.py` — `refresh_access_token` endpoint handler
+- `gns3server/api/routes/controller/dependencies/authentication.py` — `_reject_refresh_token` guard in HTTP and WebSocket paths
+- `gns3server/schemas/controller/tokens.py` — `Token`, `TokenData`, `RefreshTokenRequest` models
+- `gns3server/schemas/config.py` — `jwt_refresh_token_expire_minutes` configuration
+
+## Configuration
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `Controller.jwt_access_token_expire_minutes` | 1440 (24h) | Access token TTL. Web UI recommends 15 min. |
+| `Controller.jwt_refresh_token_expire_minutes` | 43200 (30d) | Refresh token TTL. |
+| `Controller.jwt_secret_key` | (random) | HMAC signing key for all JWT tokens. |
+
+## Notes
+
+- **Web UI integration**: The client should implement a response interceptor that catches 401, silently calls `/refresh`, and retries the original request. Multiple concurrent 401s should be queued with a single refresh request.
+- **No per-session revocation**: All tokens for a user share the same `token_version`. Logout revokes everything. Per-session granularity would require adding a `refresh_tokens` table.
+- **Rate limiting**: `/refresh` is a public endpoint with a valid credential (the refresh token). Rate limiting is recommended if brute-force attacks are a concern.

docs/features/statistics-api.md

@@ -0,0 +1,236 @@
+<!--
+SPDX-License-Identifier: CC-BY-SA-4.0
+See LICENSE file for licensing information.
+-->
+
+> This documentation is organized by AI with reference to actual code. AI can make mistakes — please verify against the source code when in doubt.
+
+
+# Statistics API
+
+## Overview
+
+Aggregated server statistics API for monitoring dashboards. Collects compute resources, project/node/link counts, and Web Wireshark container status in a single request.
+
+## Architecture
+
+```mermaid
+graph TB
+    Client["Client (Dashboard)"]
+
+    subgraph Controller["GET /v3/statistics"]
+        direction TB
+        F1["1. Compute Resources<br/>GET compute/statistics"]
+        F2["2. Project/Node/Link<br/>Iterate in memory"]
+        F3["3. Web Wireshark<br/>Docker API + docker stats"]
+    end
+
+    Compute["Compute Nodes<br/>(psutil)"]
+    Memory["Controller<br/>(in-memory data)"]
+    Docker["Docker Daemon"]
+
+    Client -->|GET /v3/statistics| Controller
+    F1 -->|HTTP| Compute
+    F2 -->|read| Memory
+    F3 -->|Docker API| Docker
+```
+
+## Data Collection Flow
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant Controller as Controller API
+    participant Compute as Compute Nodes
+    participant Docker as Docker Daemon
+
+    Client->>Controller: GET /v3/statistics
+
+    rect rgb(240, 248, 255)
+        Note over Controller: 1. Compute Resources
+        loop For each compute
+            Controller->>Compute: GET /statistics
+            Compute-->>Controller: psutil data
+            Note over Controller: skip on error
+        end
+    end
+
+    rect rgb(240, 255, 240)
+        Note over Controller: 2. Projects / Nodes / Links
+        Note over Controller: Count projects by status (opened/closed)
+        Note over Controller: Count nodes: open→by_type+by_status, closed→by_type only
+        Note over Controller: Count links: total + capturing
+    end
+
+    rect rgb(255, 248, 240)
+        Note over Controller: 3. Web Wireshark
+        loop For opened projects only
+            Controller->>Docker: Query container status
+            Controller->>Docker: docker stats (2s timeout)
+            Docker-->>Controller: Container resource usage
+        end
+    end
+
+    Controller-->>Client: JSON response
+```
+
+## API Endpoints
+
+| Method | Path | Description | Auth |
+|--------|------|-------------|------|
+| GET | `/v3/statistics` | Aggregated server statistics | Session |
+| GET | `/v3/compute/statistics` | Single compute resource stats | Basic Auth |
+
+## Response
+
+```json
+{
+  "computes": [
+    {
+      "compute_id": "local",
+      "compute_name": "Local",
+      "statistics": {
+        "memory_total": 16777216000,
+        "memory_free": 8000000000,
+        "memory_used": 8777216000,
+        "swap_total": 2147479552,
+        "swap_free": 1500000000,
+        "swap_used": 647279552,
+        "cpu_usage_percent": 45,
+        "memory_usage_percent": 52,
+        "swap_usage_percent": 30,
+        "disk_usage_percent": 67,
+        "load_average_percent": [12, 8, 5]
+      }
+    }
+  ],
+  "projects": {
+    "total": 5,
+    "opened": 3,
+    "closed": 2
+  },
+  "nodes": {
+    "total": 42,
+    "open_project_nodes": 30,
+    "closed_project_nodes": 12,
+    "by_type": { "qemu": 20, "docker": 12, "dynamips": 6, "vpcs": 4 },
+    "by_status": { "started": 25, "stopped": 12, "suspended": 5 }
+  },
+  "links": {
+    "total": 38,
+    "capturing": 2
+  },
+  "webwireshark": {
+    "total_containers": 1,
+    "running_containers": 1,
+    "active_sessions": 2,
+    "containers": [
+      {
+        "project_id": "e16e2b51-9ba9-403b-9df4-b2915d7508a3",
+        "project_name": "test-project",
+        "container_id": "6edc9029bac0",
+        "status": "running",
+        "running": true,
+        "active_sessions": 2,
+        "memory_limit": "2.0 GB",
+        "cpu_limit": "1.0",
+        "pids_limit": 1000,
+        "memory": "272.5MiB / 4GiB",
+        "cpu": "0.23%",
+        "pids": 69
+      }
+    ]
+  }
+}
+```
+
+## Field Reference
+
+### `computes[]`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `compute_id` | string | Compute identifier |
+| `compute_name` | string | Display name |
+| `statistics` | object | Resource usage (see below) |
+
+**`statistics` fields:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `memory_total` | int | Total RAM (bytes) |
+| `memory_free` | int | Available RAM (bytes) |
+| `memory_used` | int | Used RAM (bytes) |
+| `swap_total` | int | Total swap (bytes) |
+| `swap_free` | int | Free swap (bytes) |
+| `swap_used` | int | Used swap (bytes) |
+| `cpu_usage_percent` | int | CPU usage 0-100 |
+| `memory_usage_percent` | int | RAM usage 0-100 |
+| `swap_usage_percent` | int | Swap usage 0-100 |
+| `disk_usage_percent` | int | Project dir disk usage 0-100 |
+| `load_average_percent` | int[] | Load avg per core (1/5/15 min) |
+
+### `projects`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `total` | int | All projects |
+| `opened` | int | Currently opened |
+| `closed` | int | Currently closed |
+
+### `nodes`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `total` | int | All nodes across projects |
+| `open_project_nodes` | int | Nodes in opened projects (has runtime status) |
+| `closed_project_nodes` | int | Nodes in closed projects (from topology JSON, no status) |
+| `by_type` | object | Count by node type (qemu, docker, etc.) |
+| `by_status` | object | Count by status — **open project nodes only** |
+
+### `links`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `total` | int | All links across projects |
+| `capturing` | int | Links currently capturing |
+
+### `webwireshark`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `total_containers` | int | All Wireshark containers |
+| `running_containers` | int | Currently running |
+| `active_sessions` | int | Active capture sessions |
+| `containers` | array | Per-container details (opened projects only) |
+
+**`containers[]` fields:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `project_id` | string | Project UUID |
+| `project_name` | string | Project name |
+| `container_id` | string | Docker container ID (12 chars) |
+| `status` | string | Container status (running, exited, etc.) |
+| `running` | bool | Is running |
+| `active_sessions` | int | Active captures in this project |
+| `memory_limit` | string | Configured memory limit (e.g. `"2.0 GB"`, `"unlimited"`) |
+| `cpu_limit` | string | Configured CPU limit (e.g. `"1.0"`, `"unlimited"`) |
+| `pids_limit` | int/string | Process limit (e.g. `1000`, `"unlimited"`) |
+| `memory` | string | Live memory usage (conditional, see notes) |
+| `cpu` | string | Live CPU usage (conditional, see notes) |
+| `pids` | int | Live process count (conditional, see notes) |
+
+## Error Responses
+
+| Status | Description |
+|--------|-------------|
+| 401 | Unauthorized — invalid or missing session |
+| 500 | Internal server error |
+
+## Notes
+
+- **Compute stats are best-effort**: if a compute is unreachable, it is skipped (logged as error) and other data is still returned
+- **`by_status` only reflects open project nodes**: closed projects store topology in JSON without runtime status
+- **Live container stats** (`memory`, `cpu`, `pids`) are only present when `docker stats` succeeds — may be absent if the Docker daemon is slow (2s timeout)
+- **Web Wireshark containers** are only queried for opened projects

docs/features/vendor-nos-xrd.md

@@ -0,0 +1,208 @@
+<!--
+SPDX-License-Identifier: CC-BY-SA-4.0
+See LICENSE file for licensing information.
+-->
+
+> This documentation is organized by AI with reference to actual code. AI can make mistakes — please verify against the source code when in doubt.
+
+
+# Cisco XRd Control Plane (Vendor NOS Adaptation)
+
+## Overview
+
+Cisco XRd Control Plane runs as a first-class GNS3 Docker router node by
+combining the existing vendor NOS path (`console_type: "docker_exec"` +
+`GNS3_SKIP_INIT=1`, see [docker-exec-console.md](./docker-exec-console.md))
+with four generic server mechanisms added for heavy/systemd NOS containers:
+`/dev/shm` and host-device injection, config-file injection (`extra_configs`),
+and udev masking. XRd itself is pure appliance configuration — no image
+rebuild, no source patching.
+
+## Why XRd must take the vendor path
+
+XRd boots `/usr/sbin/init` (systemd) as PID 1. GNS3's generic init.sh
+wrapper chain (`/gns3/init.sh → su → run-cmd.sh → /usr/sbin/init`) crashes
+XRd's glibc loader with `Fatal glibc error: dl-call-libc-early-init.c:37
+(sym != NULL)` (SIGABRT loop). With `GNS3_SKIP_INIT=1` the container runs
+its native entrypoint directly and boots cleanly — same arrangement as
+SR Linux.
+
+## Architecture
+
+```mermaid
+graph TB
+    subgraph Appliance["XRd appliance (.gns3a) — pure configuration"]
+        ENV["environment: GNS3_SKIP_INIT / GNS3_CONSOLE_CMD / GNS3_MASK_UDEV / GNS3_SHM_SIZE / GNS3_DEVICES + XR_*"]
+        XC["extra_configs: /firstboot.cfg"]
+        XV["extra_volumes: /xr-storage + /xr-storage-shadow"]
+    end
+    subgraph Server["gns3-server (generic mechanisms)"]
+        CREATE["DockerVM.create() HostConfig"]
+        MASK["GNS3_MASK_UDEV → /dev/null binds"]
+        HOSTCFG["ShmSize / Devices"]
+        CFGINJ["extra_configs → RO single-file bind"]
+        VBRIDGE["VendorDockerVM volume bridge"]
+        HOSTCHK["host-readiness check (read-only)"]
+    end
+    subgraph Container["XRd container"]
+        SYSTEMD["systemd (/usr/sbin/init)"]
+        XR["XR control plane"]
+        XRS["/xr-storage (persisted, live data layer)"]
+    end
+    ENV --> CREATE --> SYSTEMD
+    ENV --> MASK & HOSTCFG
+    XC --> CFGINJ
+    XV --> VBRIDGE --> XRS
+    HOSTCHK -.->|"warn: inotify/file-max/fuse"| Server
+```
+
+## Mechanisms added (all generic, XRd is just the first consumer)
+
+| Mechanism | Interface | Effect | Where |
+|-----------|-----------|--------|-------|
+| shm size | `GNS3_SHM_SIZE=1024` (MB) in `environment` | native `HostConfig.ShmSize` at create time — works with or without init.sh | `docker_vm.py` `create()` |
+| host devices | `GNS3_DEVICES=/dev/fuse` (`docker run --device` syntax, space-separated) | native `HostConfig.Devices` | `docker_vm.py` `_format_devices()` |
+| config injection | `extra_configs: [{target, content}]` (template/node/appliance schema field) | content written under the node dir, bind-mounted **read-only** at `target` — seeds NOS startup configs without rebuilding the image | `docker_vm.py` `_mount_binds()`; persisted in `docker_templates.extra_configs` (Alembic migration) |
+| udev masking | `GNS3_MASK_UDEV=1` | `/dev/null` over the 5 udev systemd units **and** `/bin|/sbin|/usr/bin/udevadm` | `docker_vm.py` `create()` |
+| generic unit mask | `GNS3_MASK_SYSTEMD=u1,u2` | `/dev/null` over arbitrary `/etc/systemd/system/<unit>` | `docker_vm.py` `create()` |
+| graceful stop | `GNS3_STOP_TIMEOUT=60` (seconds; default 60, max 210) | explicit user stop sends SIGTERM + a grace period (Docker SIGKILLs once it expires) instead of the base class' immediate kill — systemd NOS images require a graceful shutdown; internal paths (delete/update/close) keep the immediate kill since the container is force-deleted right after. Max 210 keeps the +30 s HTTP margin inside the controller's 240 s stop budget | `vendor_docker_vm.py` `_terminate_container()` |
+| host check | automatic at Docker connect | read-only `/proc` check of inotify/file-max/FUSE; warns with exact fix commands (server is unprivileged — it can only check) | `compute/docker/__init__.py` `_check_host_readiness()` |
+
+`GNS3_*` variables are consumed host-side only and never forwarded into the
+container (existing GNS3 behaviour); `XR_*` variables pass through normally.
+
+## Host-disturbance root causes (all fixed)
+
+A privileged systemd container can disturb the *host* desktop. Three
+independent causes were isolated with plain-`docker run` A/B/C experiments
+(udevd coldplug / busybox chown crash / direct `udevadm trigger`):
+
+| Host symptom | Root cause | Fix |
+|---|---|---|
+| Audio muted on every node start | container `systemd-udevd` coldplug replays **all** devices it can see (privileged → host `/sys`) | `GNS3_MASK_UDEV=1` (unit masks) |
+| USB reconnects (mouse notification), journal noise | XRd's own `xr_startup.sh` calls `udevadm trigger --action=add --parent-match=<usb>` (USB license-dongle probing) — a direct binary call, unit masks don't stop it | `GNS3_MASK_UDEV=1` (udevadm null-bind) |
+| Same USB/journal noise + broken persistence | static busybox `chown` dlopens container NSS modules → glibc abort → per-file coredump storm → host `systemd-coredump` rescans devices | vendor volume path prefers the container's own `chown` (`vendor_docker_vm.py`) |
+
+Diagnostics: `udevadm monitor --kernel --udev` (uevent stream),
+`docker exec <cid> grep -n udevadm /opt/cisco/install-iosxr/base/etc/xr_startup.sh`.
+Note: "journal corrupted" messages with varying machine-IDs come from the
+*container's* journald (random machine-id per start), not the host journal.
+
+## XRd appliance recipe
+
+| Field | Value |
+|-------|-------|
+| `image` | official `ios-xr/xrd-control-plane:<ver>` — no wrapper image needed |
+| `console_type` | `docker_exec` |
+| `extra_volumes` | `["/xr-storage", "/xr-storage-shadow"]` |
+| `extra_configs` | `{target: /firstboot.cfg, content: <XR CLI first-boot config>}` |
+
+```
+GNS3_SKIP_INIT=1
+GNS3_CONSOLE_CMD=/pkg/bin/xr_cli.sh
+GNS3_MASK_UDEV=1
+GNS3_SHM_SIZE=1024
+GNS3_DEVICES=/dev/fuse
+GNS3_STOP_TIMEOUT=40
+XR_FIRST_BOOT_CONFIG=/firstboot.cfg
+XR_MGMT_INTERFACES=linux:eth0,xr_name=Mg0/RP0/CPU0/0,chksum,snoop_v4,snoop_v6
+XR_INTERFACES=linux:eth1,xr_name=Gi0/0/0/0;linux:eth2,xr_name=Gi0/0/0/1;...
+```
+
+XRd-specific gotchas (image-side, not GNS3):
+
+- Management interface xr_name is **`Mg0/RP0/CPU0/0`** (short prefix, `CPU0`
+  without slash). `MgmtEth0/RP0/CPU/0` is rejected: "not a valid
+  rack/slot/instance/port combination".
+- `XR_INTERFACES` must list exactly `adapters − 1` data interfaces (eth0 is
+  management). Changing the adapter count requires regenerating the string.
+- **Persistence layout**: in the *image*, `/xr-storage/{config,disk1,log,
+  scratch}` are symlinks into `/xr-storage-shadow` (a pristine spare copy of
+  the initial state). At boot the bootstrap replaces the symlinks with real
+  directories, and XR writes everything — committed config (`commitdb`,
+  `running`) included — into **`/xr-storage`**, never touching the shadow
+  again. This mirrors containerlab, which bind-mounts `/xr-storage`
+  (`nodes/xrd/xrd.go`: "persist data by mounting /xr-storage"). The
+  appliance persists **both** paths so writes land on host regardless of
+  whether they happen before or after the symlink→directory transition.
+- `XR_FIRST_BOOT_CONFIG` only applies when XR's config storage is empty
+  (first boot). To re-seed, delete and recreate the node.
+- The official image ships no default login; the first-boot config must
+  create one (e.g. `username admin / group root-lr / secret ...`).
+- Docker mounts are fixed at container *create* time: after changing a
+  template's `extra_volumes`, existing nodes must be deleted and recreated
+  (a stop/start keeps the old mounts).
+- Host sysctls (XRd's own requirements, same for containerlab):
+  `fs.inotify.max_user_instances=64000`, `max_user_watches=524288`,
+  `fs.file-max=1000000`, FUSE module loaded. GNS3 warns about these at
+  Docker connect; the admin raises them once. XRd also warns (non-fatal)
+  about `net.core.*` socket buffer sizes.
+
+## Business process
+
+```mermaid
+sequenceDiagram
+    participant U as User
+    participant S as gns3-server
+    participant D as Docker daemon
+    participant X as XRd container
+    U->>S: create node from template
+    S->>S: parse GNS3_* env host-side
+    S->>D: container create (ShmSize, Devices, /dev/null binds, firstboot.cfg RO bind)
+    U->>S: start
+    S->>X: container start (native entrypoint /usr/sbin/init)
+    Note over X: systemd boots; udevd + udevadm masked → host untouched
+    S->>X: docker exec volume bridge (container's own chown)
+    U->>S: open console
+    S->>X: docker exec pty: /pkg/bin/xr_cli.sh
+    X-->>U: IOS XR CLI (first boot: apply /firstboot.cfg, save to /xr-storage-shadow)
+```
+
+## Troubleshooting
+
+| Symptom | Cause / fix |
+|---|---|
+| Node exits 139, `Fatal glibc error ... sym != NULL` in logs | init.sh wrapper path — set `GNS3_SKIP_INIT=1` **and** `console_type: docker_exec` (the flag is only honoured on the vendor class) |
+| `XR_FIRST_BOOT_CONFIG ... File not found` | env path and `extra_configs` target disagree (e.g. `/firstboot.cfg` vs `/first_boot.cfg`), or entry missing |
+| Console stuck at `Username:` with no credentials | image has no default user; provide a first-boot config creating one, then **recreate** the node (first-boot only runs on empty config storage) |
+| `Invalid interface entries ... XR_MGMT_INTERFACES` | use `xr_name=Mg0/RP0/CPU0/0` |
+| Host audio muted / USB reconnects when the node starts | set `GNS3_MASK_UDEV=1` |
+| Config lost across stop/start | `extra_volumes` must include `/xr-storage` (XR's live data layer; the shadow alone is only a pristine spare). Changing `extra_volumes` requires deleting and recreating the node — Docker mounts are fixed at create time |
+| Two nodes can't ping, only one side ARPs | GNS3 link wiring bug (UDP self-loop on one end), not XRd — fixed (port-allocation race); on older builds delete and re-create the link; see [link-udp-self-loop](../bugs/link-udp-self-loop.md) |
+| Compute log: busybox coredump storm | fixed by the container-chown change; verify gns3-server is current |
+
+## Notes
+
+- All four mechanisms are opt-in: nodes that don't set the variables or the
+  field get byte-identical container configuration.
+- `extra_configs` is a schema field (unlike the env knobs) because the
+  `environment` field is line-delimited and cannot carry multi-line file
+  content.
+- Template fields live in three places (pydantic schema, DB column, Alembic
+  migration) — see the `extra_configs` DB migration when adding new ones.
+- `net.core.*` socket-buffer requirements are not yet part of the
+  host-readiness check (XRd warns about them itself, non-fatally).
+
+## References
+
+- `gns3server/compute/docker/docker_vm.py` — HostConfig env injection,
+  `_UDEV_UNITS`/`_UDEVADM_PATHS`, `extra_configs` binds, `_format_devices()`
+- `gns3server/compute/docker/vendor_docker_vm.py` — vendor path, volume
+  bridge, container-chown
+- `gns3server/compute/docker/__init__.py` — `_check_host_readiness()`
+- `gns3server/schemas/common.py` — `ExtraConfig`
+- `gns3server/db/models/templates.py` + `db_migrations/` — persistence
+- [docker-exec-console.md](./docker-exec-console.md) — the vendor NOS base
+  (docker_exec console, SKIP_INIT volume persistence)
+- containerlab `nodes/xrd/xrd.go` — reference for XRd env defaults and
+  `/xr-storage` persistence
+
+## Version History
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 1.4 | 2026-08-15 | Code-review hardening: stop-query HTTP timeout scales with `GNS3_STOP_TIMEOUT` (values >300 s no longer abort); overlapping mask/config bind targets deduplicated (Docker "Duplicate mount point"); `ExtraConfig.target` validated at save time and directory forms rejected; host-readiness check no longer aborts on one unreadable `/proc/sys` key; base env parser strips trailing commas; vendor env knobs re-parsed on create (PUT environment takes effect); graceful stop limited to explicit user stop (delete/update/close keep the immediate kill); extra_configs under a persisted volume warns. |
+| 1.3 | 2026-08-14 | Persistence corrected: XR's live data layer is `/xr-storage` (the image's symlink farm is materialized into real directories at bootstrap; `/xr-storage-shadow` is a pristine spare) — the appliance persists both. Vendor containers now stop gracefully (SIGTERM + `GNS3_STOP_TIMEOUT` grace, default 60 s) instead of being SIGKILLed on the spot. |
+| 1.2 | 2026-08-14 | Link UDP self-loop root-caused to a port-allocation race and fixed — see [link-udp-self-loop](../bugs/link-udp-self-loop.md) (now marked Fixed). |
+| 1.1 | 2026-08-14 | Datapath validated end-to-end (XRd brings its own interfaces up; ARP/ICMP bidirectional). Add troubleshooting entry for the one-way-link symptom (GNS3 link UDP self-loop bug, see bugs/link-udp-self-loop.md). |
+| 1.0 | 2026-08-14 | Initial documentation of the XRd control-plane adaptation: vendor path requirement, shm/devices/extra_configs/udev-mask mechanisms, host-disturbance root causes, appliance recipe. |

docs/features/vnc-websocket-console.md

@@ -0,0 +1,402 @@
+<!--
+SPDX-License-Identifier: CC-BY-SA-4.0
+See LICENSE file for licensing information.
+-->
+
+> This documentation is organized by AI with reference to actual code. AI can make mistakes — please verify against the source code when in doubt.
+
+
+# VNC WebSocket Console
+
+## Overview
+
+GNS3 server supports WebSocket-based VNC console access, enabling browser-based graphical console connections to QEMU and Docker VMs without requiring standalone VNC client applications.
+
+This implementation uses GNS3's API layer as a transparent WebSocket-to-TCP proxy, forwarding binary VNC protocol data between the browser and the VM's VNC server.
+
+## Architecture
+
+### Connection Flow
+
+```mermaid
+graph LR
+    A[Browser noVNC] -->|WebSocket binary| B[GNS3 Controller]
+    B -->|WebSocket + BasicAuth + SSL| C[GNS3 Compute]
+    C -->|TCP| D[QEMU/Docker VNC :5900]
+```
+
+**Controller** acts as a WebSocket-to-WebSocket relay (JWT auth, IPv6 handling).
+**Compute** acts as a WebSocket-to-TCP bridge (validates node state, opens VNC TCP connection).
+
+### Components
+
+1. **Browser (noVNC)**
+   - HTML5 VNC client running in the browser
+   - Connects via WebSocket using `binary` subprotocol
+   - Handles RFB protocol (Remote Frame Buffer) for VNC
+
+2. **GNS3 Controller API**
+   - WebSocket endpoint: `/v3/projects/{project_id}/nodes/{node_id}/console/vnc`
+   - Authentication: JWT token via query parameter
+   - Authorization: RBAC privilege check via `has_privilege_on_websocket("Node.Console")`
+   - Proxies WebSocket to compute node (WebSocket-to-WebSocket relay)
+   - Handles IPv6 addresses by wrapping in brackets
+
+3. **GNS3 Compute API**
+   - WebSocket endpoint: `/v3/compute/projects/{project_id}/{node_type}/nodes/{node_id}/console/vnc`
+   - Authentication: HTTP Basic Auth via `ws_compute_authentication()`
+   - Establishes TCP connection to VNC server, bridges WebSocket ↔ TCP
+
+4. **Node (QEMU/Docker)**
+   - VNC server listening on configured port (default: 5900+)
+   - RFB protocol for remote display
+
+## API Endpoints
+
+### Controller WebSocket Endpoint
+
+**URL**: `ws://{controller_host}:{port}/v3/projects/{project_id}/nodes/{node_id}/console/vnc?token={jwt_token}`
+
+**Authentication**:
+- JWT token via query parameter
+- User must have `Node.Console` privilege
+
+**WebSocket Subprotocols**:
+- Accepts: `binary`
+- Used by noVNC for binary data transfer
+
+**Request Example**:
+```javascript
+const token = "eyJ0eXAiOiJKV1QiLCJhbGc...";
+const wsUrl = `ws://localhost:3080/v3/projects/${projectId}/nodes/${nodeId}/console/vnc?token=${token}`;
+
+const ws = new WebSocket(wsUrl, 'binary');
+ws.binaryType = 'arraybuffer';
+```
+
+### Compute WebSocket Endpoint
+
+**URL**: `ws://{compute_host}:{port}/v3/compute/projects/{project_id}/{node_type}/nodes/{node_id}/console/vnc`
+
+**Authentication**:
+- HTTP Basic Auth via `ws_compute_authentication()` dependency
+- Configured via `settings.Server.compute_username` (default: `gns3`) and `settings.Server.compute_password` (default: empty)
+
+**Response**:
+- Bidirectional binary WebSocket connection
+- Transparent VNC protocol forwarding
+
+## Supported Node Types
+
+### QEMU VMs
+
+**Console Type Configuration**:
+```json
+{
+  "console_type": "vnc",
+  "console": 5900,
+  "console_resolution": "1024x768"
+}
+```
+
+**QEMU Parameters**:
+```bash
+-vnc :0  # VNC on display 0 (port = 5900 + display)
+```
+
+**Implementation**:
+- File: `gns3server/api/routes/compute/qemu_nodes.py`
+- Endpoint: `/{node_id}/console/vnc`
+- Method: `start_vnc_websocket_console(websocket)`
+
+### Docker Containers
+
+**Console Type Configuration**:
+```json
+{
+  "console_type": "vnc",
+  "console": 5900,
+  "console_resolution": "1024x768",
+  "console_http_port": 8080,
+  "console_http_path": "/"
+}
+```
+
+**Implementation**:
+- File: `gns3server/api/routes/compute/docker_nodes.py`
+- Endpoint: `/{node_id}/console/vnc`
+- Method: `start_vnc_websocket_console(websocket)`
+
+## WebSocket Data Forwarding
+
+### Compute Layer (WebSocket ↔ TCP)
+
+**Location**: `gns3server/compute/base_node.py` — `start_vnc_websocket_console()`
+
+1. Validates node is started and `console_type == "vnc"`; closes WebSocket with code 1000 otherwise
+2. Opens TCP connection to VNC server at `console_host:console_port`
+3. Runs two concurrent tasks via `asyncio.wait(FIRST_COMPLETED)`:
+   - `ws_forward()`: WebSocket → TCP (catches `WebSocketDisconnect`)
+   - `vnc_forward()`: TCP → WebSocket (reads 65536-byte buffer)
+4. Cancels pending tasks, closes TCP writer on completion
+
+### Controller Layer (WebSocket ↔ WebSocket)
+
+**Location**: `gns3server/api/routes/controller/nodes.py` — `vnc_console()`
+
+1. Authenticates user via `has_privilege_on_websocket("Node.Console")` dependency
+2. Constructs compute URL with IPv6 bracket handling
+3. Connects to compute WebSocket using `aiohttp.ws_connect()` with HTTP Basic Auth and SSL context
+4. Uses `asyncio.ensure_future()` for client→compute forwarding, `async for msg` iteration for compute→client
+
+### Data Flow
+
+```mermaid
+sequenceDiagram
+    participant B as Browser (noVNC)
+    participant C as Controller
+    participant W as Compute
+    participant V as VNC Server
+
+    B->>C: WebSocket connect (binary, JWT token)
+    C->>W: WebSocket connect (binary, BasicAuth, SSL)
+    W->>V: TCP connect (asyncio.open_connection)
+
+    Note over B,V: Bidirectional binary forwarding active
+
+    B->>C: WebSocket binary frame
+    C->>W: aiohttp send_bytes()
+    W->>V: TCP write(data)
+
+    V->>W: TCP data (read 65536)
+    W->>C: WebSocket binary frame
+    C->>B: send_bytes()
+```
+
+## Authentication & Authorization
+
+### Controller Layer
+
+1. **Authentication**:
+   - JWT token validation via `has_privilege_on_websocket("Node.Console")` dependency
+   - Token passed as query parameter: `?token={jwt}`
+
+2. **Authorization**:
+   - RBAC privilege check: `Node.Console`
+   - Per-node access control
+
+3. **WebSocket Subprotocol**:
+   - Client requests: `binary`
+   - Server accepts: `binary` (if requested)
+
+### Compute Layer
+
+1. **Authentication**:
+   - HTTP Basic Auth
+   - Credentials from controller config
+   - Username: `settings.Server.compute_username`
+   - Password: `settings.Server.compute_password`
+
+2. **Node Validation**:
+   - Check node exists
+   - Check node is started
+   - Check console type is `vnc`
+
+## Configuration
+
+### Server Settings
+
+**Controller Configuration** (`gns3-server.conf`):
+```ini
+[Server]
+host = 0.0.0.0
+port = 3080
+```
+
+**Compute Configuration** (same file):
+```ini
+[Server]
+compute_username = gns3
+compute_password =    # empty by default, must be set for compute auth
+```
+
+### VNC Port Range
+
+VNC console ports are allocated from a configurable range (`gns3server/schemas/config.py`):
+
+| Setting | Default | Range |
+|---------|---------|-------|
+| `vnc_console_start_port_range` | 5900 | 5900–65535 |
+| `vnc_console_end_port_range` | 10000 | 5900–65535 |
+
+Validation: `vnc_console_end_port_range` must be greater than `vnc_console_start_port_range`.
+
+### Node Settings
+
+**QEMU VM Example**:
+```json
+{
+  "name": "vm-1",
+  "node_type": "qemu",
+  "console_type": "vnc",
+  "console": 5900,
+  "console_resolution": "1280x720",
+  "properties": {
+    "qemu_path": "/usr/bin/qemu-system-x86_64"
+  }
+}
+```
+
+**Docker Container Example**:
+```json
+{
+  "name": "container-1",
+  "node_type": "docker",
+  "console_type": "vnc",
+  "console": 5900,
+  "console_resolution": "1024x768",
+  "console_http_port": 8080
+}
+```
+
+## Troubleshooting
+
+### Common Issues
+
+**1. "Node is not started"**
+- **Symptom**: WebSocket closes immediately
+- **Solution**: Start the VM before opening console
+- **API Check**: `GET /v3/projects/{project_id}/nodes/{node_id}` → verify `status == "started"`
+
+**2. "Console type is not vnc"**
+- **Symptom**: WebSocket closes with error
+- **Solution**: Set node console_type to "vnc"
+- **API Update**: `PUT /v3/projects/{project_id}/nodes/{node_id}` with `{"console_type": "vnc"}`
+
+**3. "Cannot connect to VNC server"**
+- **Symptom**: Connection timeout
+- **Possible Causes**:
+  - VNC server not listening
+  - Port conflict
+  - Firewall blocking connection
+- **Verification**:
+  ```bash
+  # Check if VNC is listening
+  netstat -tlnp | grep 5900
+
+  # Check QEMU process
+  ps aux | grep qemu
+  ```
+
+**4. WebSocket Subprotocol Negotiation Failed**
+- **Symptom**: Connection rejected during handshake
+- **Solution**: Ensure noVNC sends `binary` subprotocol
+- **Browser Console Check**:
+  ```javascript
+  console.log(ws.protocol);  // Should be "binary"
+  ```
+
+**5. Authentication Errors**
+- **Symptom**: HTTP 401/403 responses
+- **Controller**: Check JWT token is valid and not expired
+- **Compute**: Verify compute username/password in config
+
+### Debug Logging
+
+**Enable Detailed Logging**:
+```ini
+[gns3server]
+debug = true
+```
+
+**Check Controller Logs**:
+```bash
+# Look for WebSocket connection messages
+grep "VNC console WebSocket" /var/log/gns3/gns3.log
+```
+
+**Check Compute Logs**:
+```bash
+# Look for VNC forwarding messages
+grep "Connected to VNC server" /var/log/gns3/gns3.log
+```
+
+**Browser Console**:
+```javascript
+// Enable noVNC debugging
+RFB.messages.log = function(msg) { console.log(msg); };
+```
+
+## Security
+
+### Authentication
+
+1. **Controller → Client**
+   - JWT token with expiration
+   - RBAC authorization
+   - Privilege: `Node.Console`
+
+2. **Controller → Compute**
+   - HTTP Basic Auth via `aiohttp.BasicAuth`
+   - SSL context from `Controller.instance().ssl_context()`
+   - Raises `ControllerForbiddenError` if `compute_username` is not set
+
+3. **VNC Server**
+   - Optional VNC password (QEMU only)
+   - Configured via node properties
+
+### Network Security
+
+**Recommendations**:
+1. Use HTTPS/WSS for production deployments
+2. Firewall compute API ports
+3. Use short-lived JWT tokens
+4. Enable VNC password for sensitive VMs
+
+**Example**:
+```bash
+# Controller with TLS
+gns3server --ssl --cert /path/to/cert.pem --key /path/to/key.pem
+
+# VNC with password
+qemu-system-x86_64 -vnc :0,password
+```
+
+### WebSocket Security
+
+**Subprotocol Validation**:
+- Only `binary` subprotocol is accepted
+- Prevents protocol downgrade attacks
+
+**Origin Validation**:
+- Browser enforces same-origin policy
+- Configure CORS if using separate domains
+
+## Limitations
+
+1. **Single Client per VNC Port**
+   - VNC protocol supports one client at a time
+   - New connections disconnect existing clients
+
+2. **No Audio Redirection**
+   - VNC protocol does not support audio
+
+3. **No USB Redirection**
+   - VNC protocol does not support device redirection
+
+4. **Performance Overhead**
+   - WebSocket-to-TCP bridging adds processing overhead compared to native VNC clients
+
+## References
+
+- [RFB Protocol 3.8](https://tools.ietf.org/html/rfc6143) - VNC Protocol Specification
+- [noVNC Documentation](https://github.com/novnc/noVNC) - HTML5 VNC Client
+- [FastAPI WebSocket](https://fastapi.tiangolo.com/advanced/websockets/) - WebSocket Implementation
+- [GNS3 Documentation](https://docs.gns3.com/) - General GNS3 Documentation
+
+## Version History
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 1.1 | 2026-04-19 | Review against code: fix buffer size, auth details, add port range config, remove unverified content |
+| 1.0 | 2026-03-17 | Initial VNC WebSocket documentation |

docs/features/web-wireshark-business-process.md

@@ -0,0 +1,620 @@
+<!--
+SPDX-License-Identifier: CC-BY-SA-4.0
+See LICENSE file for licensing information.
+-->
+
+> This documentation is organized by AI with reference to actual code. AI can make mistakes — please verify against the source code when in doubt.
+
+
+# Web Wireshark Feature - Business Process Documentation
+
+## Overview
+
+The **Web Wireshark** feature enables users to run Wireshark packet capture analysis directly in a web browser without requiring a desktop environment or VNC connection. This is achieved through an **xpra** (persistent remote applications) HTML5 client running inside a Docker container.
+
+## Feature Summary
+
+- **Core Capability**: Web-based packet capture visualization using Wireshark
+- **Technology Stack**: Docker container + xpra + HTML5 WebSocket proxy
+- **Target Users**: Network engineers and students who need to analyze network traffic in GNS3 topologies
+- **Key Benefit**: Zero-install, browser-based packet capture analysis
+
+---
+
+## Installation
+
+Before using Web Wireshark, install the GNS3 server and set up the Docker image:
+
+```bash
+# Development install
+pip install -e . && gns3server-web-wireshark-setup
+
+# Production install
+pip install gns3-server && gns3server-web-wireshark-setup
+```
+
+This command will:
+1. Install the gns3-server package
+2. Pull the `gns3/web-wireshark:latest` image from Docker Hub
+3. If pull fails, build the image locally using the included Dockerfile
+
+The `wireshark` command shows the raw output from `docker pull` or `docker build`, allowing you to see the full progress.
+
+---
+
+## Architecture Overview
+
+```mermaid
+graph TD
+    subgraph GNS3Server["GNS3 Server"]
+        WebUI["Web UI<br/>(Browser)"]
+        Controller["GNS3 Controller"]
+        LinkCtrl["Link Controller<br/>(start_capture / stop_capture)"]
+        Manager["WebWiresharkManager<br/>(called directly, not via CLI)"]
+        DockerClient["DockerHTTPClient<br/>(HTTP via Unix Socket)"]
+    end
+
+    subgraph DockerDaemon["Docker Daemon"]
+        Container["gns3-wireshark-{project_id}"]
+        Xvfb["Xvfb (virtual framebuffer)"]
+        Xpra["xpra server"]
+        Wireshark["Wireshark"]
+    end
+
+    ClientBrowser["Client Browser<br/>(HTML5 Client)"]
+
+    ClientBrowser -->|REST API| WebUI
+    WebUI -->|capture/start| Controller
+    Controller --> LinkCtrl
+    LinkCtrl -->|start/stop/restart session| Manager
+    Manager -->|Docker API<br/>/var/run/docker.sock| DockerClient
+    DockerClient -->|container lifecycle| Container
+    Container --- Xvfb
+    Container --- Xpra
+    Container --- Wireshark
+    ClientBrowser -.->|WebSocket proxy| Xpra
+    Xpra -.->|xpra HTML5| ClientBrowser
+
+    style GNS3Server fill:#e8f4fd,stroke:#2196f3
+    style DockerDaemon fill:#fff3e0,stroke:#ff9800
+    style ClientBrowser fill:#e8f5e9,stroke:#4caf50
+```
+
+---
+
+## Component Description
+
+### 1. Web UI (Client Browser)
+- User interface for starting/stopping packet capture
+- Receives WebSocket URL for connecting to xpra HTML5 client
+- No plugins required - pure HTML5/JavaScript
+
+### 2. GNS3 Controller
+- Orchestrates the capture workflow
+- Validates user permissions (RBAC)
+- Manages link capture state
+
+### 3. manage_wireshark.py (Management CLI)
+- Command-line interface for container and session management
+- **For manual debugging and testing only** — the server calls `WebWiresharkManager` directly at runtime
+- Handles Docker container lifecycle
+- Manages xpra sessions per link
+
+### 4. WebWiresharkManager
+- Core business logic for Web Wireshark
+- Handles container creation, session startup/shutdown
+- Deterministic port allocation based on link_id
+
+### 5. DockerHTTPClient
+- Async HTTP client for Docker API
+- Communicates via Unix socket (/var/run/docker.sock)
+- Manages container lifecycle
+
+### 6. Docker Container (gns3-wireshark-{project_id})
+- Runs xpra server with HTML5 support
+- Contains Xvfb (virtual framebuffer) for headless Wireshark
+- Streams display to browser via WebSocket
+
+---
+
+## Business Processes
+
+### Process 1: Start Packet Capture with Web Wireshark
+
+```mermaid
+sequenceDiagram
+    actor User
+    participant WebUI as Web UI
+    participant Controller as Controller
+    participant LinkCtrl as Link Controller
+    participant Manager as WebWiresharkManager
+
+    User->>WebUI: 1. Start Capture
+    WebUI->>Controller: 2. POST /capture/start
+    Controller->>LinkCtrl: 3. _start_web_wireshark(jwt_token)
+    LinkCtrl->>Manager: 4. start_wireshark_session()
+    Note right of Manager: 5. Ensure network exists
+    Note right of Manager: 6. Get/create container
+    Note right of Manager: 7. Start xpra session<br/>(display + port)
+    Note right of Manager: 8. Start Wireshark<br/>(curl | wireshark -i - -k)
+    Manager-->>LinkCtrl: ws_url
+    LinkCtrl-->>Controller: ws_url
+    Controller-->>WebUI: 10. {capturing: true, ws_url: "ws://..."}
+    WebUI-->>User: 9. ws_url
+    Note over User,Manager: 11-12. Browser connects via WebSocket<br/>Server proxies to container xpra
+```
+
+**API Endpoint**: `POST /v3/projects/{project_id}/links/{link_id}/capture/start`
+
+**Request Body**:
+```json
+{
+  "wireshark": true,
+  "data_link_type": "DLT_EN10MB",
+  "capture_file_name": "capture.pcap"
+}
+```
+
+**Response**:
+```json
+{
+  "id": "link-uuid",
+  "capturing": true,
+  "ws_url": "ws://192.168.1.100:14500"
+}
+```
+
+### Process 2: Container Lifecycle (Per Project)
+
+```mermaid
+flowchart TD
+    A["Project Open"] --> B["First Link Capture"]
+    B --> C["Container Created<br/>(one per project)"]
+    C --> D["Container Running"]
+
+    subgraph SessionArchitecture["Container Session Architecture"]
+        direction TB
+        D --> E["gns3-wireshark-{project_id}"]
+
+        subgraph Link1Session["Link 1 Session"]
+            L1Xpra["xpra :14503"]
+            L1Xvfb["Xvfb :14503<br/>(1920x1080x24)"]
+            L1WS["Wireshark<br/>(curl | wireshark -i -)"]
+            L1Bind["bind-ws=0.0.0.0:14503"]
+            L1Xpra --- L1Xvfb
+            L1Xpra --- L1WS
+            L1Xpra --- L1Bind
+        end
+
+        subgraph Link2Session["Link 2 Session"]
+            L2Xpra["xpra :11024"]
+            L2Xvfb["Xvfb :11024<br/>(1920x1080x24)"]
+            L2WS["Wireshark<br/>(curl | wireshark -i -)"]
+            L2Bind["bind-ws=0.0.0.0:11024"]
+            L2Xpra --- L2Xvfb
+            L2Xpra --- L2WS
+            L2Xpra --- L2Bind
+        end
+
+        E --> Link1Session
+        E --> Link2Session
+
+        Note1["display = port = 10000 + hash(link_id) % 10000<br/>Each xpra creates its own Xvfb (NOT shared)"]
+    end
+
+    D --> F["Project Close"]
+    F --> G["Stop Container<br/>(all sessions terminate)"]
+    G --> H["Container Stopped<br/>(preserved for reuse)"]
+    H -->|Project Reopened| D
+
+    I["Project Delete"] --> J["Delete Container"]
+    J --> K["Container Removed"]
+
+    style SessionArchitecture fill:#fff8e1,stroke:#ffa000
+    style Link1Session fill:#e3f2fd,stroke:#1976d2
+    style Link2Session fill:#e8f5e9,stroke:#388e3c
+```
+
+### Process 3: WebSocket Connection Flow
+
+```mermaid
+sequenceDiagram
+    participant Browser as Client Browser
+    participant Server as GNS3 Server (API Route)
+    participant Container as Docker Container (xpra)
+
+    Browser->>Server: 1. WSS Connect (ws://.../web-wireshark?token=jwt)
+    Note right of Server: 2. Validate JWT<br/>(RBAC: Link.Capture)
+    Note right of Server: 3. Get container IP<br/>from Docker API
+    Server-->>Browser: 4. Accept connection
+    Note right of Server: 5. Start WebSocket proxy
+    Server->>Container: 6. Connect to xpra<br/>ws://container:port
+    Container-->>Server: 7. xpra validates subprotocol
+    Note over Browser,Container: 8-9. Bidirectional WebSocket proxy<br/>Browser ⟺ Server ⟺ Container
+    Note left of Browser: 10. HTML5 client renders<br/>Wireshark window
+```
+
+**WebSocket Endpoint**: `ws://host/v3/projects/{project_id}/links/{link_id}/capture/web-wireshark?token=<jwt_token>`
+
+### Process 4: Capture Data Flow
+
+```mermaid
+flowchart LR
+    subgraph GNS3Node["GNS3 Node"]
+        Router["Router / Switch"]
+    end
+
+    subgraph ComputeNode["Compute Node"]
+        Capture["Link Capture Buffer"]
+    end
+
+    Router -->|"TAP (raw packets)"| Capture
+
+    subgraph GNS3Server["GNS3 Server"]
+        APIRoute["GET /capture/stream<br/>Proxies pcap stream"]
+    end
+
+    Capture -->|"pcap stream"| APIRoute
+
+    subgraph DockerContainer["Docker Container"]
+        direction TB
+        Curl["curl -N -H 'Authorization: Bearer {jwt}'<br/>'{server}/capture/stream'"]
+        Wireshark["wireshark -i - -k"]
+        Xvfb["Xvfb :display<br/>(1920x1080x24)"]
+        Xpra["xpra :display<br/>ws://0.0.0.0:{port}"]
+
+        Curl -->|"stdin pipe"| Wireshark
+        Wireshark -->|"renders to"| Xvfb
+        Xvfb -->|"X11 display"| Xpra
+    end
+
+    APIRoute -.->|"pcap stream<br/>(curl fetches from container)"| Curl
+
+    subgraph Browser["Client Browser"]
+        HTML5Client["HTML5/xpra Client"]
+        WSUI["Wireshark Web Interface"]
+        HTML5Client --> WSUI
+    end
+
+    Xpra <-->|"WebSocket"| HTML5Client
+
+    style GNS3Node fill:#f3e5f5,stroke:#7b1fa2
+    style ComputeNode fill:#e8eaf6,stroke:#283593
+    style GNS3Server fill:#e8f4fd,stroke:#2196f3
+    style DockerContainer fill:#fff3e0,stroke:#ff9800
+    style Browser fill:#e8f5e9,stroke:#4caf50
+```
+
+---
+
+## Port Allocation Strategy
+
+### Deterministic Port Mapping
+
+```mermaid
+flowchart LR
+    LinkID["link_id (UUID)"] --> Hash["MD5 Hash"] --> Modulo["hash % 10000"]
+    Modulo --> Offset["+ 10000"]
+    Offset --> Result["display = port<br/>Range: 10000 - 19999"]
+
+    style LinkID fill:#e3f2fd,stroke:#1976d2
+    style Result fill:#e8f5e9,stroke:#388e3c
+```
+
+| link_id | port/display |
+|---------|-------------|
+| `f233f27f-7432-49c3-9aa2-50e326a10eec` | 14503 |
+| `a1b2c3d4-1234-5678-90ab-cdef12345678` | 11024 |
+| `12345678-90ab-cdef-1234-567890abcdef` | 17892 |
+
+**Benefits**:
+- Same link always gets same port (deterministic)
+- Display number = port number (same hash)
+- No port conflicts between sessions
+- Easy to predict and debug
+
+---
+
+## Network Architecture
+
+```mermaid
+graph TD
+    subgraph HostMachine["Host Machine"]
+        subgraph GNS3ServerHost["GNS3 Server<br/>192.168.1.100:3080"]
+            WSProxy["WebSocket Proxy"]
+        end
+
+        subgraph DockerNetwork["Docker Bridge: gns3-wireshark<br/>Subnet: 172.31.0.0/22"]
+            Gateway["Bridge Gateway<br/>172.31.0.1"]
+            Container["gns3-wireshark-{project_id}<br/>172.31.0.x"]
+            Gateway --- Container
+        end
+    end
+
+    Client["Client Browser"] -->|"ws://192.168.1.100:3080<br/>/capture/web-wireshark"| WSProxy
+    WSProxy -->|"via gateway 172.31.0.1<br/>ws://172.31.0.x:{port}"| Container
+
+    style HostMachine fill:#fafafa,stroke:#9e9e9e
+    style DockerNetwork fill:#e3f2fd,stroke:#1976d2
+    style GNS3ServerHost fill:#e8f5e9,stroke:#388e3c
+```
+
+---
+
+## Session Management Commands
+
+> **Note**: These commands are for manual debugging and testing only. The GNS3 server calls `WebWiresharkManager` directly at runtime.
+
+### start
+
+Starts Web Wireshark session for a specific link.
+
+| Argument | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `--project-id` | Yes | - | Project UUID |
+| `--link-id` | Yes | - | Link UUID |
+| `--jwt-token` | Yes | - | JWT authentication token |
+| `--capture-url` | No | auto-detected | PCAP stream URL |
+| `--image` | No | `gns3/web-wireshark:latest` | Docker image |
+| `--memory` | No | `2g` | Memory limit |
+| `--cpus` | No | `1.0` | CPU cores |
+| `--pids-limit` | No | `1000` | Process limit |
+
+```bash
+python manage_wireshark.py start \
+  --project-id "5af0fe00-..." \
+  --link-id "f233f27f-..." \
+  --jwt-token "eyJhbG..."
+```
+
+### Other Commands
+
+| Command | Description | Key Arguments |
+|---------|-------------|---------------|
+| `stop` | Stop session for a specific link | `--project-id`, `--link-id` |
+| `restart` | Restart session (reopens Wireshark window) | `--project-id`, `--link-id`, `--jwt-token` |
+| `stop-all` | Stop all sessions for a project | `--project-id` |
+| `delete` | Delete container (alias for delete-container) | `--project-id` |
+| `stop-container` | Stop container without deleting | `--project-id` |
+| `delete-container` | Delete the container | `--project-id` |
+
+---
+
+## Project Close/Delete Workflow
+
+```mermaid
+flowchart TD
+    A["Project Close"] --> B["_stop_web_wireshark_container()"]
+    B --> C["WebWiresharkManager.stop_container(project_id)"]
+    C --> D["docker stop<br/>(all xpra/Xvfb/Wireshark terminate)"]
+    D --> E["Container Stopped<br/>(preserved for reuse)"]
+
+    E -->|Project Reopened| F["First Capture Start"]
+    F --> G["docker start<br/>(container already exists, fast)"]
+    G --> H["New xpra sessions created"]
+
+    I["Project Delete"] --> J["_cleanup_web_wireshark_container()"]
+    J --> K["WebWiresharkManager.delete_container(project_id)"]
+    K --> L["docker rm<br/>(container removed)"]
+
+    style A fill:#e3f2fd,stroke:#1976d2
+    style I fill:#ffebee,stroke:#c62828
+    style E fill:#fff8e1,stroke:#ffa000
+    style L fill:#ffebee,stroke:#c62828
+```
+
+---
+
+## API Endpoints Summary
+
+| Method | Endpoint | Description | Privilege |
+|--------|----------|-------------|-----------|
+| POST | `/v3/projects/{id}/links/{id}/capture/start` | Start capture with Web Wireshark | Link.Capture |
+| POST | `/v3/projects/{id}/links/{id}/capture/stop` | Stop capture | Link.Capture |
+| POST | `/v3/projects/{id}/links/{id}/capture/wireshark/restart` | Restart Wireshark window | Link.Capture |
+| GET | `/v3/projects/{id}/links/{id}/capture/stream` | Stream PCAP data | Link.Capture |
+| GET | `/v3/projects/{id}/links/{id}/capture/file` | Download PCAP file | Link.Capture |
+| WS | `/v3/projects/{id}/links/{id}/capture/web-wireshark` | WebSocket proxy for xpra | Link.Capture |
+
+---
+
+## Security Considerations
+
+1. **RBAC Authentication**: All endpoints require `Link.Capture` privilege
+2. **JWT Token Validation**: WebSocket connections validate JWT token
+3. **WebSocket Subprotocol Negotiation**: Proper xpra subprotocol handling
+4. **Container Isolation**: Each project gets its own container with isolated resources
+5. **Network Segmentation**: Container runs on isolated Docker network (not host network)
+
+---
+
+## Performance Characteristics
+
+### Startup & Shutdown Performance
+
+| Step | Before Optimization | After Optimization | Improvement |
+|------|---------------------|-------------------|-------------|
+| **Health Check** | ~1.0s | ~0s | Docker native status |
+| **Gateway Detection** | 0.85s | ~0.001s | Docker API vs exec |
+| **Process Cleanup** | ~850ms | ~40ms | Host perspective recursive tree walk |
+| **Xpra Startup** | 6.4s | ~3s | HTML5 client disabled |
+| **Wireshark Launch** | ~1s | ~1s | No change |
+| **Total Startup** | **~15s** | **~5-6s** | **67% faster** |
+
+| Step | Before Optimization | After Optimization | Improvement |
+|------|---------------------|-------------------|-------------|
+| **Process Termination** | ~8s | ~20-40ms | Recursive tree walk, no orphans |
+| **File Cleanup** | ~850ms | ~850ms | Docker exec (safety) |
+| **Total Shutdown** | **~9s** | **~2s** | **78% faster** |
+
+#### Startup Breakdown: First vs Subsequent
+
+| Phase | First Startup (Container stopped) | Subsequent Startup (Container running) |
+|-------|-----------------------------------|----------------------------------------|
+| Container startup | ~1-2s | ~0s (already running) |
+| Container health check | ~1s (unhealthy→healthy) | ~0s (already healthy) |
+| Gateway detection | ~0.001s | ~0.001s |
+| Process cleanup | ~40ms | ~40ms |
+| Xpra startup | ~3s | ~3s |
+| Wireshark launch | ~1s | ~1s |
+| **Total** | **~6s** | **~5s** |
+
+#### Measured Performance Data
+
+**Startup (from production logs):**
+```
+13:46:53 → 13:46:59 = 6s (first startup with container start)
+13:47:38 → 13:47:43 = 5s (subsequent startup, container running)
+```
+
+**Shutdown (from production logs):**
+```
+13:48:15 → 13:48:17 = 2s (complete cleanup, no orphan processes)
+13:48:50 → 13:48:52 = 2s (complete cleanup, no orphan processes)
+```
+
+#### Key Optimizations
+
+- **Complete Process Cleanup**: Recursive process tree traversal eliminates orphaned processes (Xvfb, pulseaudio, ibus-daemon)
+- **Fast Gateway Detection**: Docker API query instead of container exec
+- **Smart Health Check**: Trust Docker built-in status, no manual ping
+- **Xpra Optimization**: Disabled unnecessary HTML5 client (`--html=off`)
+- **Reduced Docker Exec Calls**: Combined X lock and xpra socket cleanup into single exec call
+
+### Docker Exec Performance Limitations
+
+**Important**: Docker daemon has internal queuing for concurrent exec requests to the same container.
+
+#### Test Results (Same Container)
+
+| Test Scenario | Execution Time | Avg Per Exec |
+|--------------|----------------|--------------|
+| Single docker exec | 0.854s | 0.854s |
+| Serial 7 docker exec | 7.225s | 1.032s |
+| Parallel 7 docker exec | 10.253s | 1.465s |
+
+**Key Finding**: Parallel execution is **42% slower** than serial execution.
+
+```
+Serial:   7.225s  (7 requests processed sequentially)
+Parallel: 10.253s (Docker daemon still processes sequentially + context switch overhead)
+```
+
+#### Impact on Web Wireshark
+
+When stopping multiple capture sessions quickly:
+- Each stop requires 1 docker exec (cleanup files)
+- Docker daemon processes exec requests sequentially
+- 7 sessions × ~1s each = ~7-10 seconds total
+- User requests appear to "queue" even though they're concurrent
+
+#### Optimization Strategy
+
+Since Docker exec cannot be parallelized effectively:
+1. **Minimize exec calls** - Already implemented: 2 calls → 1 call
+2. **Accept serial processing** - No benefit to parallel execution
+3. **Focus on fast exec content** - Use simple `rm -f` commands
+
+#### Future Optimization Options
+
+- Use Docker API instead of exec (requires container filesystem access)
+- Delay cleanup to next startup (increases startup complexity)
+- Batch multiple stops into single operation (requires API changes)
+
+### Resource Usage (Per Wireshark Instance)
+| Resource | Typical Usage |
+|----------|---------------|
+| Memory | 150-250 MB |
+| CPU | 0.5-2% (idle to active) |
+| Threads | ~30 threads |
+| Disk I/O | Minimal |
+
+### Container Configuration
+
+Configured via `WebWiresharkSettings` in `gns3server/schemas/config.py`:
+
+| Parameter | Default | Recommended | Description |
+|-----------|---------|-------------|-------------|
+| enabled | true | - | Enable/disable Web Wireshark feature |
+| image | gns3/web-wireshark:latest | - | Docker image name |
+| network_subnet | 172.31.0.0/22 | - | Docker bridge network subnet |
+| Memory | 2GB | 2-4GB | Container memory limit |
+| CPUs | 1.0 | 1.0-2.0 | Container CPU limit |
+| PIDs Limit | 1000 | 1000 | Container process limit |
+
+### Scaling Guidelines
+| Instances | Memory | Use Case |
+|-----------|--------|----------|
+| 1-3 | 450-750 MB | Light projects |
+| 4-6 | 600-1.5 GB | Medium projects |
+| 7-10 | 1-2.5 GB | Large projects |
+| 10+ | >2.5 GB | Increase memory |
+
+---
+
+## Docker API Compatibility
+
+### Version Negotiation Mechanism
+
+The Web Wireshark feature implements automatic Docker API version negotiation to ensure compatibility across different Docker versions:
+
+1. **Primary**: Try API version 1.44 first
+   - Supports Docker 29.3+ (API 1.54+), which requires minimum API 1.44
+
+2. **Fallback**: If server rejects 1.44 with 400 error, downgrade to API 1.40
+   - Supports Docker 20.10 (API 1.41)
+
+### Tested Configurations
+
+| Docker Version | API Version | API 1.40 | API 1.44 | Solution |
+|----------------|-------------|----------|----------|----------|
+| 20.10 | 1.41 | ✓ | ✗ | Fallback to 1.40 |
+| 29.3+ | 1.54+ | ✗ | ✓ | Use 1.44 |
+
+### Container IP Retrieval
+
+The `get_container_ip()` method implements a dual-strategy approach for retrieving container IP addresses:
+
+1. **Primary Method**: Query Docker Container API
+   - Uses `docker inspect` via HTTP API
+   - Safe access to `NetworkSettings.Networks` field using `.get()`
+   - Handles missing fields gracefully (fixes KeyError bug)
+
+2. **Fallback Method**: Execute `hostname -I` command inside container
+   - Works when Docker API response lacks network information
+   - Compatible with containers without `ip` command
+   - Returns first IP address from `hostname -I` output
+
+This dual approach ensures compatibility across different Docker API versions that may have varying response formats.
+
+---
+
+## Known Limitations
+
+1. **JWT Token Visibility**: Token passed via command-line arguments (visible in `/proc/<pid>/cmdline`)
+2. **Single Container**: All Wireshark instances run in a single container per project
+3. **Docker Dependency**: Requires Docker daemon running on the server
+4. **Browser Support**: Requires modern browser with WebSocket support
+5. **Port Range**: Limited to 10,000 unique ports (10000-19999)
+
+---
+
+## File Structure
+
+```
+gns3server/
+├── controller/
+│   ├── link.py                    # Link capture lifecycle
+│   └── project.py                 # Project cleanup hooks
+├── api/routes/controller/
+│   └── links.py                   # REST/WebSocket API endpoints
+└── agent/web_wireshark/
+    ├── setup_wireshark_image.py   # Docker image setup tool
+    ├── manage_wireshark.py        # CLI management tool (manual/debug use only)
+    ├── manager.py                 # Session management logic (called by server)
+    ├── docker_client.py           # Docker API client
+    ├── stats.py                   # Container statistics collection
+    ├── docker/
+    │   └── Dockerfile            # Container image definition
+    └── WEB_WIRESHARK.md          # Technical documentation
+```

docs/gns3-copilot/implemented/ai-assistant-overview.en.md

@@ -0,0 +1,161 @@
+<!--
+SPDX-License-Identifier: CC-BY-SA-4.0
+See LICENSE file for licensing information.
+-->
+
+# GNS3-Copilot AI Assistant Overview
+
+## Overall Architecture
+
+```mermaid
+flowchart TB
+    subgraph "Client"
+        A["Web UI"] --> B["SSE Streaming"]
+    end
+
+    subgraph "FastAPI Route Layer"
+        B --> C["POST /chat/stream\nPOST /chat/inject"]
+        C --> D["Auth + LLM Config Loading\nSet ContextVars"]
+    end
+
+    subgraph "AgentService (Project-level)"
+        D --> E["LangGraph Agent\nStateGraph"]
+        E --> F["SQLite Checkpointer\ncopilot_checkpoints.db"]
+    end
+
+    subgraph "LangGraph Workflow"
+        E --> G["llm_call node\nmodel invocation"]
+        E --> H["tool_node\ntool execution"]
+        E --> I["title_generator_node\nauto title"]
+        E --> J["abort_handler_node\ninterrupt handling"]
+    end
+
+    subgraph "Three Copilot Modes"
+        G --> K["teaching_assistant\ndiagnostic read-only"]
+        G --> L["lab_automation_assistant\nfull control"]
+        G --> M["troubleshooting_injection\nfault injection"]
+    end
+
+    subgraph "LLM Config System"
+        D --> N["User configs\nGroup config inheritance\nAPI key encryption"]
+    end
+```
+
+## API Endpoints
+
+| Endpoint | Function |
+|---|---|
+| `POST /v3/projects/{pid}/chat/stream` | Streaming conversation (SSE), supports three copilot modes |
+| `POST /v3/projects/{pid}/chat/inject` | Fault injection entry, auto-switches to `troubleshooting_injection` mode |
+| `GET /v3/projects/{pid}/chat/sessions` | List sessions (supports filtering, pagination) |
+| `DELETE /v3/projects/{pid}/chat/sessions/{sid}` | Delete session |
+| `PATCH /v3/projects/{pid}/chat/sessions/{sid}` | Update session (rename, pin) |
+| `POST /v3/projects/{pid}/chat/sessions/{sid}/abort` | Abort an active session |
+
+## LangGraph Agent Workflow
+
+```mermaid
+sequenceDiagram
+    participant U as User
+    participant API as FastAPI
+    participant AS as AgentService
+    participant LLM as LLM Node
+    participant Tool as Tool Node
+    participant TGen as Title Node
+
+    U->>API: send message
+    API->>AS: stream_chat()
+    AS->>AS: set ContextVars<br/>(jwt_token, llm_config)
+
+    Note over AS,LLM: llm_call node
+    AS->>LLM: invoke pre-compiled model
+    LLM->>LLM: pre_model_hook<br/>inject topology + trim context
+    LLM-->>AS: AI reply (may include tool_calls)
+
+    opt has tool calls
+        AS->>Tool: execute tools
+        Tool-->>AS: tool results
+        AS->>LLM: continue LLM call
+    end
+
+    opt first turn and no title
+        AS->>TGen: auto-generate title
+        TGen-->>AS: session title
+    end
+
+    AS-->>API: SSE streaming response
+    API-->>U: stream output
+```
+
+## Three Copilot Modes
+
+### Mode Comparison
+
+| Mode | Tool Scope | Use Case |
+|---|---|---|
+| `teaching_assistant` (default) | Diagnostic read-only + packet analysis + node management | Teaching demos, troubleshooting guidance |
+| `lab_automation_assistant` | All tools (including config changes) | Lab automation, device configuration |
+| `troubleshooting_injection` | Fault injection tool set | Troubleshooting practice, fault simulation |
+
+### Tool Binding Details
+
+| Tool | teaching_assistant | lab_automation_assistant | troubleshooting_injection |
+|---|---|---|---|
+| `GNS3TemplateTool` get templates | ✓ | ✓ | |
+| `GNS3CreateNodeTool` create nodes | ✓ | ✓ | |
+| `GNS3LinkTool` create links | ✓ | ✓ | |
+| `GNS3StartNodeTool` start nodes | ✓ | ✓ | |
+| `GNS3UpdateNodeNameTool` rename | ✓ | ✓ | |
+| `GNS3StopNodeTool` stop nodes | | ✓ | |
+| `GNS3SuspendNodeTool` suspend nodes | | ✓ | |
+| `ExecuteMultipleDeviceCommands` read-only commands | ✓ | ✓ | ✓ |
+| `ExecuteMultipleDeviceConfigCommands` config commands | | ✓ | ✓ |
+| `VPCSCommands` VPCS commands | | ✓ | |
+| `PacketAnalysisTool` live packet analysis | ✓ | ✓ | |
+| `PacketAnalysisSkillsTool` protocol knowledge | ✓ | ✓ | |
+| `DeviceSkillsTool` device skills | ✓ | ✓ | |
+| `GNS3PacketFilterTool` link filters | | | ✓ |
+| `InjectionSkillsTool` fault injection skills | | | ✓ |
+| `GNS3TopologyTool` topology info | | | ✓ |
+
+The mode is selected in the `llm_call` node via `copilot_mode`, which picks the corresponding tool list and binds it to the LLM model instance through `create_base_model_with_tools(mode_tools, llm_config)`.
+
+## Context Window Management
+
+```mermaid
+flowchart LR
+    A["LLM call triggered"] --> B["pre_model_hook"]
+    B --> C["Inject topology\ninto System Prompt"]
+    B --> D["Estimate tool definition\ntoken cost"]
+    B --> E["trim_messages\nby strategy"]
+    E --> F["conservative 60%\nbalanced 75%\naggressive 85%"]
+    F --> G["Invoke LLM"]
+```
+
+- Accurate token counting via tiktoken (`cl100k_base`)
+- Three trimming strategies: conservative / balanced / aggressive
+- Auto-injects `{{topology_info}}` into System Prompt
+
+## Session Management
+
+- Per-project independent SQLite database (`gns3-copilot/copilot_checkpoints.db`)
+- Supports pin, rename, delete, history query
+- Auto-records token usage, message count, LLM call count
+
+## LLM Config System
+
+| Feature | Description |
+|---|---|
+| User-level configs | Each user can independently configure provider / model / api_key |
+| Group inheritance | Users auto-inherit group config when no personal config is set |
+| API key encryption | Auto-encrypted at database storage |
+| Optimistic locking | `version` field prevents concurrent modification conflicts |
+
+## Key Design Points
+
+1. **Project-level Isolation** — Each GNS3 project has its own Agent instance and SQLite storage
+2. **ContextVars Safe Passing** — JWT token, API key exist only in memory, auto-cleared when request ends
+3. **LangGraph StateGraph** — Custom nodes + conditional edges, supports ReAct loop and recursion limits
+4. **SSE Streaming** — Real-time push of content / tool_call / tool_start / tool_end / error / done events
+5. **Hot Reload** — System Prompt, Skills, Protocols all support runtime reload
+6. **Mode-based Tool Sets** — Three copilot modes bind different tools, safely isolated by scenario

docs/gns3-copilot/implemented/command-security.md

@@ -0,0 +1,224 @@
+<!--
+SPDX-License-Identifier: CC-BY-SA-4.0
+See LICENSE file for licensing information.
+-->
+
+> This documentation is organized by AI with reference to actual code. AI can make mistakes — please verify against the source code when in doubt.
+
+
+# Command Security Configuration
+
+## Overview
+
+GNS3-Copilot includes multiple security layers to prevent execution of commands that may cause issues in the lab environment:
+
+- **Command Filtering**: Prevents commands that may timeout or lock up the console
+- **Configuration Safety**: Restricts dangerous configuration changes (AAA, passwords, etc.)
+- **Multi-line Command Handling**: Properly processes commands with embedded newlines (banner, etc.)
+
+## Architecture
+
+```mermaid
+graph TD
+    A[Tool Request] --> B{Command Filter}
+    B -->|allowed| C[Nornir/Netmiko Execution]
+    B -->|blocked| D[blocked_commands_info]
+    C --> E[Process Results]
+    D --> E
+    E --> F[Return Result]
+
+    subgraph Command Filter
+        B1[Load forbidden_commands.txt]
+        B2[Prefix match per command]
+        B1 --> B2
+    end
+
+    subgraph Security Layers
+        S1[Layer 1: Command Filter<br/>prefix-based blocking]
+        S2[Layer 2: AI Prompt Rules<br/>AAA/password guidance only]
+        S3[Layer 3: Multi-line Expansion<br/>banner/ACL handling]
+        S1 --> S2 --> S3
+    end
+```
+
+## Business Process
+
+### Command Filtering Flow
+
+```mermaid
+flowchart TD
+    Start([Tool receives commands]) --> Load[Load forbidden patterns<br/>from config file]
+    Load --> Loop{For each command}
+    Loop -->|next command| Prefix{Command starts with<br/>forbidden pattern?}
+    Prefix -->|yes| Block[Add to blocked_commands_info]
+    Prefix -->|no| Allow[Add to allowed list]
+    Block --> Loop
+    Allow --> Loop
+    Loop -->|all checked| Empty{Allowed list empty?}
+    Empty -->|yes| Return1[Return partial_success<br/>with blocked info only]
+    Empty -->|no| Exec[Execute allowed commands<br/>via Nornir/Netmiko]
+    Exec --> HasBlocked{Has blocked commands?}
+    HasBlocked -->|yes| Return2[Return partial_success<br/>with output + blocked info]
+    HasBlocked -->|no| Return3[Return success<br/>with output]
+```
+
+### Multi-line Command Expansion Flow
+
+```mermaid
+flowchart TD
+    A[config_tools receives commands] --> B{Command contains \n?}
+    B -->|yes| C[Split by newline]
+    C --> D[Filter empty lines]
+    D --> E[Add expanded lines to command list]
+    B -->|no| F[Keep command as-is]
+    E --> G[Execute via netmiko_send_config]
+    F --> G
+```
+
+## Tools Using Command Security
+
+| Tool | File | Filter | Multi-line Expansion | Result Fields |
+|------|------|--------|---------------------|---------------|
+| `ExecuteMultipleDeviceCommands` | `display_tools_nornir.py` | Yes | No | `diagnostic_commands` |
+| `ExecuteMultipleDeviceConfigCommands` | `config_tools_nornir.py` | Yes | Yes | `config_commands` |
+
+## Command Filtering System
+
+### Forbidden Commands Configuration
+
+The forbidden commands list is loaded from the external [GNS3-Skills](https://github.com/gns3/gns3-skills) repository at `config/forbidden_commands.txt`.
+
+**Format:**
+- One command pattern per line
+- **Prefix matching** (case-insensitive) — matches the beginning of each command
+- Empty lines and lines starting with `#` are ignored
+
+**Default patterns (used when skills repository is unavailable):**
+
+| Pattern | Reason |
+|---------|--------|
+| `traceroute` | Can run 30+ seconds, exceeds tool timeout |
+| `tracepath` | Similar to traceroute, long execution time |
+| `tracert` | Windows traceroute, same timeout issues |
+| `ping -f` | Flood ping can overwhelm lab devices |
+| `debug` | Can produce overwhelming output and destabilize devices |
+| `test` | May affect device stability |
+
+### Result Format
+
+**Status values:**
+
+| Status | Condition |
+|--------|-----------|
+| `"success"` | All commands executed, none blocked |
+| `"partial_success"` | Some commands blocked (including all blocked + execution succeeded) |
+| `"failed"` | Execution failed (device not found, connection error, etc.) |
+
+**Example — partial success (display tool):**
+
+```json
+{
+    "device_name": "R-1",
+    "status": "partial_success",
+    "output": "...",
+    "diagnostic_commands": ["show version", "show ip int brief"],
+    "blocked_commands": ["traceroute 8.8.8.8"],
+    "blocked_info": {
+        "traceroute 8.8.8.8": "Command 'traceroute 8.8.8.8' is not allowed because it matches the forbidden pattern 'traceroute'. ..."
+    }
+}
+```
+
+> **Note:** `diagnostic_commands` is specific to display tools. Config tools use `config_commands` instead.
+
+## Module Structure
+
+**Command Filter:** `gns3server/agent/gns3_copilot/utils/command_filter.py`
+
+| Function | Purpose |
+|----------|---------|
+| `filter_forbidden_commands(commands)` | Returns `(allowed_commands, blocked_commands_info)` |
+| `is_command_forbidden(command)` | Check if a single command matches a forbidden pattern |
+| `get_forbidden_commands()` | Get current forbidden patterns list |
+| `reload_forbidden_commands()` | Directly load and cache commands from skills repository |
+
+**Integration points:**
+- `display_tools_nornir.py` — `_filter_forbidden_commands_from_device_configs()`
+- `config_tools_nornir.py` — `_filter_forbidden_commands_from_device_configs()` + `_expand_multiline_commands()`
+
+## Configuration Safety (AI Prompt Level)
+
+In addition to the command filter, the AI agent is instructed via system prompt (`lab_automation_assistant_prompt.py`) to handle sensitive configuration commands with caution:
+
+**Prompt-enforced rules:**
+- **FORBIDDEN (guidance only):** `enable secret`, `username`, `aaa new-model`, `service password-encryption`, `line vty` — AI provides configuration guidance instead of executing
+- **Caution required:** `reload`, `erase`, `format` — AI warns user before executing destructive operations
+
+> These are prompt-level rules, not code-level enforcement. Users can always execute commands directly via device console or SSH/Telnet.
+
+## Multi-line Command Handling
+
+Commands containing `\n` are automatically split before execution by `config_tools_nornir.py:_expand_multiline_commands()`.
+
+**Example:** `["banner motd #\nWelcome\n#"]` becomes `["banner motd #", "Welcome", "#"]`
+
+Applies to any command with embedded newlines: `banner`, multi-line ACLs, route-maps, etc.
+
+## Configuration
+
+### Customizing Forbidden Commands
+
+Edit `config/forbidden_commands.txt` in the [GNS3-Skills repository](https://github.com/gns3/gns3-skills) and push the changes, then call `POST /copilot/reload/skills` to apply them without restarting the server.
+
+## Implementation Verification
+
+### Test Results (Live GNS3 Environment)
+
+**Scenario:** IOU-L2-1 (Cisco IOS L3 switch), mixed allowed/forbidden commands.
+
+```json
+{
+  "device_name": "IOU-L2-1",
+  "status": "partial_success",
+  "diagnostic_commands": [
+    "show ip route", "show ip interface brief",
+    "ping 10.0.0.1", "ping 10.0.0.2", "ping 10.0.0.4"
+  ],
+  "blocked_commands": ["traceroute 10.0.0.2"],
+  "blocked_info": {
+    "traceroute 10.0.0.2": "Command 'traceroute 10.0.0.2' is not allowed because it matches the forbidden pattern 'traceroute'. ..."
+  }
+}
+```
+
+| Feature | Status | Notes |
+|---------|--------|-------|
+| Prefix match filtering | Verified | `traceroute` correctly matched and blocked |
+| Partial execution | Verified | Other commands executed successfully |
+| `partial_success` status | Verified | Set correctly when blocked + succeeded |
+| Multi-device support | Verified | Each device filtered independently |
+| Non-blocking behavior | Verified | No tool timeouts or console issues |
+
+## Future Enhancements
+
+- **Regex support** for more sophisticated pattern matching
+- **Per-project override files** for forbidden commands
+- **Web UI configuration** for managing forbidden commands
+- **Audit logging** for blocked command analysis
+- **Per-command timeouts** instead of blocking
+- **Interrupt mechanism** (Ctrl+C) for long-running commands
+
+## Troubleshooting
+
+| Problem | Solution |
+|---------|----------|
+| Command blocked unexpectedly | Check `blocked_commands` in result, identify matching pattern, edit `forbidden_commands.txt` |
+| "File not found, using defaults" | Verify `config/forbidden_commands.txt` exists and is readable |
+| Changes not taking effect | Call `POST /copilot/reload/skills` or restart server |
+
+## Related Documentation
+
+- [Skills Repository](skills-repository.md)
+- [Fault Injection](fault-injection.md)
+- [Chat API](chat-api.md)
+

docs/gns3-copilot/implemented/context-window-management.md

@@ -0,0 +1,203 @@
+<!--
+SPDX-License-Identifier: CC-BY-SA-4.0
+See LICENSE file for licensing information.
+-->
+
+> This documentation is organized by AI with reference to actual code. AI can make mistakes — please verify against the source code when in doubt.
+
+
+# LLM Context Window Management
+
+## Overview
+
+GNS3 Copilot's context window management prevents LLM context overflow by trimming conversation history to fit within configured token limits. It uses tiktoken for accurate token counting, supports three context strategies (conservative/balanced/aggressive), and automatically injects GNS3 topology information into the system prompt before each LLM call.
+
+## Architecture
+
+```mermaid
+graph TD
+    subgraph "context_manager.py"
+        A[create_pre_model_hook] --> B[_inject_topology_into_system]
+        A --> C[estimate_tool_tokens]
+        A --> D[trim_messages via LangChain]
+        E[count_tokens via tiktoken]
+        E --> C
+        E --> F[_count_tokens_for_message]
+        F --> D
+    end
+
+    subgraph "gns3_copilot.py"
+        G[llm_call node] --> H[Get topology via GNS3TopologyTool]
+        H --> A
+        A --> I[model_with_tools.invoke]
+    end
+
+    style A fill:#4a9eff,color:#fff
+    style D fill:#ff6b6b,color:#fff
+    style E fill:#51cf66,color:#fff
+```
+
+## Key Components
+
+| Function | File | Purpose |
+|----------|------|---------|
+| `create_pre_model_hook()` | `context_manager.py` | Factory that creates the preprocessing hook |
+| `_inject_topology_into_system()` | `context_manager.py` | Injects topology into system prompt via `{{topology_info}}` placeholder |
+| `count_tokens()` | `context_manager.py` | Accurate token counting using tiktoken (`cl100k_base`) |
+| `estimate_tool_tokens()` | `context_manager.py` | Estimates token cost of tool definitions (JSON serialization) |
+| `_count_tokens_for_message()` | `context_manager.py` | Token counter adapter for LangChain's `trim_messages` |
+| `llm_call()` | `gns3_copilot.py` | StateGraph node that orchestrates the full LLM call pipeline |
+
+**Token Counting**: Uses tiktoken `cl100k_base` encoding (GPT-4 compatible, 95%+ accuracy for most modern LLMs).
+
+**tiktoken Cache**: Encoding files are cached locally at `<agent_package>/cache/tiktoken/` to avoid repeated downloads. This is configured before tiktoken import via `TIKTOKEN_CACHE_DIR` environment variable.
+
+**Required Dependency**: `tiktoken>=0.8.0` — if not installed, `ModuleNotFoundError` is raised at startup.
+
+## Trimming Process
+
+```mermaid
+flowchart TD
+    A[llm_call node invoked] --> B[Get topology via GNS3TopologyTool]
+    B --> C[Create pre_model_hook]
+    C --> D[Inject topology into system prompt]
+    D --> E{topology data available?}
+    E -->|Yes| F[Replace placeholder with topology content]
+    E -->|No| G[Replace placeholder with 'No topology information available']
+    F --> H[Estimate tool definition tokens]
+    G --> H
+    H --> I[Calculate trim_messages budget]
+    I --> J[trim_messages with strategy='last']
+    J --> K[Return prepared messages]
+    K --> L[model.invoke with prepared messages]
+```
+
+### Token Budget Calculation
+
+```mermaid
+flowchart LR
+    A["context_limit<br/>(e.g. 128K)"] -->|"× strategy_ratio"| B["Input Budget<br/>(e.g. 96K @ balanced)"]
+    B -->|"− tool_tokens"| C["trim_messages Budget<br/>(includes system message)"]
+    C --> D["trim_messages<br/>max_tokens parameter"]
+```
+
+**Key**: `max_tokens` passed to `trim_messages` **includes** the system message. System tokens are NOT subtracted separately — `trim_messages` handles system message preservation via `include_system=True`.
+
+### Budget Calculation Example
+
+| Step | Calculation | Result |
+|------|------------|--------|
+| Context limit | 128 (configured) | 128K tokens |
+| Strategy ratio | balanced = 0.75 | 128 × 1000 × 0.75 = 96,000 |
+| Tool definitions | estimated from JSON schema | ~1,725 tokens |
+| trim_messages budget | 96,000 − 1,725 | **94,275 tokens** (includes system) |
+
+### Trimming Priority
+
+| Priority | Content | Behavior |
+|----------|---------|----------|
+| 1 | System Message (system prompt + topology) | Always kept (`include_system=True`) |
+| 2 | Latest conversation messages | Kept from newest to oldest |
+| 3 | Older conversation history | Discarded first when exceeding budget |
+
+**Note**: System prompt and topology are merged into a single `SystemMessage` via the `{{topology_info}}` template variable and cannot be trimmed independently.
+
+### Edge Case Handling
+
+| Scenario | Behavior |
+|----------|----------|
+| System + tools > input budget | ERROR log with recommendations (reduce prompt/tools, use larger model, switch to conservative). `trim_messages` is still called — `include_system=True` ensures system message is kept, but no history messages will fit. |
+| Trim budget < system × 1.5 | WARNING log: minimal room for conversation history |
+| Invalid context_strategy | Falls back to `balanced` with WARNING log |
+| `trim_messages` throws exception | Returns untrimmed messages (graceful degradation) |
+| Missing `{{topology_info}}` placeholder | Returns original messages without injection, WARNING log |
+| Topology retrieval fails | Injects `"(No topology information available)"` placeholder |
+
+## Integration with GNS3 Copilot
+
+**File**: `gns3server/agent/gns3_copilot/agent/gns3_copilot.py`
+
+### Why Direct Call, Not Config-based?
+
+The agent uses a **custom StateGraph** (`StateGraph(MessagesState)`), not LangGraph's pre-built agent. LangGraph's `pre_model_hook` config parameter only works with pre-built agents like `create_react_agent`.
+
+| Agent Type | pre_model_hook Support |
+|------------|------------------------|
+| `create_react_agent` | Via `config={"configurable": {"pre_model_hook": ...}}` |
+| `chat_agent_executor` | Via `config={"configurable": {"pre_model_hook": ...}}` |
+| **Custom StateGraph** | **Not supported** — must call directly |
+
+### Execution Flow
+
+In the `llm_call` node of `gns3_copilot.py`:
+
+1. Get `llm_config` from request-scoped context variable
+2. Get `project_id` from `config["configurable"]`
+3. Retrieve topology via `GNS3TopologyTool._run(project_id)`
+4. Select tools based on `copilot_mode` (`teaching_assistant` vs `lab_automation_assistant`)
+5. Load system prompt and create `pre_model_hook`
+6. **Directly call** `pre_hook({"messages": messages, "topology_info": topology_info})` to prepare messages
+7. Invoke `model_with_tools.invoke(prepared_messages)`
+
+> **Note**: The actual `llm_call` function also includes defensive checks for missing config, empty messages, and topology retrieval errors — see source code for full details.
+
+## Strategy Implementation
+
+### Context Strategy Ratios
+
+Defined as `CONTEXT_STRATEGY_RATIOS` in `context_manager.py`, with default `DEFAULT_CONTEXT_STRATEGY = "balanced"`.
+
+| Strategy | Input Ratio | Output Reserved | Calculation |
+|----------|-------------|-----------------|-------------|
+| Conservative | 60% | 40% | `context_limit × 1000 × 0.60` |
+| Balanced | 75% | 25% | `context_limit × 1000 × 0.75` |
+| Aggressive | 85% | 15% | `context_limit × 1000 × 0.85` |
+
+## Log Output
+
+### Normal Case (topology injected)
+
+```
+INFO: Calling pre_hook to prepare 1 messages
+INFO: ✓ Topology injected: 7722 chars, nodes: ['netshoot-1', 'R1', 'R2', 'IOU-L3-1', 'IOU-L3-2']
+INFO: Context ready: 2 msgs, ~3815 tokens + 1725 tools = 5540 / 128K (4.3%), strategy=conservative
+INFO: Messages prepared: 1 → 2
+INFO: LLM call completed: tool_calls=0
+```
+
+### When Trimming Occurs
+
+```
+INFO: Calling pre_hook to prepare 50 messages
+INFO: ✓ Topology injected: 8500 chars, nodes: ['R1', 'R2', ...]
+INFO: Messages trimmed: 50 → 25 msgs. Total: ~82000 tokens + 1725 tools = 83725 / 128K (65.4%), strategy=balanced
+INFO: Messages prepared: 50 → 25
+```
+
+### When Topology is None
+
+```
+INFO: Calling pre_hook to prepare 1 messages
+WARNING: ✗ Topology data is None, injecting placeholder
+INFO: Context ready: 2 msgs, ~800 tokens + 1725 tools = 2525 / 128K (2.0%), strategy=balanced
+```
+
+## Error Handling
+
+| Error | Behavior | Resolution |
+|-------|----------|------------|
+| tiktoken not installed | `ModuleNotFoundError` at startup | `pip install tiktoken>=0.8.0` |
+| `context_limit` missing | `ValueError` raised | Add `context_limit` to LLM config |
+| Invalid `context_limit` | `ValueError` raised | Must be positive integer |
+| Invalid `context_strategy` | WARNING, fallback to `balanced` | Use `conservative`/`balanced`/`aggressive` |
+| `trim_messages` failure | ERROR log, returns untrimmed messages | Check message format compatibility |
+
+## Deprecated API
+
+`prepare_context_messages()` is deprecated. It remains in `context_manager.py` for backward compatibility but emits `DeprecationWarning`. Use `create_pre_model_hook()` instead.
+
+## Related Source Files
+
+- `gns3server/agent/gns3_copilot/agent/context_manager.py` — Context management core logic
+- `gns3server/agent/gns3_copilot/agent/gns3_copilot.py` — LLM call node (StateGraph)
+- `gns3server/agent/gns3_copilot/agent/model_factory.py` — Model creation and tool binding

docs/gns3-copilot/implemented/fault-injection-overview.en.md

@@ -0,0 +1,104 @@
+<!--
+SPDX-License-Identifier: CC-BY-SA-4.0
+See LICENSE file for licensing information.
+-->
+
+# GNS3-Copilot Fault Injection Overview
+
+## Core Flow
+
+```mermaid
+flowchart TB
+    subgraph "① API Trigger & Mode Switch"
+        A["POST /chat/inject\nUser requests fault injection"] --> B["Verify project is opened"]
+        B --> C["Set copilot_mode =\ntroubleshooting_injection"]
+        C --> D["Start Agent\nwith fault injection tool set"]
+    end
+
+    subgraph "② Topology Analysis & Fault Selection"
+        D --> E["GNS3TopologyTool\nget topology info"]
+        E --> F["ExecuteMultipleDeviceCommands\nget device configs"]
+        F --> G["InjectionSkillsTool\nquery available fault types"]
+        G --> H{"Injection Skills Repository\ngns3/gns3-skills"}
+        H --> I["Return matching fault definitions\nwith config injection commands"]
+    end
+
+    subgraph "③ Fault Injection"
+        I --> J["Choose injection method"]
+        J --> K["ExecuteMultipleDeviceConfigCommands\ninject config changes"]
+        J --> L["GNS3PacketFilterTool\ninject link-layer faults"]
+    end
+
+    subgraph "④ Result Confirmation"
+        K --> M["Verify fault is active"]
+        L --> M
+        M --> N["Document fault details\nincluding restore commands"]
+    end
+```
+
+## Tool Overview
+
+| Tool | Source File | Purpose | Available Modes |
+|---|---|---|---|
+| `InjectionSkillsTool` | `registry.py` (skills module) | Query protocol-level fault definitions (config change commands) | troubleshooting_injection |
+| `GNS3PacketFilterTool` | `gns3_packet_filter.py` | Link-layer fault injection (delay, loss, corruption, BPF) | troubleshooting_injection |
+| `ExecuteMultipleDeviceConfigCommands` | `config_tools_nornir.py` | Batch device config changes | troubleshooting_injection |
+| `ExecuteMultipleDeviceCommands` | `display_tools_nornir.py` | Read device configurations (read-only) | troubleshooting_injection |
+| `GNS3TopologyTool` | `gns3_client` | Get project topology information | troubleshooting_injection |
+
+## Fault Injection API
+
+| Endpoint | Function |
+|---|---|
+| `POST /v3/projects/{pid}/chat/inject` | Trigger fault injection, sets `troubleshooting_injection` mode then starts Agent |
+
+**Prerequisite**: Project must be in `opened` status, otherwise returns 403.
+
+## GNS3PacketFilterTool Link Filters
+
+| Filter Type | Function | Parameters |
+|---|---|---|
+| `delay` | Latency + jitter | `[latency(0-32767), jitter(0-32767)]` |
+| `packet_loss` | Packet loss percentage | `[chance(0-100)]` |
+| `corrupt` | Packet corruption percentage | `[chance(0-100)]` |
+| `frequency_drop` | Drop every Nth packet | `[frequency(-1~32767)]` |
+| `bpf` | Berkeley Packet Filter | expression text |
+
+## Agent Workflow (LangGraph)
+
+```mermaid
+sequenceDiagram
+    participant U as User
+    participant API as POST /chat/inject
+    participant LLM as LLM Node
+    participant Topo as GNS3TopologyTool
+    participant DC as ExecuteMultipleDeviceCommands
+    participant CC as ExecuteMultipleDeviceConfigCommands
+    participant Skill as InjectionSkillsTool
+    participant Filter as GNS3PacketFilterTool
+
+    U->>API: Inject an OSPF fault
+    API->>LLM: set mode=troubleshooting_injection
+    LLM->>Topo: get topology
+    Topo-->>LLM: topology info
+    LLM->>DC: read device configs
+    DC-->>LLM: running configs
+    LLM->>Skill: list context=["ospf"]
+    Skill-->>LLM: matching fault types
+    LLM->>Skill: get device_type=injection_ospf
+    Skill-->>LLM: fault definition + injection commands
+    LLM->>CC: execute config injection
+    CC-->>LLM: injection result
+    LLM->>Filter: set filters={delay:[200,50]}
+    Filter-->>LLM: link delay injected successfully
+    LLM-->>U: Fault injected, restore commands included
+```
+
+## Key Design Points
+
+1. **Dedicated API Endpoint** — `POST /chat/inject` is the dedicated entry point, automatically switching to `troubleshooting_injection` mode
+2. **LLM-driven Fault Selection** — The LLM analyzes the topology then queries matching faults via `InjectionSkillsTool`; no hardcoded fault scenarios
+3. **Dual-Layer Injection** — Device-level config changes + link-level network impairment, covering complete troubleshooting scenarios
+4. **Fully Reversible** — Every injection includes restore commands; link filters can be cleared with `action: clear`
+5. **Safety First** — BPF syntax is pre-validated via tshark; config commands are restricted by `command_filter`
+6. **Context Filtering** — `InjectionSkillsTool` requires a `context` parameter, returning only faults matching the topology protocols

docs/gns3-copilot/implemented/fault-injection.md

@@ -0,0 +1,159 @@
+<!--
+SPDX-License-Identifier: CC-BY-SA-4.0
+See LICENSE file for licensing information.
+-->
+
+> This documentation is organized by AI with reference to actual code. AI can make mistakes — please verify against the source code when in doubt.
+
+
+# Fault Injection Feature
+
+## Overview
+
+The fault injection feature enables GNS3 Copilot to automatically inject realistic network faults into GNS3 labs for troubleshooting training. The agent analyzes the topology, selects an appropriate fault based on the configured protocols, injects it, and documents the results.
+
+## Architecture
+
+```mermaid
+graph TD
+    subgraph "Agent Workflow"
+        TG[Topology Gathering]
+        CFG[Config Collection]
+        FA[Fault Analysis]
+        FI[Fault Injection]
+        FD[Fault Documentation]
+    end
+
+    subgraph "Skills Repository"
+        IS[INJECTION_SKILLS_REGISTRY<br/>39 categories, 368 issues]
+        SK[injection_skills Tool]
+    end
+
+    subgraph "Tools"
+        DC[execute_multiple_device_commands]
+        CC[execute_multiple_device_config_commands]
+        GK[GNS3TopologyTool]
+    end
+
+    TG -->|Get topology| GK
+    CFG -->|Get configs| DC
+    FA -->|Query filtered skills| IS
+    FA -->|Select fault| SK
+    FI -->|Inject config changes| CC
+    FD -->|Output report| FD
+```
+
+## Injection Skills Tool
+
+The `InjectionSkillsTool` (LangChain `BaseTool`) is the primary interface for querying available faults.
+
+### Listing Faults (with context filter)
+
+The LLM MUST pass topology context when listing faults:
+
+```json
+{"action": "list", "context": ["ospf", "bgp", "vlan"]}
+```
+
+This returns only faults matching the protocols found in the topology. The tool rejects calls without `context`:
+
+```json
+{
+  "error": "context parameter is required when action='list'",
+  "hint": "Analyze the topology and device configurations first...",
+  "available_categories": ["bgp", "interface", "mpls", "ospf", ...]
+}
+```
+
+### Getting Fault Details
+
+Token-efficient usage pattern:
+
+```json
+// Step 1: List issue names only (~300 tokens)
+{"device_type": "injection_ospf", "detail": "index"}
+
+// Step 2: Get single issue detail (~500 tokens)
+{"device_type": "injection_ospf", "issue": "ospf_hello_dead_mismatch"}
+```
+
+### Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `action` | No (`"get"`) | `"list"` to browse, `"get"` for details |
+| `context` | **Yes** for `action="list"` | Protocols found in topology: `["ospf", "bgp"]` |
+| `device_type` | Yes for `action="get"` | e.g. `"injection_ospf"` |
+| `detail` | No (`"full"`) | `"index"` (names), `"summary"` (+desc), `"full"` (all) |
+| `issue` | No | Single issue key for targeted detail |
+
+## Fault Injection Workflow
+
+```mermaid
+sequenceDiagram
+    participant LLM
+    participant InjectionSkillsTool
+    participant TopologyTool
+    participant DeviceCommands
+
+    LLM->>TopologyTool: Get topology info
+    TopologyTool-->>LLM: Topology + device types
+
+    LLM->>DeviceCommands: Get device configs
+    DeviceCommands-->>LLM: Running configurations
+
+    Note over LLM: Analyze which protocols are in use
+
+    LLM->>InjectionSkillsTool: {"action": "list", "context": ["ospf", "vlan"]}
+    InjectionSkillsTool-->>LLM: Matching fault categories
+
+    LLM->>InjectionSkillsTool: {"device_type": "injection_ospf", "detail": "index"}
+    InjectionSkillsTool-->>LLM: Issue names (token-efficient)
+
+    LLM->>InjectionSkillsTool: {"device_type": "injection_ospf", "issue": "ospf_hello_dead_mismatch"}
+    InjectionSkillsTool-->>LLM: Full fault detail + config commands
+
+    LLM->>DeviceCommands: Inject fault configuration
+    DeviceCommands-->>LLM: Execution result
+
+    Note over LLM: Document fault in response
+```
+
+## Injection Skills Repository
+
+Skills are organized by protocol/category in the external [GNS3-Skills](https://github.com/gns3/gns3-skills) repository:
+
+| Category | File | Example Issues |
+|----------|------|----------------|
+| OSPF | `injection/ospf_issues.yaml` | Hello/Dead mismatch, MTU mismatch, area mismatch |
+| BGP | `injection/bgp_issues.yaml` | AS-path prepend, next-hop unreachable, route filtering |
+| VLAN | `injection/vlan_issues.yaml` | Trunk allowed mismatch, native VLAN mismatch |
+| STP | `injection/stp_issues.yaml` | Root guard, loop guard, port priority |
+| MPLS | `injection/mpls_issues.yaml` | LDP session down, label binding failure |
+| ... | 34 more files | 368 issues total |
+
+## Recovery
+
+Each injected fault includes restore commands in the documentation. The LLM always provides commands to fully revert all changes.
+
+## API Endpoint
+
+### POST /copilot/projects/{project_id}/chat/inject
+
+Dedicated endpoint for fault injection. Internally sets `copilot_mode` to `troubleshooting_injection` and runs the agent.
+
+**Request:**
+```json
+{
+  "message": "Inject a network fault for troubleshooting practice",
+  "session_id": "optional-session-uuid"
+}
+```
+
+**Response:** Server-Sent Events (SSE) stream identical to the chat stream endpoint.
+
+## Related Documentation
+
+- [Skills Repository](skills-repository.md)
+- [Command Security](command-security.md)
+- [Chat API](chat-api.md)

docs/gns3-copilot/implemented/multi-vendor-device-support.md

@@ -0,0 +1,772 @@
+<!--
+SPDX-License-Identifier: CC-BY-SA-4.0
+See LICENSE file for licensing information.
+-->
+
+> This documentation is organized by AI with reference to actual code. AI can make mistakes — please verify against the source code when in doubt.
+
+
+# Multi-Vendor Network Device Support
+
+## Overview
+
+GNS3-Copilot supports network devices from multiple vendors through Netmiko and Nornir integration. The system includes a custom Netmiko driver for Huawei devices in GNS3 emulation environments and supports dynamic device type detection.
+
+## Supported Vendors
+
+| Vendor | Device Type | Protocol | Status |
+|--------|-------------|----------|--------|
+| **Cisco** | `cisco_ios_telnet` | Telnet | ✅ Tested |
+| **Huawei** | `gns3_huawei_telnet_ce` | Telnet | ✅ Tested (Custom Driver) |
+| **Ruijie (锐捷)** | `gns3_ruijie_telnet` | Telnet | ✅ Tested (Custom Driver) |
+| **VPCS** | `gns3_vpcs_telnet` | Telnet | ✅ Tested (Custom Driver, Simulator) |
+
+## Custom VPCS Driver (`VPCSTelnet`)
+
+### Problem Statement
+
+VPCS (Virtual PC Simulator) is a lightweight virtual PC simulator used in GNS3 lab environments. Unlike network devices (routers/switches), VPCS devices:
+
+1. **No authentication** - Direct console access without username/password
+2. **Simple command interface** - No configuration modes
+3. **Simple prompt pattern** - `PC1>`, `PC2>`, etc.
+
+### Solution: Lightweight Custom Driver
+
+```mermaid
+graph TD
+    A[BaseConnection<br/>Netmiko base class] --> B[VPCSTelnet<br/>Custom GNS3 driver]
+    B --> C[No authentication]
+    B --> D[Simple prompt: PC\d+]
+    B --> E[No config mode]
+    B --> F[ANSI stripping]
+```
+
+**Why Not Use Standard Telnet Driver?**
+- Standard drivers attempt authentication (times out)
+- No support for VPCS-specific prompt patterns (`PC\d+>`)
+- No need for configuration mode handling
+
+### VPCSTelnet Implementation
+
+#### Location
+```
+gns3server/agent/gns3_copilot/utils/custom_netmiko/vpcs_telnet.py
+```
+
+#### Key Features
+
+**1. No Authentication**
+```python
+def telnet_login(self, pri_prompt_terminator=r"PC\d+>", ...):
+    # Send returns until VPCS prompt detected
+    for i in range(max_loops):
+        self.write_channel(self.RETURN)
+        output = self.read_channel()
+
+        if re.search(pri_prompt_terminator, output):
+            return output  # Success - VPCS prompt detected
+```
+
+**2. Simple Prompt Recognition**
+```
+PC1> ip 10.10.0.12/24 10.10.0.254
+PC1> ping 10.10.0.254
+```
+
+**3. No Configuration Mode**
+```python
+def check_config_mode(self) -> bool:
+    return False  # VPCS has no config mode
+
+def config_mode(self) -> str:
+    return ""  # No config mode to enter
+
+def exit_config_mode(self) -> str:
+    return ""  # No config mode to exit
+```
+
+**4. No Paging**
+```python
+def disable_paging(self) -> str:
+    return ""  # VPCS doesn't use paging
+```
+
+**5. Custom `send_command`**
+VPCS overrides `send_command` with non-standard defaults:
+- `strip_prompt=False`, `strip_command=False`, `normalize=False` — VPCS output doesn't need standard Netmiko processing
+- Uses `_strip_ansi_codes()` to clean terminal escape sequences from VPCS output
+
+**6. ANSI Escape Code Stripping**
+VPCS output often contains ANSI terminal codes. The `_strip_ansi_codes()` method strips bold, underline, reset, and color codes before returning output to callers.
+
+### VPCS Tool Usage
+
+The VPCS driver is used by the `execute_vpcs_commands` tool:
+
+> File: `gns3server/agent/gns3_copilot/tools_v2/vpcs_tools_netmiko.py`
+
+**VPCS Connection Parameters:**
+
+VPCS devices use additional Netmiko parameters for reliable connections:
+| Parameter | Value | Reason |
+|-----------|-------|--------|
+| `fast_cli` | `False` | VPCS is slow, disable fast CLI mode |
+| `global_delay_factor` | `2.0` | Double the delay between commands |
+
+```python
+"connection_options": {
+    "netmiko": {
+        "extras": {
+            "device_type": "gns3_vpcs_telnet",
+            "fast_cli": False,
+            "global_delay_factor": 2.0,
+        }
+    }
+}
+```
+
+### VPCS Built-in Template Configuration
+
+**✨ Automatic Tags - No Manual Configuration Required**
+
+VPCS nodes created from the built-in template automatically include the necessary tags:
+
+| Tag | Value | Purpose |
+|-----|-------|---------|
+| `device_type` | `gns3_vpcs_telnet` | Netmiko driver selection |
+
+**Built-in Template Definition:**
+> File: `gns3server/services/templates.py`
+
+The VPCS built-in template includes `"tags": ["device_type:gns3_vpcs_telnet"]`, which is automatically applied to all VPCS nodes created from the template.
+
+**User Benefits:**
+- ✅ **No manual tagging required** — Tags are applied automatically when creating VPCS nodes
+- ✅ **Automatic driver selection** — Copilot tools automatically use the correct Netmiko driver
+- ✅ **Consistent behavior** — All VPCS nodes from the built-in template work identically
+- ✅ **Zero configuration** — Users don't need to understand device_type tags
+
+**How It Works:**
+1. User creates a VPCS node from the built-in "VPCS" template
+2. Node automatically inherits the tag: `device_type:gns3_vpcs_telnet`
+3. Copilot tools read the tag and select the appropriate VPCS Netmiko driver
+4. Commands execute using the VPCS-optimized driver (no authentication, simple prompts)
+
+### Supported VPCS Commands
+
+| Command | Description | Example |
+|---------|-------------|---------|
+| `ip` | Configure/show IP address | `ip 10.10.0.12/24 10.10.0.254` |
+| `ping` | Test connectivity | `ping 10.10.0.254` |
+| `arp` | Display ARP table | `arp` |
+| `show ip` | Show IP configuration | `show ip` |
+| `version` | Show VPCS version | `version` |
+| `save` | Save configuration | `save` |
+| `load` | Load configuration | `load` |
+
+### Architecture Benefits
+
+**Unified Tool Architecture:**
+- ✅ Uses Nornir for connection management (same as network device tools)
+- ✅ Uses Netmiko for command execution (consistent with other tools)
+- ✅ Follows same patterns as `config_tools_nornir.py` and `display_tools_nornir.py`
+- ✅ Simplified codebase - no need for separate telnetlib3 implementation
+
+**Migration from telnetlib3:**
+| Aspect | Old (telnetlib3) | New (Netmiko + Nornir) |
+|--------|-----------------|-------------------------|
+| Library | telnetlib3 | Netmiko |
+| Framework | Manual threading | Nornir |
+| Code Lines | ~490 lines | ~580 lines (with better structure) |
+| Consistency | Unique implementation | Same as other tools |
+| Maintenance | Separate code path | Unified architecture |
+
+---
+
+## Custom Huawei Driver (`GNS3HuaweiTelnetCE`)
+
+### Problem Statement
+
+GNS3-emulated Huawei devices connect via console **without requiring authentication**. Standard Netmiko drivers attempt username/password authentication, causing connection timeouts.
+
+**Standard Driver Behavior:**
+```
+Telnet Connection → Wait for username prompt → Send username → Wait for password → Send password → Access
+                    ^ Times out after 20 seconds
+```
+
+**GNS3 Huawei Device:**
+```
+Telnet Connection → Direct access to command line (no login prompts)
+                    <HUAWEI>
+```
+
+### Solution: Custom Driver Architecture
+
+```mermaid
+graph TD
+    A[BaseConnection] --> B[CiscoBaseConnection]
+    B --> C[HuaweiBase<br/>VRP support, system-view,<br/>prompt patterns, paging]
+    C --> D[GNS3HuaweiTelnetCE<br/>Overrides telnet_login only]
+    D --> E[Skip authentication]
+    D --> F[Auto-commit before exit]
+    D --> G[y/n auto-confirm]
+```
+
+**Why Inherit from HuaweiBase?**
+- ✅ Built-in VRP (Versatile Routing Platform) command handling
+- ✅ Huawei-specific configuration mode (`system-view`)
+- ✅ Huawei prompt patterns (`<...>`, `[...]`)
+- ✅ Huawei paging disable (`screen-length 0 temporary`)
+- ✅ Minimal code changes - only override authentication
+
+### GNS3HuaweiTelnetCE Implementation
+
+#### Location
+```
+gns3server/agent/gns3_copilot/utils/custom_netmiko/huawei_ce.py
+```
+
+**Package Structure:**
+```
+custom_netmiko/
+├── __init__.py              # Package initialization, auto-registers all drivers
+├── huawei_ce.py             # Huawei CloudEngine custom driver
+├── README.md                # Driver development guide
+└── tests/                   # Unit tests
+    ├── __init__.py
+    └── test_huawei_ce.py    # Huawei CE driver tests
+```
+
+#### Key Features
+
+1. **Skip Authentication**
+   - Directly detect Huawei prompt patterns
+   - No username/password prompts
+   - Connection ready in < 1 second
+
+2. **VRP Prompt Recognition**
+   ```
+   User view:    <HUAWEI>
+   System view:  [HUAWEI]
+   Interface:    [HUAWEI-GigabitEthernet0/0/1]
+   ```
+
+3. **Automatic Confirmation Handling**
+   - Detects and responds to `[y/n]` prompts
+   - Example: `return` command asks "Return to user view? [y/n]:"
+   - Automatically sends `y` to confirm
+
+4. **Proper Output Collection**
+   - Uses Netmiko's `read_channel_timing()` for reliable output
+   - Waits for command completion (2s no new data = done)
+   - 30-second absolute timeout prevents hanging
+
+5. **Auto-Commit Before Exit**
+   - Automatically sends `commit` command before exiting config mode
+   - Prevents "Uncommitted configurations [Y/N/C]" prompt
+   - Ensures configuration changes are saved
+
+#### Limitations
+
+**Why Not Use the Standard `huawei_telnet` Driver?**
+- The standard Netmiko Huawei driver (`huawei_telnet`) has known issues in GNS3 emulation environments
+- This is the primary reason the custom `gns3_huawei_telnet_ce` driver was developed
+- The custom driver is designed for GNS3 devices **without authentication**
+- If your GNS3 Huawei device has been configured with authentication, remove it for GNS3 testing to use the custom driver
+
+**When to Use:**
+
+| Scenario | Recommendation |
+|----------|---------------|
+| GNS3 Huawei device | Always use `gns3_huawei_telnet_ce` |
+| GNS3 device has auth configured | Remove auth, then use `gns3_huawei_telnet_ce` |
+
+#### Method Overrides
+
+**1. `telnet_login` - Skip Authentication**
+```python
+def telnet_login(self, pri_prompt_terminator=r"<\S+>|>\s*$",
+                alt_prompt_terminator=r"\[\S+\]", ...) -> str:
+    # Clear buffer
+    self.read_channel()
+
+    # Send returns until prompt detected
+    for i in range(max_loops):
+        self.write_channel(self.RETURN)
+        output = self.read_channel()
+
+        # Check for Huawei prompts
+        if re.search(pri_prompt_terminator, output):
+            return output  # Success!
+
+    return output  # Best effort
+```
+
+**2. `send_config_set` - Configuration Commands**
+```python
+def send_config_set(self, config_commands, **kwargs) -> str:
+    # Enter config mode
+    output += self.config_mode(config_command="system-view")
+
+    # Send all commands
+    for cmd in config_commands:
+        self.write_channel(f"{cmd}{self.RETURN}")
+        time.sleep(delay_factor * 0.05)
+
+    # Collect output using Netmiko standard method
+    output += self.read_channel_timing(read_timeout=30, last_read=2.0)
+
+    # Auto-commit before exit (prevents [Y/N/C] prompt)
+    self.write_channel(f"commit{self.RETURN}")
+    time.sleep(0.5 * self.global_delay_factor)
+    output += self.read_channel()
+
+    # Exit config mode
+    output += self.exit_config_mode()
+
+    return output
+```
+
+**3. `exit_config_mode` - Handle Confirmation**
+```python
+def exit_config_mode(self, exit_config="return", pattern=r"<\S+>|>\s*$") -> str:
+    self.write_channel(f"return{self.RETURN}")
+
+    # Look for confirmation prompt
+    for _ in range(20):
+        new_output = self.read_channel()
+
+        if re.search(r"\[y/n\]", new_output):
+            self.write_channel(f"y{self.RETURN}")  # Auto-confirm
+
+        if re.search(pattern, new_output):
+            return output  # Back to user view
+
+    return output
+```
+
+### Device Type Registration
+
+The custom driver must be registered with Netmiko's global mappings:
+
+```python
+def register_custom_device_type() -> None:
+    import importlib
+    sd = importlib.import_module("netmiko.ssh_dispatcher")
+
+    # Register in CLASS_MAPPER (for ConnectHandler)
+    sd.CLASS_MAPPER["gns3_huawei_telnet_ce"] = GNS3HuaweiTelnetCE
+    sd.CLASS_MAPPER["huawei_ce"] = GNS3HuaweiTelnetCE
+
+    # Register in CLASS_MAPPER_BASE (for base class definitions)
+    sd.CLASS_MAPPER_BASE["gns3_huawei_telnet_ce"] = GNS3HuaweiTelnetCE
+    sd.CLASS_MAPPER_BASE["huawei_ce"] = GNS3HuaweiTelnetCE
+
+    # CRITICAL: Rebuild static lists
+    sd.platforms = list(sd.CLASS_MAPPER.keys())
+    sd.platforms.sort()
+    sd.telnet_platforms = [x for x in sd.platforms if "telnet" in x]
+```
+
+**Important: Static List Problem**
+- `ssh_dispatcher.platforms` is computed at module import time
+- Modifying `CLASS_MAPPER` doesn't automatically update `platforms`
+- Must manually rebuild the list after registration
+
+**Auto-Registration**
+```python
+# Automatically runs on module import
+try:
+    register_custom_device_type()
+except Exception as e:
+    logger.warning(f"Failed to register custom device type: {e}")
+```
+
+## Custom Ruijie Driver (`RuijieTelnetEnhanced`)
+
+### Problem Statement
+
+Ruijie (锐捷) network devices exhibit Cisco-like command syntax but have interactive prompts during configuration that can cause standard Netmiko drivers to fail.
+
+**Common Issue - OSPF Router-ID:**
+```
+Router(config-router)#router-id 10.0.0.1
+Change router-id and update OSPF process! [yes/no]:
+```
+
+Standard Netmiko's `send_config_set()` waits for a prompt pattern, but the `[yes/no]:` prompt doesn't match the expected config mode pattern, causing:
+1. **ReadTimeout**: Netmiko times out waiting for the prompt
+2. **Command Failure**: Subsequent commands are not executed
+3. **Device Lockup**: Console remains in the waiting state
+
+### Solution: Hybrid Strategy with Interactive Prompt Handling
+
+```mermaid
+graph TD
+    A[BaseConnection] --> B[CiscoBaseConnection]
+    B --> C[RuijieOSBase<br/>Netmiko built-in]
+    C --> D[RuijieTelnetEnhanced<br/>Interactive prompt handling]
+    D --> E[Preprocessing<br/>Insert yes after known commands]
+    D --> F[Batch send<br/>Fast path 2-3s]
+    D --> G[Fallback one-by-one<br/>Slow but reliable ~10s]
+```
+
+**Why Hybrid Strategy?**
+1. **Preprocessing**: Automatically insert `yes` after known interactive commands
+2. **Fast Path**: Batch send for most commands (2-3 seconds for 13 commands)
+3. **Fallback**: One-by-one send with real-time detection (reliable but slower)
+
+### RuijieTelnetEnhanced Implementation
+
+#### Location
+```
+gns3server/agent/gns3_copilot/utils/custom_netmiko/ruijie_telnet.py
+```
+
+#### Key Features
+
+**1. Preprocessing - Known Interactive Commands**
+```python
+INTERACTIVE_PATTERNS = [
+    re.compile(r'^router-id\s+', re.IGNORECASE),  # OSPF/EIGRP/BGP router-id
+    re.compile(r'^erase\s+', re.IGNORECASE),        # erase startup-config
+    re.compile(r'^delete\s+', re.IGNORECASE),       # delete files
+    re.compile(r'^format\s+', re.IGNORECASE),       # format filesystem
+    re.compile(r'^reload\b', re.IGNORECASE),        # reload/reboot
+    re.compile(r'^boot\s+system\s+', re.IGNORECASE), # change boot image
+]
+```
+
+**2. Hybrid Send Strategy**
+
+```mermaid
+flowchart TD
+    A[Input Configuration Commands] --> B[Preprocessing]
+    B --> B1[Detect interactive commands]
+    B1 --> B2[Insert 'yes' after them]
+    B2 --> C[Try Batch Send - Fast]
+    C --> C1[Write all commands rapidly]
+    C1 --> C2[Read output once, last_read=2.0s]
+    C2 --> D{Success?}
+    D -->|Yes| E[Return output]
+    D -->|No| F[Fallback: One-by-One]
+    F --> F1[Send each command individually]
+    F1 --> F2[Detect prompts after each]
+    F2 --> F3[Send 'yes' when needed, last_read=0.5s]
+    F3 --> E
+```
+
+**3. Batch Send Performance**
+- **13 commands** with 1 interactive command
+- **Fast path**: ~2-3 seconds (includes device processing time)
+- **Fallback**: ~10 seconds (if batch fails)
+
+**4. Real-time Detection (Fallback)**
+```python
+# After each command
+new_output = self.read_channel_timing(read_timeout=10, last_read=0.5)
+
+# Check for [yes/no] prompt
+if re.search(r"\[yes/no\]", new_output, re.IGNORECASE):
+    self.write_channel(f"yes{self.RETURN}")
+    output += self.read_channel_timing(read_timeout=30, last_read=0.5)
+```
+
+#### GNS3 Node Tag Configuration
+
+**For Ruijie devices in GNS3:**
+```
+device_type:gns3_ruijie_telnet
+```
+
+**Example Usage:**
+```python
+from netmiko import ConnectHandler
+from gns3server.agent.gns3_copilot.utils import custom_netmiko
+
+device = {
+    "device_type": "gns3_ruijie_telnet",
+    "host": "127.0.0.1",
+    "port": 5000,
+}
+
+with ConnectHandler(**device) as conn:
+    # These commands include router-id (interactive)
+    config = [
+        "router ospf 1",
+        "router-id 10.0.0.1",  # Triggers [yes/no] prompt
+        "network 192.168.1.0 0.0.0.255 area 0",
+    ]
+    # Automatically handles the [yes/no] prompt
+    output = conn.send_config_set(config)
+```
+
+#### Limitations
+
+**Interactive Command Coverage:**
+- **Covered**: `router-id`, `erase`, `delete`, `format`, `reload`, `boot system`
+- **Not Covered**: Unknown or vendor-specific interactive prompts
+- **Fallback**: If batch fails, falls back to one-by-one with real-time detection
+
+**When to Use:**
+
+| Scenario | Use Driver |
+|----------|------------|
+| GNS3 Ruijie (known interactive commands) | `gns3_ruijie_telnet` (batch + auto-fallback) |
+| GNS3 Ruijie (unknown interactive prompts) | `gns3_ruijie_telnet` (auto-fallback to one-by-one) |
+
+## Dynamic Device Type Detection
+
+### GNS3 Node Tags
+
+Device type is extracted from GNS3 node tags:
+
+```
+device_type:gns3_huawei_telnet_ce    → Netmiko driver selection
+```
+
+**Tag Examples:**
+
+| Vendor | Device Type Tag | Template Source |
+|--------|----------------|-----------------|
+| Cisco IOS | `device_type:cisco_ios_telnet` | User appliance |
+| Huawei CE | `device_type:gns3_huawei_telnet_ce` | User appliance |
+| Ruijie | `device_type:gns3_ruijie_telnet` | User appliance |
+| **VPCS** | `device_type:gns3_vpcs_telnet` | **Built-in ✅** |
+
+**VPCS Built-in Template:**
+- VPCS has a **built-in template** with pre-configured `device_type` tag
+- The tag is **automatically applied** when creating VPCS nodes
+- No manual configuration required — works out of the box
+- Other devices require users to import appliances and configure tags manually
+
+### Nornir Best Practice: Host-Level Connection Configuration
+
+The system uses **Nornir's configuration priority** (host > group > defaults) to handle multi-vendor environments efficiently:
+
+```python
+# From get_gns3_device_port.py
+hosts_data[device_name] = {
+    "port": console_port,
+    "groups": ["network_devices"],  # All devices share one group
+    "connection_options": {
+        "netmiko": {
+            "extras": {"device_type": device_type}  # Device-specific driver
+        }
+    },
+}
+```
+
+**Why Host-Level `connection_options`?**
+- ✅ Each device has its own `device_type` (host-level config)
+- ✅ All devices share common settings via group inheritance (`hostname`, `timeout`)
+- ✅ No need to dynamically create multiple groups for each device type
+- ✅ Cleaner code structure — single generic group for all devices
+- ✅ Follows Nornir best practice: "configuration proximity"
+
+**Configuration Priority:**
+```mermaid
+graph TD
+    A["Host Level<br/>connection_options.device_type<br/>(gns3_huawei_telnet_ce, cisco_ios_telnet, etc.)"]
+    B["Group Level<br/>hostname=127.0.0.1, timeout=120<br/>username, password"]
+    C["Defaults Level<br/>data.location=gns3"]
+    A -->|overrides| B
+    B -->|overrides| C
+```
+
+| Aspect | Old: Dynamic Groups | New: Host-Level Config |
+|--------|--------------------|-----------------------|
+| Group count | One per vendor type | Single `network_devices` group |
+| Device type location | Group `connection_options` | Host `connection_options` |
+| Complexity | Dynamic group creation logic | No dynamic group logic |
+
+## Architecture Evolution
+
+### Problem: Multi-Vendor Device Support
+
+**Initial Challenge:**
+```mermaid
+graph TD
+    A[Topology: Cisco R1 + Huawei SW1 + Juniper SRX] --> B[Need: Different Netmiko drivers per device]
+    B --> C[Question: How to configure Nornir for multiple device types?]
+```
+
+### Solution Evolution
+
+| Approach | Strategy | Issue |
+|----------|----------|-------|
+| ❌ Approach 1 | Single group with first device's `device_type` | All devices use wrong driver |
+| ❌ Approach 2 | Dynamic groups per vendor (`huawei_telnet`, `cisco_telnet`, ...) | Complex logic, code duplication, not Nornir best practice |
+| ✅ Approach 3 (Current) | **Host-level `connection_options`** + single generic group | Clean, follows Nornir host > group > defaults priority |
+
+> See `get_gns3_device_port.py:get_device_ports_from_topology()` for the current implementation.
+
+### Configuration Priority Demonstration
+
+```mermaid
+graph TD
+    A["Host Level (highest)<br/>device_type: gns3_huawei_telnet_ce"]
+    B["Group Level (middle)<br/>hostname: 127.0.0.1, timeout: 120"]
+    C["Defaults Level (lowest)<br/>data.location: gns3"]
+    A -->|overrides| B -->|overrides| C
+    D[Result] --> D1["Each device uses its own device_type"]
+    D --> D2["All share hostname, timeout from group"]
+    D --> D3["All share data.location from defaults"]
+```
+
+## Usage Examples
+
+### Direct Netmiko Usage
+
+**Custom driver auto-registers on import. No username/password needed for GNS3 devices.**
+
+| Device Type | `device_type` | Auth | Notes |
+|-------------|---------------|------|-------|
+| Huawei CE | `gns3_huawei_telnet_ce` | None | Custom driver, skip auth |
+| Ruijie | `gns3_ruijie_telnet` | None | Custom driver, interactive prompts handled |
+| VPCS | `gns3_vpcs_telnet` | None | Custom driver, no config mode |
+| Cisco IOS | `cisco_ios_telnet` | Required | Standard Netmiko driver |
+
+### GNS3 Copilot Tool Usage
+
+> Tools: `tools_v2/display_tools_nornir.py`, `tools_v2/config_tools_nornir.py`, `tools_v2/vpcs_tools_netmiko.py`
+
+Each tool reads node tags to determine `device_type`, builds host-level Nornir inventory, and dispatches commands to the appropriate Netmiko driver. Multi-vendor topologies are handled transparently — each device uses its own driver.
+
+## Module Structure
+
+```
+gns3server/agent/gns3_copilot/
+├── utils/
+│   ├── custom_netmiko/            # Custom Netmiko drivers package
+│   │   ├── __init__.py             # Auto-registers all drivers on import
+│   │   ├── huawei_ce.py            # Huawei CloudEngine driver
+│   │   ├── ruijie_telnet.py        # Ruijie enhanced driver
+│   │   ├── vpcs_telnet.py          # VPCS simulator driver
+│   │   ├── README.md               # Driver development guide
+│   │   └── tests/                  # Unit tests (52 total)
+│   │       ├── __init__.py
+│   │       ├── test_huawei_ce.py   # Huawei CE driver tests (9)
+│   │       ├── test_ruijie_telnet.py # Ruijie driver tests (15)
+│   │       └── test_vpcs_telnet.py   # VPCS driver tests (28)
+│   └── get_gns3_device_port.py     # Device port extraction
+│       └── get_device_ports_from_topology()  # Extract ports + device_type from tags
+├── tools_v2/
+│   ├── display_tools_nornir.py     # Multi-vendor display commands
+│   ├── config_tools_nornir.py      # Multi-vendor config commands
+│   │   └── _expand_multiline_commands()   # Expand banner commands
+│   └── vpcs_tools_netmiko.py      # VPCS commands using Nornir + Netmiko
+│       └── VPCSCommands           # VPCS tool class
+```
+
+**Key Architectural Changes (2026-03-14):**
+- ❌ Removed: `vpcs_tools_telnetlib3.py` - Replaced with Netmiko implementation
+- ✅ Added: `vpcs_telnet.py` - Custom VPCS driver for Netmiko
+- ✅ Added: `vpcs_tools_netmiko.py` - VPCS tool using Nornir + Netmiko
+- ✅ Simplified: Unified tool architecture - all tools use Nornir + Netmiko
+- ✅ Updated: Module structure - all tools follow same pattern
+
+**Key Architectural Changes (2026-03-13):**
+- ❌ Removed: `_get_nornir_groups_config()` - No longer needed
+- ❌ Removed: `_get_nornir_group()` - No longer needed
+- ✅ Simplified: `_initialize_nornir()` - Uses single generic group
+- ✅ Updated: `get_gns3_device_port.py()` - Returns host-level `connection_options`
+- ✅ Added: `ruijie_telnet.py` - Custom Ruijie driver with interactive prompt handling
+- ✅ Added: `_expand_multiline_commands()` - Auto-expands banner and multi-line commands
+- ✅ Added: device_type tag validation with error feedback (inline in `_run`)
+
+## Unit Testing
+
+### Test Coverage
+
+> Test files located at: `gns3server/agent/gns3_copilot/utils/custom_netmiko/tests/`
+
+**Total: 52 tests across 3 test files**
+
+| Test File | Tests | Coverage Focus |
+|-----------|-------|----------------|
+| `test_huawei_ce.py` | 9 | Registration, inheritance, VRP methods, mock connection |
+| `test_ruijie_telnet.py` | 15 | Registration, interactive patterns, preprocessing, batch/fallback |
+| `test_vpcs_telnet.py` | 28 | Registration, login, command sending, ANSI stripping, config mode |
+
+#### Huawei CE Tests (`TestHuaweiTelnetCEDriver` + `TestHuaweiTelnetCEIntegration`)
+- Device type registration in CLASS_MAPPER
+- Inheritance from HuaweiBase
+- VRP-specific methods (`config_mode`, `check_config_mode`, `exit_config_mode`)
+- Prompt pattern constants
+- Mock telnet connection
+
+#### Ruijie Tests (`TestRuijieTelnetEnhancedDriver` + `TestRuijieTelnetEnhancedIntegration`)
+- Device type registration
+- Inheritance from RuijieOSBase
+- Interactive pattern matching (`router-id`, `erase`, `delete`, etc.)
+- Preprocessing of interactive commands
+- Batch and fallback send strategies
+
+#### VPCS Tests (`TestVPCSTelnetDriver` + 5 more test classes)
+- Device type registration
+- Inheritance from BaseConnection
+- No-auth login with `PC\d+>` prompt
+- `send_command` / `send_command_timing` overrides
+- ANSI escape code stripping (8 dedicated tests)
+- Config mode always returns empty/false
+
+**Running Tests:**
+```bash
+source venv/bin/activate
+python -m pytest gns3server/agent/gns3_copilot/utils/custom_netmiko/tests/
+```
+
+**Current Test Status:** ✅ All 52 tests passing
+
+## Related Documentation
+
+- [Custom Netmiko README](../../../../../gns3server/agent/gns3_copilot/utils/custom_netmiko/README.md) - Driver development guide
+- [Node Control Tools](./node-control-tools.md) - Device lifecycle management
+- [Command Security](./command-security.md) - Command filtering and validation
+- [Chat API](./chat-api.md) - Session management and SSE
+
+## References
+
+- [Netmiko Documentation](https://ktbyers.github.io/netmiko/)
+- [Netmiko PLATFORMS.md](https://github.com/ktbyers/netmiko/blob/master/PLATFORMS.md)
+- [Nornir Documentation](https://nornir.readthedocs.io/)
+
+---
+
+_Implementation Date: 2026-03-12_
+
+_Last Updated: 2026-04-20 (Documentation review: fixed VPCS template tags, updated test coverage, added Mermaid diagrams, removed code bloat)_
+
+_Status: ✅ Implemented - Custom drivers for Huawei, Ruijie, and VPCS; multi-vendor support with Cisco IOS, Huawei, Ruijie, and VPCS tested_
+
+_Architecture: Nornir best practice - host-level connection_options with single generic group_
+
+_Unit Tests: ✅ 52/52 passing (9 Huawei + 15 Ruijie + 28 VPCS)_
+
+_Changelog:_
+- **2026-03-14**: Added VPCS support and unified tool architecture
+  - Implemented `VPCSTelnet` custom Netmiko driver for VPCS simulator
+  - Replaced `vpcs_tools_telnetlib3.py` with `vpcs_tools_netmiko.py`
+  - Unified all tools to use Nornir + Netmiko architecture
+  - Removed dependency on telnetlib3 for VPCS devices
+  - Improved code consistency and maintainability
+- **2026-03-13 (Evening)**: Added Ruijie enhanced driver and interactive command handling
+  - Implemented `RuijieTelnetEnhanced` with hybrid batch/fallback strategy
+  - Added automatic `yes` insertion for known interactive commands (`router-id`, `erase`, etc.)
+  - Achieves ~2-3 seconds for 13 commands (vs 10+ seconds for one-by-one)
+  - Auto-fallback to real-time detection for unknown interactive prompts
+  - Registered `gns3_ruijie_telnet` device type
+- **2026-03-13 (Afternoon)**: Enhanced configuration safety and command handling
+  - Added AAA/password configuration prohibition in system prompts
+  - Implemented multi-line command expansion (`_expand_multiline_commands()`)
+  - Added `device_type` tag validation with error feedback
+  - Prevents execution of commands that could lock users out of devices
+  - Properly handles banner and other multi-line configuration commands
+- **2026-03-13 (Morning)**: Refactored to use host-level `connection_options` instead of dynamic groups
+  - Removed `_get_nornir_groups_config()` and `_get_nornir_group()` helper functions
+  - Simplified `_initialize_nornir()` to use single generic group
+  - Updated `get_gns3_device_port.py()` to return host-level configuration
+- **2026-03-12**: Initial implementation with custom Huawei driver

docs/gns3-copilot/implemented/packet-analysis-overview.en.md

@@ -0,0 +1,74 @@
+<!--
+SPDX-License-Identifier: CC-BY-SA-4.0
+See LICENSE file for licensing information.
+-->
+
+# GNS3-Copilot Real-time Packet AI Analysis Overview
+
+## Core Flow
+
+```mermaid
+flowchart TB
+    subgraph "① Analysis Trigger & Knowledge Query"
+        A["User asks\n'e.g. Analyze OSPF neighbor state'"] --> B["LLM calls\nPacketAnalysisSkillsTool"]
+        B --> C{"Protocol Knowledge Repository\ngns3/gns3-skills"}
+        C --> D["Returns protocol definition\nfields/base_filter/check_rules"]
+        B --> E["LLM calls\nsearch_fields mode"]
+        E --> F["tshark -G fields\nfield name search"]
+        F --> G["Returns valid field names"]
+    end
+
+    subgraph "② Live Capture & Analysis"
+        D --> H["LLM constructs tshark_args"]
+        G --> H
+        H --> I["PacketAnalysisTool\ncapture analysis mode"]
+        I --> J["GET /capture/file\ndownload live PCAP"]
+        J --> K["Pre-validate -e field names"]
+        K --> L["tshark -r pcap\nrun analysis"]
+        L --> M["Return analysis results"]
+    end
+```
+
+## Tool Overview
+
+| Tool | Source File | Purpose | Available Modes |
+|---|---|---|---|
+| `PacketAnalysisTool` | `packet_analysis_tool.py` | Download live PCAP + tshark analysis | teaching / lab_automation |
+| `PacketAnalysisSkillsTool` | `registry.py` (skills module) | Query protocol-level analysis knowledge (fields, filters) | teaching / lab_automation |
+
+## Agent Workflow (LangGraph)
+
+```mermaid
+sequenceDiagram
+    participant U as User
+    participant LLM as LLM Node
+    participant Skills as PacketAnalysisSkillsTool
+    participant Pcap as PacketAnalysisTool
+
+    U->>LLM: OSPF neighbors can't establish, analyze
+    LLM->>Skills: get protocol=ospf
+    Skills-->>LLM: OSPF fields, filter definitions
+    LLM->>Pcap: search_fields query=ospf.hello
+    Pcap-->>LLM: valid -e field names
+    LLM->>Pcap: download PCAP + tshark_args
+    Pcap-->>LLM: tshark output results
+    LLM->>LLM: analysis reveals Dead interval mismatch
+    LLM-->>U: OSPF Dead interval mismatch detected
+```
+
+## Server Capture API
+
+| Endpoint | Function |
+|---|---|
+| `POST /v3/projects/{pid}/links/{lid}/capture/start` | Start packet capture on a link |
+| `POST /v3/projects/{pid}/links/{lid}/capture/stop` | Stop packet capture |
+| `GET /v3/projects/{pid}/links/{lid}/capture/file` | Download PCAP file (available even while capture is active) |
+| `GET /v3/projects/{pid}/links/{lid}/capture/stream` | Stream PCAP data |
+| `WS /v3/projects/{pid}/links/{lid}/capture/web-wireshark` | Web Wireshark WebSocket proxy |
+
+## Key Design Points
+
+1. **LLM-driven Analysis** — The LLM constructs tshark parameters itself; the framework does not hardcode protocol logic, only performs safety validation
+2. **Live PCAP** — Captures can be downloaded and analyzed while running, no need to stop capturing
+3. **Dual Knowledge Sources** — External repository provides protocol-specific knowledge; local tshark field registry provides exact field names
+4. **Safety First** — Pre-validation of tshark field names prevents execution failures from invalid fields

docs/gns3-copilot/implemented/packet-analysis.md

@@ -0,0 +1,182 @@
+<!--
+SPDX-License-Identifier: CC-BY-SA-4.0
+See LICENSE file for licensing information.
+-->
+
+> This documentation is organized by AI with reference to actual code. AI can make mistakes — please verify against the source code when in doubt.
+
+
+# Protocol-Oriented Packet Analysis
+
+## Overview
+
+GNS3 Copilot provides protocol-oriented packet analysis that allows the AI assistant to diagnose network issues from live GNS3 captures. Protocol definitions (tshark fields, display filters, check rules) are stored as YAML files in the external GNS3-Skills repository and loaded into memory at startup.
+
+The system exposes two LangChain tools: `PacketAnalysisSkillsTool` queries protocol definitions, and `PacketAnalysisTool` runs tshark against downloaded pcap files using the LLM-constructed arguments.
+
+## Architecture
+
+```mermaid
+graph TD
+    subgraph "GNS3-Skills Repository"
+        YAML[packet_analysis/*.yaml<br/>40+ protocol files]
+    end
+
+    subgraph "GNS3 Server"
+        SM[SkillsManager]
+        SL[SkillsLoader]
+        REG[PACKET_ANALYSIS_REGISTRY<br/>in-memory dict]
+        SKILL[PacketAnalysisSkillsTool<br/>query protocol definitions]
+        TOOL[PacketAnalysisTool<br/>run tshark on captures]
+    end
+
+    subgraph "tshark"
+        FIELDS["tshark -G fields"<br/>live field registry]
+        CAP["tshark -r pcap"<br/>packet capture analysis]
+    end
+
+    YAML -->|load at startup / reload| SL
+    SL --> REG
+    SM --> SL
+
+    SKILL -->|read protocol fields/filters| REG
+    TOOL -->|validate -e fields| FIELDS
+    TOOL -->|download pcap + run tshark| CAP
+```
+
+## Supported Protocols
+
+Definitions are loaded from `GNS3-Skills/packet_analysis/*.yaml`. The following protocol families are covered:
+
+| Category | Protocols |
+|----------|-----------|
+| Network Layer | ip, ipv6, arp, icmp, icmpv6 |
+| Transport Layer | tcp, udp |
+| Data Link | ethernet, ppp, hdlc, frame_relay, vlan, isl, llc |
+| Routing | ospf, eigrp, rip, bgp, isis, pim, dvmrp |
+| Link Protocols | l2tp, lacp, pagp, udld |
+| Infrastructure | cdp, lldp, stp, vtp, dtp |
+| Management | snmp, telnet, ssh, radius, tacacs |
+| Application | dns, http, bootp, dhcp |
+| Tunneling / Security | gre, esp, ah, mpls, eapol, ssl, isakmp |
+| Miscellaneous | nbns, slarp, ocsp, wccp, auto_rp, loop |
+
+Each protocol YAML contains:
+
+```yaml
+name: "OSPF Packet Analysis"
+description: "Analyze OSPF routing protocol packets"
+protocol_key: "ospf"
+display_filter: "ospf"
+fields:
+  - label: "Source IP"
+    tshark_field: "ip.src"
+    description: "Source IPv4 address"
+  - label: "OSPF Message Type"
+    tshark_field: "ospf.msg"
+    description: "1=Hello, 2=DBD, 3=LSR, 4=LSU, 5=LSAck"
+filter_examples:
+  - description: "Show OSPF Hello packets"
+    filter: "ospf.msg == 1"
+checks:
+  - name: hello_dead_mismatch
+    severity: critical
+    message: "Hello/Dead Interval mismatch between neighbors"
+```
+
+## Analysis Flow
+
+```mermaid
+sequenceDiagram
+    participant LLM as LLM Agent
+    participant SKILL as PacketAnalysisSkillsTool
+    participant TOOL as PacketAnalysisTool
+    participant tshark as tshark
+    participant GNS3 as GNS3 Server
+
+    LLM->>SKILL: {"action": "list"}
+    SKILL-->>LLM: Available protocols
+
+    LLM->>SKILL: {"action": "get", "protocol": "ospf"}
+    SKILL-->>LLM: Fields, filters, check rules
+
+    Note over LLM: LLM constructs tshark_args<br/>using protocol knowledge
+
+    LLM->>TOOL: {project_id, link_id,<br/>tshark_args: "-Y ospf -T fields -e ip.src -e ospf.msg"}
+    TOOL->>TOOL: Validate -e field names<br/>against tshark -G fields
+    TOOL->>GNS3: Download pcap for link_id
+    GNS3-->>TOOL: Capture file
+    TOOL->>tshark: tshark -r pcap -Y ospf -T fields -e ip.src -e ospf.msg
+    tshark-->>TOOL: Tab-separated output
+    TOOL-->>LLM: Raw tshark output
+```
+
+## Tool Registration
+
+The packet analysis tools are available in two copilot modes:
+
+| Tool | Teaching Assistant | Lab Automation | Troubleshooting Injection |
+|------|:------------------:|:--------------:|:-------------------------:|
+| `PacketAnalysisTool` | Yes | Yes | No |
+| `PacketAnalysisSkillsTool` | Yes | Yes | No |
+
+## Tool Interface
+
+### PacketAnalysisSkillsTool (`packet_analysis_skills`)
+
+Queries protocol definitions from the `PACKET_ANALYSIS_REGISTRY`. Used before running tshark to look up valid field names, display filters, and anomaly checks.
+
+| Action | Input | Output |
+|--------|-------|--------|
+| List protocols | `{"action": "list"}` | `{count, protocols: [{protocol, name, description}]}` |
+| Get protocol | `{"action": "get", "protocol": "ospf"}` | Protocol definition with fields, filters, checks |
+
+### PacketAnalysisTool (`packet_analysis`)
+
+Runs tshark against a downloaded GNS3 capture file. Supports two modes:
+
+**Capture analysis mode:**
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `project_id` | Yes | UUID of the GNS3 project |
+| `link_id` | Yes | UUID of the link to analyze |
+| `tshark_args` | Yes | tshark arguments (after `-r <pcap>`) |
+
+**Field search mode:**
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `action` | Yes | `"search_fields"` |
+| `query` | Yes | Single keyword (e.g., `"ospf.lsa"`, `"bgp.open"`) |
+
+### Validation and Error Handling
+
+Before downloading the capture, the tool validates `-e` field names against the live tshark field registry (`tshark -G fields`). Invalid field names are rejected early with a hint to use `search_fields`.
+
+| Scenario | Response |
+|----------|----------|
+| Invalid `-e` field name | `{error, hint, invalid_fields}` |
+| tshark filter/field error | `{error: "tshark argument error", hints}` |
+| Empty capture file | `{error: "Capture file is empty"}` |
+| No matching packets | `{result: "No matching packets found", hints}` |
+| tshark timeout (30s) | `{error: "tshark timeout after 30 seconds"}` |
+| tshark not installed | `{error: "tshark not installed"}` |
+
+When `-c` is used and no results are found, the tool hints that `-c` limits total packets read (not matched count), and suggests removing it or piping to `head`.
+
+## Hot Reload
+
+Packet analysis protocols can be reloaded without restarting the server via the existing reload API:
+
+```
+POST /v3/copilot/reload/skills
+```
+
+This triggers `SkillsManager.reload_packet_analysis_protocols()`, which re-reads all YAML files from the `packet_analysis/` directory and updates `PACKET_ANALYSIS_REGISTRY` in place.
+
+## Related Documentation
+
+- [External Skills Repository](skills-repository.md)
+- [Fault Injection](fault-injection.md)
+- [Chat API](chat-api.md)

docs/gns3-copilot/implemented/skills-repository.md

@@ -0,0 +1,171 @@
+<!--
+SPDX-License-Identifier: CC-BY-SA-4.0
+See LICENSE file for licensing information.
+-->
+
+> This documentation is organized by AI with reference to actual code. AI can make mistakes — please verify against the source code when in doubt.
+
+
+# External Skills Repository
+
+## Overview
+
+GNS3 Copilot loads all skills, prompts, and security configurations from an external Git repository at [github.com/gns3/gns3-skills](https://github.com/gns3/gns3-skills). This enables dynamic updates without server redeployment.
+
+The repository provides:
+- **Injection skills** (39 categories): Network fault scenarios for troubleshooting practice
+- **Device skills**: Device-specific command knowledge (VPCS, etc.)
+- **Feature skills**: Topology planning, network design
+- **System prompts**: Agent personality and behavior definitions
+- **Forbidden commands**: Security rules for command filtering
+
+## Architecture
+
+```mermaid
+graph TD
+    subgraph "GNS3-Skills Repository"
+        YAML[injection/*.yaml<br/>device/*.yaml<br/>feature/*.yaml]
+        MD[prompts/*.md]
+        CFG[config/forbidden_commands.txt]
+    end
+
+    subgraph "GNS3 Server"
+        SM[SkillsManager]
+        SL[SkillsLoader]
+        REG[Registry<br/>SKILLS_REGISTRY<br/>INJECTION_SKILLS_REGISTRY]
+        PROMPT[PROMPTS_CACHE]
+        FC[command_filter]
+    end
+
+    YAML --> SL
+    MD --> SL
+    CFG --> FC
+    SL --> REG
+    SL --> PROMPT
+    SM --> SL
+    SM -->|git pull| YAML
+```
+
+## Repository Structure
+
+```
+GNS3-Skills/
+├── injection/          # 39 YAML files, one per protocol/category
+│   ├── ospf_issues.yaml
+│   ├── bgp_issues.yaml
+│   ├── vlan_issues.yaml
+│   └── ...
+├── device/             # Device-specific skills
+│   └── vpcs.yaml
+├── feature/            # Feature skills
+│   └── topology_planner.yaml
+├── prompts/            # System prompts (Markdown)
+│   ├── teaching_assistant.md
+│   ├── lab_automation_assistant.md
+│   ├── troubleshooting_injection.md
+│   └── title.md
+└── config/             # Security configuration
+    └── forbidden_commands.txt
+```
+
+## Configuration
+
+Skills repository settings are configured in `gns3_server.conf` under the `[Server]` section:
+
+```ini
+[Server]
+skills_repo_url = https://github.com/gns3/gns3-skills.git
+skills_repo_branch = main
+skills_auto_update = true
+```
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `skills_repo_url` | `https://github.com/gns3/gns3-skills.git` | Git repository URL |
+| `skills_repo_branch` | `main` | Git branch to track |
+| `skills_auto_update` | `true` | Automatically pull on reload |
+
+## Initialization Flow
+
+```mermaid
+sequenceDiagram
+    participant Server
+    participant agent/__init__.py
+    participant SkillsManager
+    participant Git
+
+    Server->>agent/__init__.py: Import module
+    agent/__init__.py->>SkillsManager: Start background init thread
+    Note over SkillsManager: Thread.join(5s timeout)
+
+    SkillsManager->>Git: Check local repo exists?
+    alt No local repo
+        Git->>SkillsManager: git clone (with timeout env)
+    else Local repo exists
+        SkillsManager->>Git: Check uncommitted changes?
+        alt Has uncommitted changes
+            Git-->>SkillsManager: Warn, skip pull
+        else No changes
+            SkillsManager->>Git: git fetch (timeout 10s)
+            SkillsManager->>Git: Behind remote?
+            alt Behind
+                Git->>SkillsManager: git pull
+            else Up to date
+                Git-->>SkillsManager: Nothing to do
+            end
+        end
+    end
+
+    SkillsManager->>SkillsManager: reload_skills() - load YAML files
+    SkillsManager->>SkillsManager: reload_prompts() - load Markdown files
+```
+
+### Git Timeout Configuration
+
+Git operations use per-command environment variables to prevent hanging:
+
+```python
+_GIT_TIMEOUT_ENV = {
+    'GIT_HTTP_TIMEOUT': '10',           # Connection timeout (default: 120s)
+    'GIT_HTTP_LOW_SPEED_TIME': '5',     # Slow speed threshold window
+    'GIT_HTTP_LOW_SPEED_LIMIT': '1000', # < 1 KB/s = slow → abort
+}
+```
+
+These apply only to the specific `clone`/`fetch`/`pull` subprocess, not to the global environment.
+
+## API Endpoint
+
+### POST /copilot/reload/skills
+
+Triggers a full reload of the skills repository. Performs one git update check, then reloads all skills, prompts, and forbidden commands from local files.
+
+**Response:**
+
+```json
+{
+  "success": true,
+  "skills": true,
+  "skill_count": 39,
+  "prompts": true,
+  "prompt_count": 4,
+  "forbidden_commands": 6,
+  "version": "abc123def456..."
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `success` | Overall success (true if skills or prompts loaded) |
+| `skills` | Skills reload result |
+| `skill_count` | Number of injection skills loaded |
+| `prompts` | Prompts reload result |
+| `prompt_count` | Number of prompts loaded |
+| `forbidden_commands` | Number of forbidden command patterns |
+| `version` | Git commit hash of the repository |
+
+## Related Documentation
+
+- [Fault Injection](fault-injection.md)
+- [Command Security](command-security.md)
+- [Chat API](chat-api.md)

docs/gns3-copilot/netmiko_devices.md

@@ -0,0 +1,255 @@
+<!--
+SPDX-License-Identifier: CC-BY-SA-4.0
+See LICENSE file for licensing information.
+-->
+> This documentation is organized by AI with reference to actual code. AI can make mistakes — please verify against the source code when in doubt.
+
+
+
+# Netmiko Supported Devices
+
+**Netmiko Version:** 4.6.0
+**Generated:** 2026-03-14 13:10:00
+**Last Updated:** 2026-03-14 (Added VPCS support)
+
+---
+
+## Summary
+
+- **Total Device Types:** 366
+- **SSH Devices:** 154
+- **Telnet Devices:** 55
+- **Custom Devices:** 3
+
+## Custom GNS3 Drivers
+
+GNS3-Copilot includes custom Netmiko drivers optimized for GNS3 emulation:
+
+| Platform | Device Type | Description |
+|----------|-------------|-------------|
+| Huawei CE | `gns3_huawei_telnet_ce` | Huawei CloudEngine driver with no authentication |
+| Ruijie | `gns3_ruijie_telnet` | Ruijie OS enhanced driver with interactive command handling |
+| VPCS | `gns3_vpcs_telnet` | VPCS simulator driver with ANSI code stripping |
+
+## SSH Supported Devices
+
+| Platform | Device Type | Source |
+|----------|-------------|--------|
+| A10 | `a10_ssh` | Netmiko |
+| Accedian | `accedian_ssh` | Netmiko |
+| Adtran | `adtran_os_ssh` | Netmiko |
+| Adva | `adva_fsp150f2_ssh` | Netmiko |
+| Adva | `adva_fsp150f3_ssh` | Netmiko |
+| Alaxala | `alaxala_ax26s_ssh` | Netmiko |
+| Alaxala | `alaxala_ax36s_ssh` | Netmiko |
+| Alcatel | `alcatel_aos_ssh` | Netmiko |
+| Alcatel | `alcatel_sros_ssh` | Netmiko |
+| Allied | `allied_telesis_awplus_ssh` | Netmiko |
+| Apresia | `apresia_aeos_ssh` | Netmiko |
+| Arista | `arista_eos_ssh` | Netmiko |
+| Arris | `arris_cer_ssh` | Netmiko |
+| Aruba | `aruba_aoscx_ssh` | Netmiko |
+| Aruba | `aruba_os_ssh` | Netmiko |
+| Aruba | `aruba_osswitch_ssh` | Netmiko |
+| Aruba | `aruba_procurve_ssh` | Netmiko |
+| Asterfusion | `asterfusion_asternos_ssh` | Netmiko |
+| Audiocode | `audiocode_66_ssh` | Netmiko |
+| Audiocode | `audiocode_72_ssh` | Netmiko |
+| Audiocode | `audiocode_shell_ssh` | Netmiko |
+| Avaya | `avaya_ers_ssh` | Netmiko |
+| Avaya | `avaya_vsp_ssh` | Netmiko |
+| Bintec | `bintec_boss_ssh` | Netmiko |
+| Broadcom | `broadcom_icos_ssh` | Netmiko |
+| Brocade | `brocade_fastiron_ssh` | Netmiko |
+| Brocade | `brocade_fos_ssh` | Netmiko |
+| Brocade | `brocade_netiron_ssh` | Netmiko |
+| Brocade | `brocade_nos_ssh` | Netmiko |
+| Brocade | `brocade_vdx_ssh` | Netmiko |
+| Brocade | `brocade_vyos_ssh` | Netmiko |
+| Calix | `calix_b6_ssh` | Netmiko |
+| Casa | `casa_cmts_ssh` | Netmiko |
+| Cdot | `cdot_cros_ssh` | Netmiko |
+| Centec | `centec_os_ssh` | Netmiko |
+| Check Point | `checkpoint_gaia_ssh` | Netmiko |
+| Ciena | `ciena_saos10_ssh` | Netmiko |
+| Ciena | `ciena_saos_ssh` | Netmiko |
+| Ciena | `ciena_waveserver_ssh` | Netmiko |
+| Cisco | `cisco_apic_ssh` | Netmiko |
+| Cisco | `cisco_asa_ssh` | Netmiko |
+| Cisco | `cisco_ftd_ssh` | Netmiko |
+| Cisco | `cisco_ios_ssh` | Netmiko |
+| Cisco | `cisco_nxos_ssh` | Netmiko |
+| Cisco | `cisco_s200_ssh` | Netmiko |
+| Cisco | `cisco_s300_ssh` | Netmiko |
+| Cisco | `cisco_tp_ssh` | Netmiko |
+| Cisco | `cisco_viptela_ssh` | Netmiko |
+| Cisco | `cisco_wlc_ssh` | Netmiko |
+| Cisco | `cisco_xe_ssh` | Netmiko |
+| Cisco | `cisco_xr_ssh` | Netmiko |
+| Cloudgenix | `cloudgenix_ion_ssh` | Netmiko |
+| Corelight | `corelight_linux_ssh` | Netmiko |
+| Coriant | `coriant_ssh` | Netmiko |
+| Cumulus | `cumulus_linux_ssh` | Netmiko |
+| Dell | `dell_dnos9_ssh` | Netmiko |
+| Dell | `dell_force10_ssh` | Netmiko |
+| Dell | `dell_isilon_ssh` | Netmiko |
+| Dell | `dell_os10_ssh` | Netmiko |
+| Dell | `dell_os6_ssh` | Netmiko |
+| Dell | `dell_os9_ssh` | Netmiko |
+| Dell | `dell_powerconnect_ssh` | Netmiko |
+| Dell | `dell_sonic_ssh` | Netmiko |
+| Digi | `digi_transport_ssh` | Netmiko |
+| Dlink | `dlink_ds_ssh` | Netmiko |
+| Edgecore | `edgecore_sonic_ssh` | Netmiko |
+| Ekinops | `ekinops_ek360_ssh` | Netmiko |
+| Eltex | `eltex_esr_ssh` | Netmiko |
+| Eltex | `eltex_ssh` | Netmiko |
+| Endace | `endace_ssh` | Netmiko |
+| Enterasys | `enterasys_ssh` | Netmiko |
+| Ericsson | `ericsson_ipos_ssh` | Netmiko |
+| Ericsson | `ericsson_mltn63_ssh` | Netmiko |
+| Ericsson | `ericsson_mltn66_ssh` | Netmiko |
+| Extreme | `extreme_ers_ssh` | Netmiko |
+| Extreme | `extreme_exos_ssh` | Netmiko |
+| Extreme | `extreme_netiron_ssh` | Netmiko |
+| Extreme | `extreme_nos_ssh` | Netmiko |
+| Extreme | `extreme_slx_ssh` | Netmiko |
+| Extreme | `extreme_ssh` | Netmiko |
+| Extreme | `extreme_tierra_ssh` | Netmiko |
+| Extreme | `extreme_vdx_ssh` | Netmiko |
+| Extreme | `extreme_vsp_ssh` | Netmiko |
+| Extreme | `extreme_wing_ssh` | Netmiko |
+| F5 | `f5_linux_ssh` | Netmiko |
+| F5 | `f5_ltm_ssh` | Netmiko |
+| F5 | `f5_tmsh_ssh` | Netmiko |
+| Fiberstore | `fiberstore_fsos_ssh` | Netmiko |
+| Fiberstore | `fiberstore_fsosv2_ssh` | Netmiko |
+| Fiberstore | `fiberstore_networkos_ssh` | Netmiko |
+| Flexvnf | `flexvnf_ssh` | Netmiko |
+| Fortinet | `fortinet_ssh` | Netmiko |
+| Garderos | `garderos_grs_ssh` | Netmiko |
+| Generic | `generic_ssh` | Netmiko |
+| Generic | `generic_termserver_ssh` | Netmiko |
+| H3C (华三) | `h3c_comware_ssh` | Netmiko |
+| HP | `hp_comware_ssh` | Netmiko |
+| HP | `hp_procurve_ssh` | Netmiko |
+| Hillstone | `hillstone_stoneos_ssh` | Netmiko |
+| Huawei | `huawei_olt_ssh` | Netmiko |
+| Huawei | `huawei_smartax_ssh` | Netmiko |
+| Huawei | `huawei_smartaxmmi_ssh` | Netmiko |
+| Huawei | `huawei_ssh` | Netmiko |
+| Huawei | `huawei_vrp_ssh` | Netmiko |
+| Huawei | `huawei_vrpv8_ssh` | Netmiko |
+| Infinera | `infinera_packet_ssh` | Netmiko |
+| Ipinfusion | `ipinfusion_ocnos_ssh` | Netmiko |
+| Juniper | `juniper_junos_ssh` | Netmiko |
+| Juniper | `juniper_screenos_ssh` | Netmiko |
+| Juniper | `juniper_ssh` | Netmiko |
+| Keymile | `keymile_nos_ssh` | Netmiko |
+| Keymile | `keymile_ssh` | Netmiko |
+| Lancom | `lancom_lcossx4_ssh` | Netmiko |
+| Linux | `linux_ssh` | Netmiko |
+| Maipu (迈普) | `maipu_ssh` | Netmiko |
+| Mellanox | `mellanox_mlnxos_ssh` | Netmiko |
+| Mellanox | `mellanox_ssh` | Netmiko |
+| Mikrotik | `mikrotik_routeros_ssh` | Netmiko |
+| Mikrotik | `mikrotik_switchos_ssh` | Netmiko |
+| Mrv | `mrv_lx_ssh` | Netmiko |
+| Mrv | `mrv_optiswitch_ssh` | Netmiko |
+| Nec | `nec_ix_ssh` | Netmiko |
+| Netapp | `netapp_cdot_ssh` | Netmiko |
+| Netgear | `netgear_prosafe_ssh` | Netmiko |
+| Netscaler | `netscaler_ssh` | Netmiko |
+| Nokia | `nokia_srl_ssh` | Netmiko |
+| Nokia | `nokia_sros_ssh` | Netmiko |
+| Oneaccess | `oneaccess_oneos_ssh` | Netmiko |
+| Ovs | `ovs_linux_ssh` | Netmiko |
+| Palo Alto | `paloalto_panos_ssh` | Netmiko |
+| Pluribus | `pluribus_ssh` | Netmiko |
+| Quanta | `quanta_mesh_ssh` | Netmiko |
+| Rad | `rad_etx_ssh` | Netmiko |
+| Raisecom | `raisecom_roap_ssh` | Netmiko |
+| Ruckus | `ruckus_fastiron_ssh` | Netmiko |
+| Ruijie (锐捷) | `ruijie_os_ssh` | Netmiko |
+| Silverpeak | `silverpeak_vxoa_ssh` | Netmiko |
+| Sixwind | `sixwind_os_ssh` | Netmiko |
+| Sophos | `sophos_sfos_ssh` | Netmiko |
+| Supermicro | `supermicro_smis_ssh` | Netmiko |
+| Telcosystems | `telcosystems_binos_ssh` | Netmiko |
+| Teldat | `teldat_cit_ssh` | Netmiko |
+| Tplink | `tplink_jetstream_ssh` | Netmiko |
+| Ubiquiti | `ubiquiti_edge_ssh` | Netmiko |
+| Ubiquiti | `ubiquiti_edgerouter_ssh` | Netmiko |
+| Ubiquiti | `ubiquiti_edgeswitch_ssh` | Netmiko |
+| Ubiquiti | `ubiquiti_unifiswitch_ssh` | Netmiko |
+| Vertiv | `vertiv_mph_ssh` | Netmiko |
+| Vyatta | `vyatta_vyos_ssh` | Netmiko |
+| Vyos | `vyos_ssh` | Netmiko |
+| Watchguard | `watchguard_fireware_ssh` | Netmiko |
+| Yamaha | `yamaha_ssh` | Netmiko |
+| ZTE (中兴) | `zte_zxros_ssh` | Netmiko |
+| Zyxel | `zyxel_os_ssh` | Netmiko |
+
+## Telnet Supported Devices
+
+| Platform | Device Type | Source |
+|----------|-------------|--------|
+| Adtran | `adtran_os_telnet` | Netmiko |
+| Apresia | `apresia_aeos_telnet` | Netmiko |
+| Arista | `arista_eos_telnet` | Netmiko |
+| Aruba | `aruba_procurve_telnet` | Netmiko |
+| Audiocode | `audiocode_66_telnet` | Netmiko |
+| Audiocode | `audiocode_72_telnet` | Netmiko |
+| Audiocode | `audiocode_shell_telnet` | Netmiko |
+| Bintec | `bintec_boss_telnet` | Netmiko |
+| Brocade | `brocade_fastiron_telnet` | Netmiko |
+| Brocade | `brocade_netiron_telnet` | Netmiko |
+| Calix | `calix_b6_telnet` | Netmiko |
+| Centec | `centec_os_telnet` | Netmiko |
+| Ciena | `ciena_saos_telnet` | Netmiko |
+| Cisco | `cisco_ios_telnet` | Netmiko |
+| Cisco | `cisco_nxos_telnet` | Netmiko |
+| Cisco | `cisco_s200_telnet` | Netmiko |
+| Cisco | `cisco_s300_telnet` | Netmiko |
+| Cisco | `cisco_xr_telnet` | Netmiko |
+| Dell | `dell_dnos6_telnet` | Netmiko |
+| Dell | `dell_powerconnect_telnet` | Netmiko |
+| Dlink | `dlink_ds_telnet` | Netmiko |
+| Extreme | `extreme_exos_telnet` | Netmiko |
+| Extreme | `extreme_netiron_telnet` | Netmiko |
+| Extreme | `extreme_telnet` | Netmiko |
+| Fiberstore | `fiberstore_fsosv2_telnet` | Netmiko |
+| Generic | `generic_telnet` | Netmiko |
+| Generic | `generic_termserver_telnet` | Netmiko |
+| Genexis | `genexis_solt33_telnet` | Netmiko |
+| HP | `hp_comware_telnet` | Netmiko |
+| HP | `hp_procurve_telnet` | Netmiko |
+| Huawei | `huawei_olt_telnet` | Netmiko |
+| Huawei | `huawei_telnet` | Netmiko |
+| Huawei | `gns3_huawei_telnet_ce` | Custom ✨ (GNS3) |
+| Infinera | `infinera_packet_telnet` | Netmiko |
+| Ipinfusion | `ipinfusion_ocnos_telnet` | Netmiko |
+| Juniper | `juniper_junos_telnet` | Netmiko |
+| Maipu (迈普) | `maipu_telnet` | Netmiko |
+| Nec | `nec_ix_telnet` | Netmiko |
+| Nokia | `nokia_sros_telnet` | Netmiko |
+| Oneaccess | `oneaccess_oneos_telnet` | Netmiko |
+| Optilink | `optilink_eolt11444_telnet` | Netmiko |
+| Optilink | `optilink_eolt9702_telnet` | Netmiko |
+| Palo Alto | `paloalto_panos_telnet` | Netmiko |
+| Rad | `rad_etx_telnet` | Netmiko |
+| Raisecom | `raisecom_telnet` | Netmiko |
+| Ruckus | `ruckus_fastiron_telnet` | Netmiko |
+| Ruijie (锐捷) | `ruijie_os_telnet` | Netmiko |
+| Ruijie (锐捷) | `gns3_ruijie_telnet` | Custom ✨ (GNS3 Enhanced) |
+| Supermicro | `supermicro_smis_telnet` | Netmiko |
+| VPCS | `gns3_vpcs_telnet` | Custom ✨ (GNS3 VPCS Simulator) |
+| Telcosystems | `telcosystems_binos_telnet` | Netmiko |
+| Teldat | `teldat_cit_telnet` | Netmiko |
+| Tplink | `tplink_jetstream_telnet` | Netmiko |
+| Yamaha | `yamaha_telnet` | Netmiko |
+| ZTE (中兴) | `zte_zxros_telnet` | Netmiko |
+
+---
+
+*This document was generated automatically by the Netmiko device list script.*

docs/gns3-copilot/roadmap/aiops-fault-injection-testing-pipeline-roadmap.md

@@ -0,0 +1,280 @@
+<!--
+SPDX-License-Identifier: CC-BY-SA-4.0
+See LICENSE file for licensing information.
+-->
+
+> This document is a roadmap/planning document. The described features have not been implemented yet.
+
+# AIOps Fault Injection Testing Pipeline — Roadmap
+
+## Overview
+
+Build a realistic testing pipeline that duplicates the company's production network architecture into GNS3, then systematically injects network faults using the AI Copilot's fault injection capabilities to validate and train the AIOps module before production deployment.
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                      AIOps Testing Pipeline                     │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  ┌──────────────┐    ┌──────────────┐    ┌──────────────────┐   │
+│  │  Network      │    │  Fault       │    │  AIOps           │   │
+│  │  Duplication  │───▶│  Injection   │───▶│  Validation      │   │
+│  │  (Phase 1)    │    │  (Phase 2)   │    │  (Phase 3)       │   │
+│  └──────────────┘    └──────────────┘    └──────────────────┘   │
+│         │                   │                      │            │
+│         ▼                   ▼                      ▼            │
+│  ┌──────────────┐    ┌──────────────┐    ┌──────────────────┐   │
+│  │ GNS3 Network  │    │ Fault        │    │ Results &        │   │
+│  │ Replica       │    │ Scenarios    │    │ Reporting        │   │
+│  └──────────────┘    └──────────────┘    └──────────────────┘   │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Core Concept
+
+1. **Duplicate** the company's production network architecture into a GNS3 simulation environment
+2. **Select** a set of fault types to test (OSPF, BGP, VxLAN, STP, packet filter, etc.)
+3. **Inject** faults automatically using the AI Copilot's fault injection capabilities
+4. **Validate** whether the AIOps module correctly identifies and reports each fault
+5. **Loop** through all selected fault scenarios, building a comprehensive test matrix
+6. **Train** the AIOps module on results to improve accuracy before production deployment
+
+## Phase 1: Network Architecture Duplication
+
+### Goal
+
+Create a high-fidelity replica of the company production network in GNS3.
+
+### Key Tasks
+
+- [ ] **Topology Mapping**: Document production network topology (devices, links, protocols)
+- [ ] **Device Selection**: Map production devices to GNS3-compatible images (Cisco IOSv, XRv, Juniper vSRX, etc.)
+- [ ] **Configuration Extraction**: Export sanitized production configs (remove passwords, public IPs, sensitive data)
+- [ ] **GNS3 Deployment**: Build the network in GNS3 with accurate device placement and links
+- [ ] **Config Replication**: Apply adapted configurations to GNS3 devices
+- [ ] **Connectivity Validation**: Verify OSPF/BGP adjacencies, VLANs, VRFs, and end-to-end reachability
+- [ ] **Baseline Capture**: Record normal operation metrics (CPU, memory, interface counters, routing tables)
+
+### Considerations
+
+- Sanitize all production configurations before importing into GNS3
+- Use environment-specific IP addressing where necessary (loopbacks, management)
+- Document all deviations from production for traceability
+
+## Phase 2: Fault Injection Pipeline
+
+### Goal
+
+Systematically inject network faults and validate AIOps detection using the existing AI Copilot fault injection infrastructure.
+
+### Components
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│                     Fault Injection Pipeline                      │
+├──────────────────────────────────────────────────────────────────┤
+│                                                                  │
+│  ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────────┐  │
+│  │ Scenario │   │ Inject   │   │ AIOps    │   │ Record       │  │
+│  │ Selector │──▶│ Fault    │──▶│ Validate │──▶│ & Report     │  │
+│  └──────────┘   └──────────┘   └──────────┘   └──────────────┘  │
+│       │              │              │               │           │
+│       │              │              │               │           │
+│       └──────────────┴──────────────┴───────────────┘           │
+│                           │                                      │
+│                           ▼                                      │
+│                    Loop until all scenarios tested                │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+### 2.1 Scenario Selector
+
+- Read fault scenarios from the GNS3-Skills repository
+- Support filtering by:
+  - Protocol (OSPF, BGP, VxLAN, STP, VLAN, etc.)
+  - Severity (critical, high, medium, low)
+  - Difficulty (beginner, intermediate, advanced)
+- Track which scenarios have been tested
+- Randomize selection order to avoid bias
+- Exclude previously tested scenarios
+
+### 2.2 Fault Injection
+
+- Use existing `manage_gns3_packet_filter` tool for network-level faults
+- Use existing `execute_multiple_device_config_commands` for configuration faults
+- Use existing `InjectionSkillsTool` to query and select appropriate faults
+- Support combined faults (multiple simultaneous issues)
+- Auto-recovery between scenarios (restore baseline state)
+
+### 2.3 AIOps Validation
+
+- Feed network state (after fault injection) to the AIOps module
+- Record AIOps diagnosis output
+- Compare AIOps results against expected fault definition:
+  - **Correct identification**: AIOps names the exact fault
+  - **Partial identification**: AIOps identifies related symptoms but not root cause
+  - **Missed**: AIOps fails to detect any issue
+  - **False positive**: AIOps reports a fault that doesn't exist
+
+### 2.4 Test Execution Flow
+
+```
+1. Reset network to clean baseline state
+2. Select next untested fault scenario
+3. Inject the fault into the GNS3 network
+4. Wait for convergence (configurable delay)
+5. Query AIOps module for diagnosis
+6. Compare AIOps output with expected fault definition
+7. Record result (pass/fail/partial)
+8. Restore network to baseline
+9. Repeat from step 2 until all scenarios completed
+```
+
+## Phase 3: Traffic Injection (Enhanced Realism)
+
+### Goal
+
+Add realistic network traffic to the GNS3 simulation so that AIOps has real telemetry data to analyze, rather than a static network.
+
+### Approaches
+
+#### 3.1 Traffic Generators in GNS3
+
+- Deploy traffic generator appliances in GNS3 (e.g., TRex, Ostinato, Scapy on Linux nodes)
+- Generate realistic traffic patterns:
+  - VoIP/RTP streams
+  - HTTP/HTTPS web traffic
+  - Database replication
+  - Routing protocol updates (OSPF hellos, BGP keepalives)
+  - ICMP monitoring traffic
+
+#### 3.2 tcpreplay with Captured Traffic
+
+- Capture real production traffic (sanitized)
+- Use `tcpreplay` to replay traffic through the GNS3 network
+- More realistic than synthetic traffic generators
+
+#### 3.3 Integration with Network Monitoring
+
+- Feed simulated device telemetry (SNMP, syslog, NetFlow) to the AIOps module
+- Enable AIOps to analyze real-time telemetry during fault conditions
+- Validate that AIOps can distinguish between traffic anomalies and actual faults
+
+## Success Metrics
+
+| Metric | Target | Measurement Method |
+|--------|--------|-------------------|
+| Fault detection rate | >95% | AIOps correctly identifies injected faults |
+| False positive rate | <5% | AIOps reports fault when none exists |
+| Time to detection | <30s | Duration from injection to AIOps alert |
+| Coverage | >80% of defined scenarios | Percentage of scenarios tested |
+| Accuracy improvement | Measurable per cycle | Compare pass rates across test cycles |
+
+## Technical Architecture
+
+```
+┌────────────────────────────────────────────────────────────────────┐
+│                     Test Orchestrator                               │
+│  ┌──────────────────────────────────────────────────────────────┐   │
+│  │  Test Runner (Python)                                        │   │
+│  │  - Scenario selection & scheduling                            │   │
+│  │  - Fault injection coordination                               │   │
+│  │  - AIOps query & result collection                            │   │
+│  │  - Report generation                                          │   │
+│  └──────────┬────────────────────────────────────────────┬───────┘   │
+│             │                                            │           │
+│             ▼                                            ▼           │
+│  ┌────────────────────┐                    ┌────────────────────┐   │
+│  │  GNS3 Controller    │                    │  AIOps Module      │   │
+│  │  (gns3-server)      │                    │                    │   │
+│  │  - Network mgmt     │                    │  - Fault diagnosis │   │
+│  │  - Fault injection  │                    │  - Alert detection │   │
+│  │  - State queries    │                    │  - Root cause      │   │
+│  └────────────────────┘                    └────────────────────┘   │
+│             │                                                        │
+│             ▼                                                        │
+│  ┌────────────────────┐                                              │
+│  │  GNS3 Network      │                                              │
+│  │  Replica           │                                              │
+│  │  - Devices         │                                              │
+│  │  - Traffic         │                                              │
+│  │  - Telemetry       │                                              │
+│  └────────────────────┘                                              │
+└────────────────────────────────────────────────────────────────────┘
+```
+
+## Reporting
+
+Each test cycle produces:
+
+- **Summary report**: Pass/fail rates, coverage, trends
+- **Detailed per-scenario report**: Injection details, AIOps response, comparison
+- **Regression tracker**: Which scenarios regressed since last cycle
+- **Accuracy trend**: Improvement or degradation over time
+
+### Example Report Entry
+
+```yaml
+test_cycle: 7
+date: "2026-06-01"
+scenarios_planned: 20
+scenarios_completed: 18
+failed_injections: 1
+skipped: 1
+results:
+  - scenario: ospf_hello_dead_mismatch
+    protocol: ospf
+    severity: major
+    injection_method: device_config
+    target_device: R1
+    aiops_detection: true
+    aiops_diagnosis: "OSPF Hello/Dead interval mismatch between R1 and R2"
+    detection_latency_ms: 12000
+    match: exact
+  - scenario: packet_loss_heavy
+    protocol: performance
+    severity: high
+    injection_method: packet_filter
+    target_link: "R1 ↔ R2 (ethernet)"
+    aiops_detection: true
+    aiops_diagnosis: "High packet loss detected on link R1-R2"
+    detection_latency_ms: 45000
+    match: partial
+```
+
+## Dependencies
+
+- [ ] GNS3 network replica ready and validated
+- [ ] AI Copilot fault injection tools operational
+- [ ] AIOps module query interface available
+- [ ] Traffic generation tools deployed (for Phase 3)
+- [ ] Test orchestrator framework (to be built)
+- [ ] Result database and reporting system
+
+## Timeline
+
+| Phase | Duration | Deliverable |
+|-------|----------|-------------|
+| P1: Network Duplication | 2-4 weeks | GNS3 replica of production network |
+| P2: Fault Injection Pipeline | 2-3 weeks | Automated test runner + first results |
+| P3: Traffic Injection | 2-4 weeks | Realistic traffic simulation integrated |
+
+## Status
+
+- [ ] P1: Network architecture duplication
+  - [ ] Topology mapping documented
+  - [ ] Device configurations sanitized and adapted
+  - [ ] GNS3 replica deployed
+  - [ ] Baseline connectivity verified
+- [ ] P2: Fault injection pipeline
+  - [ ] Scenario selection framework
+  - [ ] Automated fault injection
+  - [ ] AIOps validation interface
+  - [ ] Report generation
+  - [ ] Loop/retry mechanism
+- [ ] P3: Traffic injection
+  - [ ] Traffic generator deployment
+  - [ ] Traffic pattern library
+  - [ ] AIOps telemetry integration
+

docs/gns3-copilot/roadmap/injection-fault-tracking-roadmap.md

@@ -0,0 +1,64 @@
+<!--
+SPDX-License-Identifier: CC-BY-SA-4.0
+See LICENSE file for licensing information.
+-->
+
+> This document is a roadmap/planning document. The described features have not been implemented yet.
+
+
+# Injection Fault Tracking — Roadmap
+
+## Problem
+
+When using the AI Copilot in troubleshooting injection mode across multiple chat sessions within the same project, there is no mechanism to prevent the same fault from being injected repeatedly. Each new session starts with a clean slate, unaware of what faults have already been used. This leads to:
+
+- Duplicate injection scenarios across different sessions
+- No visibility for instructors into which faults have been used
+- No record of which devices were affected or whether faults were resolved
+
+## Proposed Solution
+
+Track injected faults per chat session and feed the history into the LLM's system prompt as context, so the model actively avoids repeating scenarios.
+
+### 1. Storage
+
+The existing `chat_sessions` table has `metadata` and `stats` JSON columns. After each fault injection, the agent records:
+
+```json
+// stored in chat_session.metadata
+{
+    "injected_fault": {
+        "fault_type": "injection_ospf",
+        "issue_key": "ospf_hello_dead_mismatch",
+        "issue_name": "OSPF Hello/Dead Interval Mismatch",
+        "device": "R1",
+        "severity": "major",
+        "injected_at": "2026-05-11T23:00:00Z",
+        "resolved": false
+    }
+}
+```
+
+### 2. Context Injection
+
+When starting a new troubleshooting session, query all previous sessions for the project, filter by `copilot_mode = "troubleshooting_injection"`, extract `injected_fault` data, and inject a summary into the system prompt via a placeholder (similar to the existing `{{topology_info}}` mechanism):
+
+```
+Previously injected faults in this project:
+  1. OSPF Hello/Dead Interval Mismatch on R1 (2026-05-11) — resolved
+  2. BGP Route Reflector misconfiguration on R3 (2026-05-10) — resolved
+
+Select a fault that has NOT been used before.
+```
+
+### 3. Prompt Update
+
+The `troubleshooting_injection.md` prompt in the GNS3-Skills repository gains an `{{injection_history}}` placeholder, and the agent is instructed to choose a fault not in the history list.
+
+## Status
+
+- [ ] GNS3-Skills: add `{{injection_history}}` placeholder to `troubleshooting_injection.md`
+- [ ] gns3-server: implement injection fault recording in agent chat session flow
+- [ ] gns3-server: implement injection history query across sessions per project
+- [ ] gns3-server: inject history into system prompt via `context_manager.py`
+- [ ] gns3-server: add `exclude` parameter to `InjectionSkillsTool` for filtering used faults

docs/gns3-copilot/roadmap/rbac-user-isolation-roadmap.md

@@ -0,0 +1,621 @@
+# RBAC User Isolation Roadmap
+
+## Overview
+
+GNS3 3.0 ships with a complete RBAC framework (ACE + Role + Privilege models), but the user isolation layer is incomplete. Users can see resources they should not have access to because:
+
+- Resource creation does not auto-grant the creator an ACE
+- List endpoints return unfiltered results
+- Two GET endpoints have RBAC checks bypassed via FIXME
+
+**This document has been updated to reflect the implemented solution in `feature/simple-user-isolation` branch.**
+
+## Current State
+
+| Resource | Route Check | List Filtering | Auto-ACE on Create | ACE Cleanup on Delete |
+|---|---|---|---|---|
+| Project | `Project.Audit/Modify/Allocate` | **Implemented** — Three-step filtering | **Not needed** | Done |
+| Template | `Template.Audit` **FIXME** | None — all templates returned | **Missing** | Done |
+| Node | `Node.Audit/Modify/Allocate` | N/A (inherits project) | Inherits project | N/A |
+| Link | `Link.Audit/Modify/Allocate` | N/A (inherits project) | Inherits project | N/A |
+| Drawing | `Drawing.Audit/Modify/Allocate` | N/A (inherits project) | Inherits project | N/A |
+| Snapshot | `Snapshot.Audit/Allocate/Restore` | N/A (inherits project) | Inherits project | N/A |
+| Image | `Image.Audit/Allocate` | None — all images returned | **Missing** | Missing |
+| Compute | `Compute.Audit` **FIXME** | None — all computes returned | N/A (shared infra) | Done |
+| Appliance | `Appliance.Audit/Allocate` | None — all appliances returned | N/A (builtin) | N/A |
+| Symbol | `Symbol.Audit/Allocate` | None — all symbols returned | N/A (builtin) | N/A |
+
+## Implemented Solution: Project Isolation
+
+### Three-Step Permission Check Logic
+
+**Status**: ✅ Implemented in `feature/simple-user-isolation` branch
+
+```python
+# Step 1: ACE check - basic access permission
+# Get projects user has ACE for
+ace_projects = []
+for project in controller.projects.values():
+    project_path = f"/projects/{project.id}"
+    if await rbac_repo.check_user_has_privilege(current_user.user_id, project_path, "Project.Audit"):
+        ace_projects.append(project)
+
+# Step 2: Filter ace_projects by created_by - user's own projects
+# Project sharing is only available through resource pools
+user_projects = [p.asdict() for p in ace_projects if p.created_by == current_user.username]
+projects.extend(user_projects)
+
+# Step 3: Resource pool projects
+# Projects shared through resource pools
+user_pool_resources = await rbac_repo.get_user_pool_resources(current_user.user_id, "Project.Audit")
+project_ids_in_pools = [str(r.resource_id) for r in user_pool_resources if r.resource_type == "project"]
+pool_projects = [p.asdict() for p in controller.projects.values() if p.id in project_ids_in_pools]
+projects.extend(pool_projects)
+```
+
+### Key Design Principles
+
+1. **ACE for basic access control**: Controls whether user can access the system
+2. **created_by for user isolation**: Controls which specific resources user can access
+3. **Resource pools for project sharing**: The only mechanism for sharing projects between users
+4. **No direct ACE sharing**: Users cannot configure ACE directly on specific projects to share them
+
+### Advantages of This Approach
+
+- **Fault tolerance**: Even with broad ACE configuration (`path: "/" + propagate: true`), user isolation remains effective
+- **Clear separation**: Basic access, data ownership, and team sharing are clearly separated
+- **Simple mechanism**: No complex auto-ACE or seen_project_ids tracking required
+- **Performance**: Leverages existing created_by field, no schema changes needed
+
+## Updated Architecture
+
+```mermaid
+graph TD
+    subgraph Client
+        WebUI
+        CLI
+    end
+    
+    subgraph "Controller API"
+        Auth[get_current_active_user]
+        Routes[Resource Routes]
+        ACE_Check[Step 1: ACE Check]
+        Owner_Filter[Step 2: Filter by created_by]
+        Pool_Check[Step 3: Resource Pools]
+    end
+    
+    subgraph "RBAC Engine"
+        ACE[(ACE table)]
+        Role[(Role table)]
+        Privilege[(Privilege table)]
+        Checker[check_user_has_privilege]
+    end
+    
+    WebUI --> Auth
+    CLI --> Auth
+    Auth --> Routes
+    Routes --> ACE_Check
+    ACE_Check --> Checker
+    ACE_Check --> Owner_Filter
+    Owner_Filter --> Pool_Check
+    Pool_Check --> Checker
+    Checker --> ACE
+    Checker --> Role
+    Role --> Privilege
+```
+
+## Business Process
+
+### Project listing with three-step filtering
+
+```mermaid
+sequenceDiagram
+    actor U as User
+    participant API as GET /projects
+    participant Controller as Controller
+    participant RBAC as RBAC Engine
+    
+    U->>API: List projects
+    API->>API: get_current_active_user (not superadmin)
+    
+    API->>RBAC: Step 1: ACE check on each project
+    loop Each project
+        RBAC-->>API: ACE results
+    end
+    
+    API->>API: Step 2: Filter by created_by
+    API-->>U: User's own projects
+    
+    API->>RBAC: Step 3: Resource pool projects
+    RBAC-->>API: Pool projects
+    
+    API-->>U: Combined list (own + pool)
+```
+
+## Updated Phased Plan
+
+### ✅ Phase 1 — MVP: Project isolation (COMPLETED)
+
+**Goal**: Users only see projects they created or were granted access to through resource pools.
+
+| Task | Files | Status | Detail |
+|---|---|---|---|
+| Fix project list filtering | `projects.py` — `get_projects()` | ✅ **Implemented** | Three-step filtering: ACE check → created_by filter → resource pools |
+
+**Result**: 
+- ✅ Users can only see projects they created
+- ✅ Team collaboration through resource pools works
+- ✅ Fault tolerance: Works correctly even with broad ACE configurations
+- ✅ No schema changes required
+- ✅ ~30 lines changed
+
+### Phase 2 — Template isolation
+
+**Goal**: Users see their own templates + builtin templates only.
+
+| Task | Files | Detail |
+|---|---|---|
+| Apply same pattern to templates | `templates.py` — `get_templates()` | Use same three-step filtering as projects |
+| Uncomment `Template.Audit` | `templates.py` | Restore `has_privilege("Template.Audit")` checks |
+
+**Dependency**: Web UI must handle 403 from `GET /templates/{id}`. Mitigation: keep builtin templates unconditionally visible so the UI always has data.
+
+### Phase 3 — Image isolation (optional)
+
+**Goal**: Users see only images they uploaded.
+
+| Task | Files |
+|---|---|
+| Apply same pattern to images | `images.py` — `get_images()` |
+| Fix image list filtering | `images.py` |
+| ACE cleanup on delete | `images.py` — `delete_image()` |
+
+### Phase 4 — Default ACE for "Users" group (optional)
+
+**Goal**: Users in "Users" group can create/list resources without admin ACE intervention.
+
+| Task | Detail |
+|---|---|
+| Default ACE on `/projects` | Grant "Users" group → User role → `/projects` (propagate=False) |
+| Default ACE on `/templates` | Grant "Users" group → User role → `/templates` (propagate=False) |
+
+## API Endpoints Changed
+
+### Phase 1 (Implemented)
+
+| Method | Path | Change |
+|---|---|---|
+| `GET` | `/v3/projects` | Three-step filtering: ACE → created_by → resource pools |
+
+### Phase 2 (Planned)
+
+| Method | Path | Change |
+|---|---|---|
+| `GET` | `/v3/templates` | Apply same three-step filtering |
+| `GET` | `/v3/templates/{id}` | Restore `Template.Audit` check |
+
+## Key Design Decisions
+
+1. **Project sharing through resource pools only**: Users cannot configure ACE directly to share specific projects. All sharing must go through resource pools. This prevents permission configuration chaos and maintains clear ownership semantics.
+
+2. **No auto-ACE required**: The three-step filtering logic works without needing automatic ACE creation on project creation. The created_by field provides sufficient ownership information.
+
+3. **Fault-tolerant to ACE configuration**: Even if administrators configure broad ACE permissions (like `path: "/" + propagate: true`), user isolation remains effective because Step 2 filters by created_by.
+
+4. **No DB migration required**: Uses existing ACE/role/privilege tables and created_by field. No schema changes needed.
+
+5. **Performance**: Project list filtering is O(n) where n is the total number of projects. Each project requires one ACE check. Acceptable for < 500 projects. Can optimize later with batch ACE queries if needed.
+
+## Updated References
+
+- **Implementation**: `gns3server/api/routes/controller/projects.py` (feature/simple-user-isolation branch)
+- **Discussion**: https://github.com/GNS3/gns3-server/discussions/1949
+- **RBAC models**: `gns3server/db/models/acl.py`, `roles.py`, `privileges.py`
+- **RBAC repository**: `gns3server/db/repositories/rbac.py`
+- **Auth dependency**: `gns3server/api/routes/controller/dependencies/authentication.py`
+- **RBAC dependency**: `gns3server/api/routes/controller/dependencies/rbac.py`
+- **Resource pools**: `gns3server/db/models/pools.py` and `gns3server/db/repositories/pools.py`
+
+## Implementation Notes
+
+### What Was Implemented
+
+The `feature/simple-user-isolation` branch implements a robust user isolation mechanism that:
+
+1. **Integrates with existing RBAC framework** without breaking changes
+2. **Leverages the created_by field** that already exists in the Project model
+3. **Uses three-step pipeline filtering** to avoid complex seen_project_ids tracking
+4. **Supports team collaboration** through existing resource pool functionality
+5. **Is fault-tolerant to ACE misconfiguration** - broad ACE permissions don't break user isolation
+
+### What Was Not Implemented
+
+The original roadmap's Phase 1 included auto-ACE creation on project creation. This was determined to be unnecessary because:
+
+- The three-step filtering logic achieves user isolation without auto-ACE
+- Auto-ACE would add complexity without significant benefit
+- Project sharing through resource pools is cleaner than direct ACE configuration
+
+### Future Work
+
+The same three-step filtering pattern can be applied to:
+- **Templates**: Replace the FIXME comment with proper filtering logic
+- **Images**: Apply the same pattern for user image isolation
+- **Other resources**: Extend the pattern as needed
+
+This implementation provides a solid foundation for user isolation in GNS3 3.0+ while maintaining compatibility with the existing RBAC framework.
+
+## Phase 5 — ACE Architecture Refactoring (Future)
+
+**Goal**: Improve ACE manageability by supporting multiple paths and resource pools in a single ACE entry.
+
+### Current Problem
+
+With the current design where one ACE = one path:
+- **ACE explosion**: 5 user groups × 10 resource pools = 50 ACE entries
+- **Management complexity**: Difficult to maintain and understand ACE purpose
+- **Performance impact**: Permission checking must iterate through many ACE entries
+
+### Proposed Solution
+
+Redesign ACE structure to support multiple paths and resource pools in a single ACE entry:
+
+```json
+{
+  "name": "Development Team Access",
+  "description": "Full access for development team",
+  "ace_type": "group",
+  "group_id": "...",
+  "role_id": "...",
+  "paths": ["/projects", "/templates", "/images"],
+  "resource_pools": ["pool-id-1", "pool-id-2"],
+  "propagate": true,
+  "allowed": true
+}
+```
+
+### Database Changes Required
+
+1. **Add name and description to ACE table**:
+```sql
+ALTER TABLE acl ADD COLUMN name VARCHAR;
+ALTER TABLE acl ADD COLUMN description TEXT;
+```
+
+2. **Create association tables**:
+```sql
+CREATE TABLE ace_paths (
+    ace_id UUID REFERENCES acl(ace_id),
+    path VARCHAR,
+    PRIMARY KEY (ace_id, path)
+);
+
+CREATE TABLE ace_pools (
+    ace_id UUID REFERENCES acl(ace_id),
+    resource_pool_id UUID REFERENCES resource_pools(resource_pool_id),
+    PRIMARY KEY (ace_id, resource_pool_id)
+);
+```
+
+3. **Update permission checking logic** to check both paths and resource_pools tables
+
+### Benefits
+
+- ✅ **Reduced ACE entries**: One ACE covers multiple related paths/pools
+- ✅ **Better organization**: Logical grouping with clear names and descriptions
+- ✅ **Easier management**: Edit one ACE instead of multiple related entries
+- ✅ **Improved performance**: Fewer ACE entries to check during permission validation
+
+### Implementation Considerations
+
+- **Migration path**: Need to migrate existing single-path ACEs to new structure
+- **Backward compatibility**: API should support both old and new formats during transition
+- **UI updates**: ACE management interface needs to support multi-path/pool selection
+- **Permission checking**: Update `check_user_has_privilege` to check association tables
+
+## Phase 6 — Frontend Permission Query API (Future)
+
+**Goal**: Provide an API endpoint for the Web UI to query the current user's permissions, enabling dynamic UI rendering based on role and ACE configuration.
+
+### Problem
+
+Currently the Web UI cannot determine what the authenticated user is allowed to see or do:
+
+- ❌ Users see menu items and buttons they don't have permission to use
+- ❌ Clicking a forbidden action results in a 403 error (unexpected UX)
+- ❌ No way to hide/show UI elements based on actual permissions
+
+### Proposed Solution
+
+Create a `GET /v3/me/permissions` endpoint that returns the current user's effective permissions:
+
+```json
+{
+  "user_id": "uuid",
+  "is_superadmin": false,
+  "permissions": [
+    {"path": "/projects", "privileges": ["Project.Audit", "Project.Allocate"]},
+    {"path": "/projects/{id}", "privileges": ["Project.Audit", "Project.Modify"]},
+    {"path": "/templates", "privileges": ["Template.Audit"]}
+  ],
+  "pools": [
+    {"path": "/pools/{id}", "name": "Team Projects", "privileges": ["Pool.Audit"]}
+  ]
+}
+```
+
+### Benefits
+
+- ✅ **Dynamic UI**: Frontend can hide inaccessible menus/buttons
+- ✅ **Better UX**: Users only see what they can actually use
+- ✅ **Reduced errors**: Fewer 403 responses from hidden operations
+- ✅ **Faster feedback**: Permission checks happen at render time, not request time
+
+### Dependencies
+
+- **Phase 5 (ACE refactoring)** may change how permissions are stored, which would affect this API's implementation
+
+## Phase 7 — Resource Pool Renaming (Future)
+
+**Goal**: Rename "Resource Pool" to a more descriptive name that better reflects its actual purpose.
+
+### Problem
+
+The current name "Resource Pool" is too generic and doesn't clearly convey its actual function:
+
+- ❌ **Ambiguous name**: "Resource Pool" could refer to compute pools, connection pools, etc.
+- ❌ **Unclear purpose**: Users don't understand it's primarily for sharing projects
+- ❌ **Discoverability**: Hard to find the right feature when looking for project sharing
+
+### Actual Function
+
+Resource pools in GNS3 are used for:
+- **Project sharing**: Allow users to access projects created by other users
+- **Team collaboration**: Enable team members to work on shared projects
+- **Access control**: Provide fine-grained permissions for project access through three-step filtering (ACE check → created_by filter → resource pools)
+
+### Proposed Name Options
+
+| Option | Pros | Cons |
+|--------|-------|-------|
+| **Project Pool** | More explicit, indicates it contains projects | Still uses "pool" terminology |
+| **Shared Projects** | Directly describes the function | Loses the "collection" concept |
+| **Team Projects** | Emphasizes collaboration use case | Doesn't cover non-team sharing scenarios |
+
+**Recommended**: **Project Pool** - strikes a balance between clarity and consistency with existing terminology.
+
+### Implementation Scope
+
+Renaming would require changes to:
+- Database tables: `resource_pools` → `project_pools`
+- API routes: `/v3/pools` → `/v3/project_pools`
+- Schema classes and field names throughout the codebase
+- All documentation and help text
+- Migration script to preserve existing data
+
+### Benefits
+
+- ✅ **Improved discoverability**: Users can easily find the project sharing feature
+- ✅ **Better onboarding**: New users understand the purpose without confusion
+- ✅ **Clearer API**: API endpoints and schemas more self-documenting
+
+### Implementation Considerations
+
+- **Breaking change**: Requires API version bump or backward compatibility layer
+- **Data migration**: Existing resource pools must be preserved during table rename
+- **Documentation updates**: All references in docs, tutorials, and API specs need updating
+- **UI changes**: Frontend labels and navigation menus need to match new terminology
+
+## Phase 8 — Per-User Project Namespace (Future)
+
+**Goal**: Allow project names to be unique per user instead of globally unique, enabling better user experience.
+
+### Current Problem
+
+Although Phase 1 implements user isolation (users only see projects they created or have access to through resource pools), project names remain globally unique:
+
+- ❌ **Naming conflicts**: Alice and Bob cannot both create a project named "My Project"
+- ❌ **Unnecessary restrictions**: Even though projects are isolated, users must coordinate globally unique names
+- ❌ **Poor user experience**: Users get confusing error messages when trying to use common names like "Test Project"
+
+### Proposed Solution
+
+Change project uniqueness from global to per-user:
+
+**Current:**
+```sql
+UNIQUE(name)  -- Project names must be globally unique
+```
+
+**Proposed:**
+```sql
+UNIQUE(user_id, name)  -- Project names unique per user
+```
+
+### Benefits
+
+- ✅ **Better UX**: Users can name projects whatever they want without worrying about global conflicts
+- ✅ **Natural naming**: Common names like "Test Project" or "Demo" can coexist between users
+- ✅ **No coordination needed**: Teams don't need to maintain a shared project naming registry
+- ✅ **Consistent isolation**: Projects are isolated both in visibility AND naming
+
+### Implementation Scope
+
+Changes required:
+- **Database schema**: Modify Project table unique constraint from `(name)` to `(user_id, name)`
+- **Migration script**: Handle existing projects with conflicting names
+- **API validation**: Update project creation validation logic
+- **Frontend**: Remove global name uniqueness checks from UI
+
+### Migration Considerations
+
+**Handling existing name conflicts:**
+If the database already has projects with the same name but different users:
+- Option 1: Keep existing names, only enforce uniqueness for new projects
+- Option 2: Append suffixes to duplicates (e.g., "My Project (alice)", "My Project (bob)")
+- Option 3: Require admin resolution for conflicts before enabling new constraint
+
+**Recommended**: Option 1 (grandfather existing projects) for minimal disruption.
+
+### Dependencies
+
+- **Phase 1 (User isolation)**: Must be completed first
+- Database migration required to modify unique constraint
+
+## Phase 9 — User Self-Registration (Future)
+
+**Goal**: Allow users to register their own accounts without requiring manual admin creation.
+
+### Current State
+
+Currently, user accounts can only be created by administrators or through direct database operations:
+- ❌ **Admin burden**: Every new user requires manual account creation
+- ❌ **Poor scalability**: Not suitable for public deployments or large organizations
+- ❌ **Friction**: Users cannot immediately start using the system
+
+### Proposed Features
+
+**Self-Registration Flow:**
+1. User provides email, username, and password
+2. System validates input and creates account
+3. Optional email verification to confirm email address
+4. Account created with default role (typically "User" role)
+5. User can immediately log in and start creating projects
+
+**Email Verification (Optional):**
+- Send verification email with confirmation link/code
+- Verify email address before granting full access
+- Prevent spam account creation
+- Require SMTP server configuration
+
+### Implementation Components
+
+1. **New API endpoint**: `POST /v3/access/register` (public, no authentication required)
+2. **Email service**: Integration with SMTP server for sending emails
+3. **Configuration**: SMTP settings (host, port, credentials, encryption)
+4. **Rate limiting**: Prevent abuse of self-registration
+5. **Captcha integration**: Optional bot protection
+
+### Configuration
+
+```yaml
+Server:
+  email:
+    enabled: true
+    smtp_host: smtp.example.com
+    smtp_port: 587
+    smtp_username: noreply@example.com
+    smtp_password: secret
+    use_tls: true
+  registration:
+    require_email_verification: true
+    default_role: "User"
+    allow_public_registration: true
+```
+
+### Security Considerations
+
+- ✅ **Rate limiting**: Prevent spam account creation
+- ✅ **Email verification**: Confirm email ownership
+- ✅ **Default permissions**: New users get limited default role
+- ✅ **Admin approval** (optional): Require admin approval before account activation
+- ❌ **Superadmin creation**: Never allow self-registration as superadmin
+
+### Dependencies
+
+- **Phase 10 (Email service)**: SMTP integration required for email verification
+
+## Phase 10 — Email Service Integration (Future)
+
+**Goal**: Implement email sending capability for notifications, verification, and alerts.
+
+### Use Cases
+
+1. **User registration**: Email verification links/codes
+2. **Password reset**: Secure password reset emails
+3. **System alerts**: Error notifications, system updates
+4. **Project sharing**: Notify users when projects are shared via resource pools
+5. **Usage reports**: Periodic usage summaries or quota alerts
+
+### Proposed Implementation
+
+**Email Service Architecture:**
+- Abstract email service interface
+- Support multiple email providers (SMTP, SendGrid, AWS SES, etc.)
+- Email templates with Jinja2 for customization
+- Async email sending to avoid blocking API responses
+- Email queue for retry logic on failures
+
+**Email Templates:**
+- Registration verification
+- Password reset
+- Project shared notification
+- System alerts
+- Usage reports
+
+**API Endpoints:**
+```python
+# Configuration (admin only)
+POST /v3/access/config/email
+GET /v3/access/config/email
+PUT /v3/access/config/email
+
+# Test email (admin only)
+POST /v3/access/config/email/test
+
+# Password reset (public)
+POST /v3/access/users/password/reset/request
+POST /v3/access/users/password/reset/confirm
+
+# Email verification (public)
+POST /v3/access/users/verify/email
+POST /v3/access/users/verify/confirm
+```
+
+### Database Schema
+
+New table for email tracking:
+```sql
+CREATE TABLE email_verification_tokens (
+    token_id UUID PRIMARY KEY,
+    user_id UUID REFERENCES users(user_id) ON DELETE CASCADE,
+    token VARCHAR(255),  # Verification code
+    purpose VARCHAR(50),  # 'registration', 'password_reset', etc.
+    expires_at DATETIME,
+    created_at DATETIME,
+    used BOOLEAN DEFAULT FALSE
+);
+```
+
+### Configuration
+
+```yaml
+Server:
+  email:
+    enabled: true
+    provider: "smtp"  # or "sendgrid", "aws_ses", etc.
+    from_address: "noreply@example.com"
+    from_name: "GNS3 Server"
+    reply_to: "support@example.com"
+    smtp:
+      host: smtp.example.com
+      port: 587
+      username: noreply@example.com
+      password: encrypted_password
+      use_tls: true
+    templates_dir: /etc/gns3/email_templates
+```
+
+### Security Considerations
+
+- ✅ **Encrypted credentials**: SMTP passwords stored encrypted in database
+- ✅ **Token expiration**: Verification tokens expire after configurable time
+- ✅ **Rate limiting**: Prevent email spamming
+- ✅ **Async sending**: Don't block API responses on email operations
+- ✅ **Retry logic**: Handle temporary email service failures
+- ✅ **Privacy**: Don't expose user information in error messages
+
+### Dependencies
+
+- **Phase 9 (Self-registration)**: User self-registration requires email verification
+- Encryption utilities for storing SMTP credentials securely

docs/gns3-copilot/roadmap/server-settings-api-roadmap.md

@@ -0,0 +1,67 @@
+<!--
+SPDX-License-Identifier: CC-BY-SA-4.0
+See LICENSE file for licensing information.
+-->
+
+> This document is a roadmap/planning document. The described features have not been implemented yet.
+
+
+# Server Settings REST API — Roadmap
+
+## Problem
+
+Currently, `gns3_server.conf` can only be modified by directly editing the file on disk. There is no REST API endpoint to read or write server configuration, which prevents the Web UI from offering a settings page for server parameters.
+
+## Proposed API
+
+```
+GET  /v3/settings  →  Return all current server settings
+PUT  /v3/settings  →  Update and persist server settings
+```
+
+### Implementation Plan
+
+**1. Add `save_config()` to `Config` class** (`gns3server/config.py`)
+
+The `Config` class currently only reads configuration (via `read_config()` / `reload()`). A `save_config()` method is needed to serialize the in-memory `ServerConfig` pydantic model back to INI format and write it to disk.
+
+Serialization details:
+- `bool` → `"True"` / `"False"` (configparser convention)
+- `SecretStr` → `get_secret_value()`
+- `Enum` → `.value`
+- `List[str]` → semi-colon for `additional_images_paths`, comma for `allowed_interfaces`
+- `None` → skip
+
+**2. Add a settings getter/setter** to `Config` to allow programmatic updates to the in-memory settings.
+
+**3. New route file** (`gns3server/api/routes/controller/settings.py`):
+
+- `GET /v3/settings` — returns the full `ServerConfig` as JSON (pydantic automatically masks `SecretStr` fields as `"********"`)
+- `PUT /v3/settings` — accepts `ServerConfig`, merges existing secrets when placeholder values (`"********"`) are submitted, calls `save_config()`, and triggers runtime config update callbacks
+
+Both endpoints require `get_current_active_user` for authentication.
+
+**4. Register the new router** in `gns3server/api/routes/controller/__init__.py` under the `/settings` prefix.
+
+### Security
+
+- All settings endpoints require admin authentication (`get_current_active_user`)
+- `SecretStr` fields (`compute_password`, `default_admin_password`, `jwt_secret_key`) are masked in responses
+- On write, unchanged secrets are preserved via placeholder detection
+
+### Related Files
+
+| File | Role |
+|------|------|
+| `gns3server/config.py` | Config singleton with `read_config()` / `reload()` |
+| `gns3server/schemas/config.py` | `ServerConfig` pydantic model with all 9 sub-models |
+| `gns3server/api/routes/controller/__init__.py` | Controller router mounting |
+| `gns3server/controller/__init__.py` | `Controller._update_config()` for runtime credential sync |
+
+## Status
+
+- [ ] gns3server/config.py: add `save_config()` method
+- [ ] gns3server/config.py: add settings getter/setter
+- [ ] gns3server/api/routes/controller/settings.py: new route file with GET and PUT endpoints
+- [ ] gns3server/api/routes/controller/__init__.py: register settings router under `/settings`
+- [ ] gns3server/api/routes/controller/controller.py: add notification emission on config change

docs/gns3-copilot/roadmap/skills-editor-api-roadmap.md

@@ -0,0 +1,318 @@
+<!--
+SPDX-License-Identifier: CC-BY-SA-4.0
+See LICENSE file for licensing information.
+-->
+
+> This documentation is organized by AI with reference to actual code. AI can make mistakes — please verify against the source code when in doubt.
+
+
+# Skills Editor API
+
+## Overview
+
+A management API that allows the Web UI to browse, edit, save, and contribute skill files (prompts, fault injection, device skills, packet analysis protocols) back to the upstream GNS3-Skills repository via Pull Requests.
+
+Today, skills are read-only from the server's perspective — the only management endpoint is `POST /copilot/reload/skills` for hot-reloading. This API adds full CRUD operations on the local skills repository plus Git commit/push/PR workflows.
+
+## Architecture
+
+```mermaid
+graph TD
+    subgraph "Web UI"
+        UI[Skills Editor Page]
+    end
+
+    subgraph "GNS3 Server API"
+        API[skills_editor.py<br/>/copilot/skills/*]
+        FM[SkillsFileManager]
+        SM[SkillsManager]
+    end
+
+    subgraph "Local Git Repo"
+        INJ[injection/*.yaml]
+        DEV[device/*.yaml]
+        PA[packet_analysis/*.yaml]
+        PRM[prompts/*.md]
+        CFG[config/*.txt]
+    end
+
+    subgraph "Remote"
+        GH[GitHub API<br/>Pull Requests]
+        REPO[gns3/gns3-skills]
+    end
+
+    UI -->|CRUD + PR| API
+    API --> FM
+    FM -->|file read/write| INJ
+    FM -->|file read/write| DEV
+    FM -->|file read/write| PA
+    FM -->|file read/write| PRM
+    FM -->|file read/write| CFG
+    FM -->|git commit/push| REPO
+    FM -->|create PR| GH
+    SM -->|hot reload| INJ
+    SM -->|hot reload| DEV
+    SM -->|hot reload| PA
+    SM -->|hot reload| PRM
+```
+
+## Business Process
+
+### Edit and Contribute Flow
+
+```mermaid
+sequenceDiagram
+    participant UI as Web UI
+    participant API as Skills Editor API
+    participant FM as SkillsFileManager
+    participant Git as Local Git Repo
+    participant GH as GitHub
+
+    UI->>API: GET /copilot/skills
+    API-->>UI: List categories + file counts
+
+    UI->>API: GET /copilot/skills/injection
+    API-->>UI: List YAML files
+
+    UI->>API: GET /copilot/skills/injection/ospf_issues
+    API->>FM: read_file("injection", "ospf_issues")
+    FM-->>API: YAML content
+    API-->>UI: File content
+
+    UI->>API: PUT /copilot/skills/injection/ospf_issues<br/>{content: "..."}
+    API->>FM: write_file("injection", "ospf_issues", content)
+    FM->>Git: Write file to disk
+    FM-->>API: Success
+    API-->>UI: Updated
+
+    UI->>API: POST /copilot/skills/commit<br/>{message: "fix: update OSPF fault"}
+    API->>FM: commit_changes(message, files)
+    FM->>Git: git add + git commit
+    FM-->>API: Commit hash
+    API-->>UI: Committed
+
+    UI->>API: POST /copilot/skills/pull-request<br/>{title, body, branch}
+    API->>FM: create_pull_request(...)
+    FM->>Git: git push origin <branch>
+    FM->>GH: POST /repos/{owner}/{repo}/pulls
+    GH-->>FM: PR URL
+    FM-->>API: PR created
+    API-->>UI: PR URL
+
+    UI->>API: POST /copilot/skills/reload
+    API->>FM: Hot reload all registries
+    API-->>UI: Reloaded
+```
+
+## Valid Categories
+
+| Category | Directory | File Extension | Content |
+|----------|-----------|---------------|---------|
+| `prompts` | `prompts/` | `.md` | System prompts (teaching_assistant, lab_automation_assistant, etc.) |
+| `injection` | `injection/` | `.yaml` | Fault injection skill definitions (OSPF, BGP, VLAN, etc.) |
+| `device` | `device/` | `.yaml` | Device-specific command knowledge |
+| `packet_analysis` | `packet_analysis/` | `.yaml` | Protocol definitions for tshark-based analysis |
+| `config` | `config/` | `.txt` | Security and configuration files (forbidden_commands, etc.) |
+
+## API Endpoints
+
+All endpoints require **superadmin** authentication. Prefix: `/v3/copilot/skills`.
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/copilot/skills` | List all categories with file counts |
+| GET | `/copilot/skills/{category}` | List files in a category |
+| GET | `/copilot/skills/{category}/{filename}` | Read file content (without extension) |
+| POST | `/copilot/skills/{category}` | Create a new skill file |
+| PUT | `/copilot/skills/{category}/{filename}` | Update existing file content |
+| DELETE | `/copilot/skills/{category}/{filename}` | Delete a skill file |
+| GET | `/copilot/skills/status` | Git status (modified/untracked/deleted files) + repo info |
+| POST | `/copilot/skills/commit` | Stage and commit changes |
+| POST | `/copilot/skills/push` | Push a branch to remote |
+| POST | `/copilot/skills/pull-request` | Create a Pull Request (direct or via fork) |
+| POST | `/copilot/skills/reload` | Hot reload all skills into memory (replaces `/reload/skills`) |
+| POST | `/copilot/skills/rollback/{commit_hash}` | Rollback repository to a specific commit |
+
+### Response Examples
+
+**GET /copilot/skills** — List categories
+
+```json
+{
+  "categories": [
+    {"category": "injection", "file_count": 39, "path": "injection/"},
+    {"category": "device", "file_count": 2, "path": "device/"},
+    {"category": "packet_analysis", "file_count": 8, "path": "packet_analysis/"},
+    {"category": "prompts", "file_count": 4, "path": "prompts/"},
+    {"category": "config", "file_count": 1, "path": "config/"}
+  ],
+  "repository": {
+    "repo_url": "https://github.com/gns3/gns3-skills.git",
+    "branch": "main",
+    "current_version": "abc123def456...",
+    "is_dirty": false
+  }
+}
+```
+
+**GET /copilot/skills/injection** — List files in category
+
+```json
+{
+  "category": "injection",
+  "files": [
+    {"filename": "ospf_issues", "extension": ".yaml", "size": 4521, "last_modified": "2026-05-10T08:30:00Z"},
+    {"filename": "bgp_issues", "extension": ".yaml", "size": 3820, "last_modified": "2026-05-09T14:00:00Z"}
+  ]
+}
+```
+
+**GET /copilot/skills/injection/ospf_issues** — Read file content
+
+```json
+{
+  "category": "injection",
+  "filename": "ospf_issues",
+  "extension": ".yaml",
+  "content": "name: OSPF Fault Injection\n...\n",
+  "size": 4521,
+  "last_modified": "2026-05-10T08:30:00Z"
+}
+```
+
+**PUT /copilot/skills/injection/ospf_issues** — Update file
+
+```json
+{
+  "content": "name: OSPF Fault Injection\n..."
+}
+```
+
+Response:
+
+```json
+{
+  "category": "injection",
+  "filename": "ospf_issues",
+  "size": 4600,
+  "last_modified": "2026-05-12T10:00:00Z",
+  "status": "modified"
+}
+```
+
+**POST /copilot/skills/commit** — Commit changes
+
+Request:
+
+```json
+{
+  "message": "fix: update OSPF hello/dead interval fault descriptions",
+  "files": ["injection/ospf_issues.yaml"]
+}
+```
+
+Response:
+
+```json
+{
+  "success": true,
+  "commit_hash": "def456abc789...",
+  "message": "fix: update OSPF hello/dead interval fault descriptions",
+  "files_committed": 1
+}
+```
+
+**POST /copilot/skills/pull-request** — Create PR
+
+Request:
+
+```json
+{
+  "title": "Fix OSPF fault injection descriptions",
+  "body": "Updated OSPF hello/dead interval fault descriptions for clarity.",
+  "branch": "fix/ospf-descriptions",
+  "target_branch": "main",
+  "fork_url": "https://github.com/user/GNS3-Skills.git"
+}
+```
+
+Response:
+
+```json
+{
+  "success": true,
+  "pr_url": "https://github.com/gns3/gns3-skills/pull/42",
+  "pr_number": 42,
+  "branch": "fix/ospf-descriptions"
+}
+```
+
+**GET /copilot/skills/status** — Git status
+
+```json
+{
+  "current_version": "abc123def456...",
+  "branch": "main",
+  "is_dirty": true,
+  "modified": ["injection/ospf_issues.yaml"],
+  "untracked": [],
+  "deleted": [],
+  "staged": [],
+  "available_versions": [
+    {"hash": "abc123def456", "message": "Add MPLS fault scenarios", "author": "dev", "date": "2026-05-10T08:00:00Z"}
+  ]
+}
+```
+
+## Implementation Plan
+
+### New Files
+
+| File | Purpose |
+|------|---------|
+| `gns3server/agent/gns3_copilot/skills/file_manager.py` | `SkillsFileManager` class — file CRUD, git commit/push, GitHub PR API |
+| `gns3server/api/routes/controller/skills_editor.py` | FastAPI router with all endpoints above |
+
+### Modified Files
+
+| File | Change |
+|------|--------|
+| `gns3server/agent/gns3_copilot/skills/manager.py` | Add `get_file_manager()` method returning a `SkillsFileManager` |
+| `gns3server/api/routes/controller/__init__.py` | Register `skills_editor` router under `/copilot/skills` prefix |
+| `gns3server/api/routes/controller/copilot.py` | Deprecate `/reload/skills` in favor of `/skills/reload` |
+
+### SkillsFileManager Key Methods
+
+| Method | Returns |
+|--------|---------|
+| `list_categories()` | `list[{category, file_count, path}]` |
+| `list_files(category)` | `list[{filename, size, last_modified}]` |
+| `read_file(category, filename)` | File content as string |
+| `write_file(category, filename, content)` | Write (create or update) |
+| `delete_file(category, filename)` | Delete file |
+| `get_git_status()` | Modified/untracked/deleted file lists |
+| `commit_changes(message, files)` | git add + commit |
+| `push_to_remote(branch)` | git push |
+| `create_pull_request(title, body, branch, target, fork_url)` | Push + GitHub PR API |
+
+## Security
+
+- **Authentication**: All endpoints require superadmin (`current_user.is_superadmin` check)
+- **Path traversal prevention**: Category validated against whitelist; filename sanitized (no `/`, `..`, or absolute paths)
+- **File extension enforcement**: `.yaml` for injection/device/packet_analysis, `.md` for prompts, `.txt` for config
+- **File size limit**: Reject files > 1MB
+- **YAML validation**: Validate with `yaml.safe_load` before saving
+- **GitHub token**: Required for PR creation, stored in GNS3 server config
+
+### PR Creation Modes
+
+1. **Direct push**: Push to a new branch on the main repo, create PR via GitHub API
+2. **Fork**: Push to user's fork, create PR against upstream
+
+The `fork_url` parameter selects the mode. When omitted, the API pushes to the same repository and creates a PR directly.
+
+## Related Documentation
+
+- [External Skills Repository](../implemented/skills-repository.md)
+- [Fault Injection](../implemented/fault-injection.md)
+- [Chat API](../implemented/chat-api.md)

docs/gns3-copilot/roadmap/user-node-limit-roadmap.md

@@ -0,0 +1,311 @@
+# User Node Limit Roadmap
+
+## Overview
+
+Implement a user-level node startup limit feature for GNS3 server to prevent single users from consuming excessive system resources. This feature is **disabled by default** and can be enabled through configuration files, supporting a three-tier configuration priority system.
+
+## Problem Statement
+
+Currently, GNS3 server has no mechanism to limit the number of nodes a user can start across all their projects. This can lead to:
+
+- **Resource exhaustion**: A single user can consume all available system resources
+- **Unfair usage**: Some users may prevent others from using the system
+- **System instability**: Too many running nodes can degrade overall performance
+- **Cost issues**: In cloud environments, this can lead to unexpected costs
+
+## Solution Design
+
+### Core Principles
+
+1. **Default to no limits**: System maintains backward compatibility by defaulting to unrestricted usage
+2. **Configuration-driven**: All limits can be controlled through configuration files
+3. **Multi-tier priority**: User-specific > User group-specific > Global configuration
+4. **Intelligent filtering**: Only count nodes that actually consume resources
+5. **Clear error messages**: Users receive actionable feedback when limits are reached
+
+### Technical Architecture
+
+#### 1. Database Layer Extension
+
+**Files**: `gns3server/db/models/users.py`
+
+Add `max_nodes` field to both `User` and `UserGroup` models:
+
+```python
+# In User model
+max_nodes = Column(Integer, nullable=True)  # NULL = no limit
+
+# In UserGroup model  
+max_nodes = Column(Integer, nullable=True)  # NULL = no limit
+```
+
+#### 2. Configuration System Extension
+
+**File**: `gns3server/schemas/config.py`
+
+Add node limit configuration to `ControllerSettings`:
+
+```python
+class NodeLimitSettings(BaseModel):
+    enabled: bool = False  # Feature toggle (default disabled)
+    default_max_nodes: int = 5  # Default limit when enabled
+    excluded_node_types: List[str] = Field(default_factory=lambda: [
+        "ethernet_switch", "ethernet_hub", "cloud", "nat"
+    ])
+```
+
+#### 3. Core Service Implementation
+
+**New File**: `gns3server/services/node_limit_service.py`
+
+Implement the `NodeLimitService` class with key methods:
+
+```python
+class NodeLimitService:
+    async def get_user_active_node_count(self, username: str, excluded_types: List[str]) -> int:
+        """Count user's active nodes across all projects"""
+        
+    async def get_user_node_limit(self, user: User) -> Optional[int]:
+        """Get user's node limit with priority logic"""
+        
+    async def check_user_node_limit(self, user: User, project: Project) -> Tuple[bool, str]:
+        """Check if user can start more nodes"""
+```
+
+#### 4. API Integration
+
+**File**: `gns3server/api/routes/controller/nodes.py`
+
+Add limit checking to node startup endpoint:
+
+```python
+@router.post("/{node_id}/start")
+async def start_node(
+    node: Node = Depends(dep_node),
+    current_user: User = Depends(get_current_active_user),
+    node_limit_service: NodeLimitService = Depends(get_node_limit_service)
+):
+    # Node limit check
+    can_start, error_msg = await node_limit_service.check_user_node_limit(
+        current_user, node.project
+    )
+    if not can_start:
+        raise HTTPException(status_code=403, detail=error_msg)
+    
+    # Original startup logic
+    await node.start()
+```
+
+### Node Counting Logic
+
+#### What Counts Toward the Limit
+
+- **Status**: Only nodes in `started` or `suspended` state
+- **Ownership**: Only projects where `project.created_by == current_user.username`
+- **Node types**: All node types except those explicitly excluded
+
+#### What's Excluded from the Limit
+
+- **Always-running nodes**: Ethernet switches, hubs (nodes where `is_always_running()` returns true)
+- **Infrastructure nodes**: Cloud nodes and NAT nodes
+- **Stopped nodes**: Nodes in `stopped` state
+- **Other users' projects**: Nodes in projects created by other users
+
+#### Configuration Priority
+
+```
+User-specific limit (highest priority)
+    ↓ not set
+User group limit
+    ↓ not set  
+Global configuration (if enabled)
+    ↓ disabled
+No limit (default)
+```
+
+### Configuration Examples
+
+#### Scenario 1: Default No Limits (System Default)
+
+```ini
+[Controller]
+node_limits_enabled = false
+```
+
+**Result**: All users have no node limits
+
+#### Scenario 2: Enable Global Limits
+
+```ini
+[Controller]
+node_limits_enabled = true
+node_limits_default_max_nodes = 5
+node_limits_excluded_types = ethernet_switch,ethernet_hub,cloud,nat
+```
+
+**Result**: All users limited to 5 active nodes (excluding infrastructure nodes)
+
+#### Scenario 3: User-Specific Limits
+
+Configuration file: `node_limits_enabled = false`
+
+Database:
+- User A: `max_nodes = 10` (limited to 10 nodes)
+- User B: `max_nodes = NULL` (no limit)
+- Other users: no limit
+
+#### Scenario 4: User Group Limits
+
+Configuration file: `node_limits_enabled = false`
+
+Database:
+- "Users" group: `max_nodes = 5`
+- "Premium Users" group: `max_nodes = 20`
+- "Administrators" group: `max_nodes = NULL`
+
+**Result**: Members inherit limits from their groups
+
+## Implementation Files
+
+| File Path | Type | Description |
+|-----------|------|-------------|
+| `gns3server/db/models/users.py` | Modify | Add `max_nodes` field to User and UserGroup |
+| `gns3server/db_migrations/versions/xxx_add_node_limits.py` | New | Database migration script |
+| `gns3server/schemas/config.py` | Modify | Add NodeLimitSettings configuration class |
+| `gns3server/schemas/controller/users.py` | Modify | Add `max_nodes` to API schemas |
+| `gns3server/services/node_limit_service.py` | New | Core node limit service |
+| `gns3server/api/routes/controller/nodes.py` | Modify | Add limit check to node startup |
+| `gns3server/api/routes/controller/users.py` | Modify | Add user limit configuration API |
+| `gns3server/api/routes/controller/groups.py` | Modify | Add group limit configuration API |
+
+## Implementation Steps
+
+### Phase 1: Database Layer
+1. Add `max_nodes` field to `User` and `UserGroup` models
+2. Create database migration file
+3. Test database migration and rollback
+
+### Phase 2: Configuration System
+1. Add `NodeLimitSettings` to configuration schema
+2. Update configuration file loading logic
+3. Test configuration parsing and validation
+
+### Phase 3: Core Service
+1. Implement `NodeLimitService` class
+2. Implement node counting logic
+3. Implement limit checking logic
+4. Add unit tests for service methods
+
+### Phase 4: API Integration
+1. Modify node startup endpoint to add limit check
+2. Add user limit configuration endpoints
+3. Add group limit configuration endpoints
+4. Add user node usage statistics endpoint
+
+### Phase 5: Testing
+1. Unit tests for all core functions
+2. Integration tests for API endpoints
+3. End-to-end tests for complete workflows
+4. Performance tests for node counting operations
+
+## Testing Strategy
+
+### Functional Tests
+- [ ] Default state verification (no limits)
+- [ ] Global limit enablement
+- [ ] User-specific limits
+- [ ] User group limits
+- [ ] Configuration priority verification
+
+### Boundary Tests
+- [ ] Exactly at limit (can start last node)
+- [ ] One over limit (startup rejected)
+- [ ] Stop node then restart (should work)
+- [ ] Special node type exclusion
+
+### Integration Tests
+- [ ] Multi-user concurrent startups
+- [ ] Node state transitions
+- [ ] Dynamic configuration changes
+- [ ] Project ownership filtering
+
+### Performance Tests
+- [ ] Node counting performance with many projects
+- [ ] Concurrent startup request handling
+- [ ] Memory usage monitoring
+
+## Error Messages
+
+### User-Friendly Error Response
+
+When a user hits their node limit:
+
+```json
+{
+  "detail": "节点启动限制：您当前有 5 个活跃节点，限制为 5 个。请停止一些节点后再试，或联系管理员调整限制。"
+}
+```
+
+Alternative formats:
+- Show current usage vs limit
+- Provide action suggestions
+- Include contact information for administrators
+
+## Migration Path
+
+### For Existing Systems
+
+1. **Database migration**: Add new nullable fields (safe, no data loss)
+2. **Configuration update**: Add new optional settings (backward compatible)
+3. **API changes**: Add new optional dependency injection (no breaking changes)
+4. **Behavior**: No changes to existing functionality when disabled
+
+### Rollback Plan
+
+If issues occur:
+1. Set `node_limits_enabled = false` in configuration
+2. Service automatically disables limit checking
+3. System returns to pre-feature behavior
+
+## Benefits
+
+1. **Resource Management**: Prevent resource exhaustion
+2. **Fair Usage**: Ensure equitable resource distribution
+3. **Cost Control**: Manage cloud resource costs
+4. **System Stability**: Maintain performance under load
+5. **Flexibility**: Support different usage patterns and tiers
+6. **Backward Compatible**: No impact on existing deployments
+
+## Future Enhancements
+
+- Per-project limits (in addition to global user limits)
+- Time-based limits (different limits for different times)
+- Burst limits (temporary allowance for peak usage)
+- Usage quotas with reset periods (daily/weekly/monthly)
+- Monitoring and alerting for limit approaching
+- Administrative override capabilities
+- Usage history and analytics
+
+## Documentation Updates
+
+- [ ] Update API documentation with new endpoints
+- [ ] Add configuration guide to admin documentation
+- [ ] Update user guide with limit information
+- [ ] Add troubleshooting section for limit issues
+- [ ] Provide migration guide for existing deployments
+
+## Status
+
+**Current Status**: Design Phase
+
+**Next Steps**:
+1. Review and approve this roadmap
+2. Begin Phase 1 implementation (Database Layer)
+3. Create detailed technical specification
+4. Set up development and testing environment
+
+---
+
+**Document Version**: 1.0  
+**Last Updated**: 2026-05-27  
+**Author**: GNS3 Development Team

docs/gns3-copilot/roadmap/user-preferences-api-roadmap.md

@@ -0,0 +1,60 @@
+<!--
+SPDX-License-Identifier: CC-BY-SA-4.0
+See LICENSE file for licensing information.
+-->
+
+> This document is a roadmap/planning document. The described features have not been implemented yet.
+
+
+# User Preferences API — Roadmap
+
+## Problem
+
+Currently, user-specific preferences (UI theme, language, AI Copilot settings, workspace layout, etc.) can only be stored in browser `localStorage`. This has several drawbacks:
+
+1. **localStorage clearing** — clearing browser data or switching devices loses all settings
+2. **No cross-device sync** — users must reconfigure preferences on each device
+3. **No API access** — CLI tools and third-party clients cannot read/write preferences
+4. **Fragile persistence** — localStorage can be cleared by browser maintenance or incognito mode
+
+## Proposed API
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/v3/access/users/me/preferences` | Get all preferences for current user |
+| `PUT` | `/v3/access/users/me/preferences` | Merge preferences (top-level merge, not replace) |
+| `DELETE` | `/v3/access/users/me/preferences` | Clear all preferences |
+
+### Storage
+
+A `preferences` JSON column on the existing `users` table:
+
+- Type: `JSON`, non-nullable, default `'{}'`
+- No schema enforcement — clients can store arbitrary key-value pairs
+- Examples: `{"theme": "dark", "language": "zh-CN", "copilot_default_mode": "teaching_assistant"}`
+
+### Implementation Plan
+
+1. Add `preferences` JSON column to `User` ORM model
+2. Create Alembic migration
+3. Add `UserPreferencesUpdate` Pydantic schema with `extra="allow"`
+4. Add `get_user_preferences()` and `update_user_preferences()` to `UsersRepository`
+5. Add three endpoints to `users.py` router: `GET/PUT/DELETE /me/preferences`
+
+### Related Files
+
+| File | Role |
+|------|------|
+| `gns3server/db/models/user.py` | User ORM model |
+| `gns3server/db/repositories/users.py` | UsersRepository with database operations |
+| `gns3server/api/routes/controller/users.py` | User API router |
+| `gns3server/schemas/` | Pydantic schemas |
+| `gns3server/db/versions/` | Alembic migrations |
+
+## Status
+
+- [ ] Add `preferences` JSON column to User ORM model
+- [ ] Create Alembic migration
+- [ ] Add `UserPreferencesUpdate` schema
+- [ ] Add repository methods
+- [ ] Add API endpoints to users.py router

docs/gns3-copilot/roadmap/web-wireshark-docker-optimization-roadmap.md

@@ -0,0 +1,372 @@
+<!--
+SPDX-License-Identifier: CC-BY-SA-4.0
+See LICENSE file for licensing information.
+-->
+
+> This document is a roadmap/planning document. The described features have not been implemented yet.
+
+
+# Web Wireshark Docker Image Size Optimization — Roadmap
+
+## Problem
+
+The `gns3/web-wireshark` Docker image currently occupies **~2GB** of disk space, which impacts:
+- Initial pull/download time for users
+- Storage requirements on Docker Hub
+- Deployment flexibility in resource-constrained environments
+
+### Current Size Breakdown
+
+Based on `docker history gns3/web-wireshark:latest`:
+
+| Component | Size | Percentage |
+|-----------|------|------------|
+| `debian:trixie` base image | 120 MB | 6% |
+| xpra + dependencies | 65.1 MB | 3.3% |
+| Wireshark + GUI stack (Qt, GTK, X11) | 1.82 GB | 91% |
+| **Total** | **~2 GB** | **100%** |
+
+### Detailed File System Analysis
+
+Analysis of container file system reveals significant cleanup opportunities:
+
+| Directory | Size | Cleanup Potential |
+|-----------|------|-------------------|
+| `/usr/lib` | 1.3 GB | ~50MB (static libraries) |
+| `/usr/share/locale` | 151 MB | **~145MB** (192 locales → 1) |
+| `/usr/share/ibus` | 130 MB | **~130MB** (input framework) |
+| `/usr/share/doc` | 76 MB | **~76MB** (documentation) |
+| `/usr/share/backgrounds` | 37 MB | **~37MB** (desktop backgrounds) |
+| `/usr/share/man` | 27 MB | **~27MB** (man pages) |
+| `/usr/share/icons` | 16 MB | ~5MB (keep essential) |
+| Development packages | ~50 MB | **~50MB** (21 `-dev` packages) |
+| Static libraries (`*.a`, `*.la`) | 16 MB | **~16MB** |
+| Sounds/help/perl | ~20 MB | **~20MB** |
+| **Total Cleanable** | **~570 MB** | |
+
+**Key Findings**:
+- 192 locale languages installed (only need en_US)
+- ibus input framework installed (not needed in headless container)
+- 21 development packages with headers/headers
+- 161 static library files (`.a`, `.la`)
+- Complete documentation and man pages
+- Desktop environment components (backgrounds, sounds)
+
+## Proposed Optimizations
+
+### Phase 1: Safe Optimizations (Estimated: -300~400MB)
+
+Low-risk changes that maintain full compatibility.
+
+#### 1. Use Slim Base Image (-50MB)
+
+```dockerfile
+FROM debian:trixie-slim  # Instead of debian:trixie
+```
+
+**Impact**: Reduces base from 120MB to ~70MB  
+**Risk**: Low - slim variant contains all essential runtime libraries  
+**Testing Required**: Verify xpra and Wireshark launch without errors
+
+#### 2. Install Without Recommended Packages (-150~200MB)
+
+```dockerfile
+RUN apt-get install -y --no-install-recommends \
+    wireshark-common \
+    wireshark \
+    xpra=6.4.3* \
+    xpra-x11 \
+    xvfb \
+    curl \
+    x11-utils
+```
+
+**Impact**: Prevents installation of non-essential recommended packages  
+**Risk**: Low - only excludes recommended packages, not required dependencies  
+**Testing Required**: Full functionality test (capture, analysis, WebSocket)
+
+#### 3. Cleanup Unnecessary Files (-400~500MB)
+
+```dockerfile
+RUN apt-get install -y --no-install-recommends \
+    wireshark-common wireshark xpra=6.4.3* xpra-x11 xvfb curl x11-utils \
+    # Remove documentation and man pages
+    && rm -rf /var/lib/apt/lists/* \
+    && rm -rf /usr/share/doc/* /usr/share/man/* /usr/share/help/* \
+    # Remove unnecessary locales (keep only en_US)
+    && rm -rf /usr/share/locale/* \
+    && localedef -i en_US -f UTF-8 en_US.UTF-8 \
+    # Remove desktop environment components
+    && rm -rf /usr/share/backgrounds/* /usr/share/sounds/* \
+    # Remove static libraries
+    && find /usr/lib -name '*.a' -delete \
+    && find /usr/lib -name '*.la' -delete \
+    # Remove unnecessary packages
+    && apt-get purge -y -y \
+        ibus ibus-data ibus-gtk* python3-ibus-1.0 \
+        gnome-backgrounds \
+    && apt-get autoremove -y \
+    && apt-get clean
+```
+
+**Impact**: Removes documentation, locales, desktop components, input framework  
+**Risk**: Low - all removed components are unnecessary in headless container  
+**Testing Required**: Verify Wireshark GUI renders correctly without icons/themes
+
+### Phase 2: Experimental (Requires Testing, -200~500MB)
+
+Higher-risk optimizations that need extensive validation.
+
+#### 4. Alpine Linux Alternative (-500MB~1GB)
+
+```dockerfile
+FROM alpine:3.19
+RUN apk add --no-cache wireshark xpra xvfb curl ...
+```
+
+**Impact**: Could reduce image to ~500MB-1GB  
+**Risk**: **High** - Wireshark and xpra have complex Qt/GTK dependencies  
+**Challenges**:
+- Wireshark Qt dependencies may not be available in Alpine repos
+- xpra package availability and compatibility
+- X11 library differences
+- May require building dependencies from source
+
+**Testing Required**:
+- [ ] Verify Wireshark package availability in Alpine
+- [ ] Test xpra compilation/installation on Alpine
+- [ ] Validate all GUI libraries work correctly
+- [ ] Full integration testing
+
+**Recommendation**: Do not pursue unless Phase 1 insufficient
+
+## Compression Feasibility Analysis
+
+### Question: Can we reduce image size through compression?
+
+**Short Answer**: **Not recommended** - limited benefit with performance trade-offs
+
+### Current Compression Status
+
+Docker images already use compression:
+
+| Format | Size | Compression Rate | Use Case |
+|--------|------|------------------|----------|
+| Runtime size | 2.0 GB | - | Container running |
+| docker save (raw) | 1.9 GB | 5% | Docker internal compression |
+| docker save + gzip | 718 MB | **64%** | Standard transfer |
+| docker save + xz | 563 MB | **72%** | Maximum compression |
+| docker save + zstd | ~600 MB | **70%** | Fast compression |
+
+### Binary Compression Analysis
+
+#### File Already Stripped
+All binaries already have debug symbols removed:
+```bash
+wireshark:    ELF 64-bit... stripped
+python3.13:   ELF 64-bit... stripped
+libc.so.6:    ELF 64-bit... stripped
+```
+
+**No further stripping possible**
+
+#### UPX Executable Compression (Limited Benefit)
+
+Test results compressing major executables:
+
+| Binary | Original | UPX Compressed | Savings | Startup Impact |
+|--------|----------|----------------|---------|----------------|
+| wireshark (11MB) | 11.0 MB | 4.2 MB | 62% | +0.3s |
+| Xvfb (2.1MB) | 2.1 MB | 0.9 MB | 57% | +0.1s |
+| python3.13 (6.6MB) | 6.6 MB | 2.8 MB | 58% | +0.2s |
+| **Total** | **19.7 MB** | **7.9 MB** | **60%** | **+0.6s** |
+
+**Overall Impact**: Only ~20MB savings (1%) with 0.6s startup penalty
+
+### Why Compression Has Limited Benefit
+
+1. **Small Executable Footprint**: Binaries are only 74MB (3.7% of image)
+2. **Libraries Are Data Files**: `/usr/lib` contains mostly data, not code
+3. **Already Compressed**: Docker storage drivers compress layers automatically
+4. **Resource Files Dominate**: Fonts, icons, themes don't compress well
+
+### Compression Trade-offs
+
+| Method | Potential Savings | Performance Impact | Complexity | Risk |
+|--------|-------------------|-------------------|------------|------|
+| **File cleanup** | 400-500MB (20-25%) | None | Low | Low |
+| UPX compression | 50-100MB (2.5-5%) | +0.6s startup | Medium | Medium |
+| Layer squashing | 10-50MB (0.5-2.5%) | None | Low | Low |
+| Transfer compression | 1.4GB (70%) | None (transfer only) | None | None |
+
+### Recommendation
+
+**Do not pursue binary compression** because:
+- ✅ File cleanup is **4-10x more effective**
+- ✅ No performance penalty
+- ✅ Simpler build process
+- ✅ Better compatibility
+
+**For transfer/storage optimization**, use standard tools:
+```bash
+# For archiving (use zstd for best speed/ratio)
+docker save gns3/web-wireshark:latest | \
+  zstd -19 -o web-wireshark.tar.zst
+
+# For maximum compression (slow)
+docker save gns3/web-wireshark:latest | \
+  xz -9 -T 0 > web-wireshark.tar.xz
+```
+
+## Implementation Plan
+
+### Step 1: Create Optimized Dockerfile
+
+Create `gns3server/agent/web_wireshark/docker/Dockerfile.optimized` with Phase 1 changes.
+
+### Step 2: Local Testing
+
+```bash
+# Build optimized image
+cd gns3server/agent/web_wireshark/docker
+docker build -f Dockerfile.optimized -t gns3/web-wireshark:optimized .
+
+# Verify size reduction
+docker images | grep web-wireshark
+
+# Test Wireshark functionality
+docker run --rm gns3/web-wireshark:optimized wireshark --version
+
+# Test xpra functionality
+docker run --rm gns3/web-wireshark:optimized xpra --version
+```
+
+### Step 3: Integration Testing
+
+```bash
+# Test with actual GNS3 server
+pip install . && gns3server-web-wireshark-setup
+
+# Start a test session
+python3 gns3server/agent/web_wireshark/manage_wireshark.py \
+  --verbose start \
+  --project-id "test-optimized" \
+  --link-id "test-link-1" \
+  --jwt-token "test-token" \
+  --image "gns3/web-wireshark:optimized"
+
+# Verify WebSocket connectivity and packet capture
+```
+
+### Step 4: Production Rollout
+
+1. Tag optimized image: `gns3/web-wireshark:v1.6-optimized`
+2. Deploy to staging environment
+3. Monitor for 1 week with real workloads
+4. If stable, promote to `latest` tag
+5. Keep old image available for rollback
+
+## Testing Checklist
+
+Before marking as complete:
+
+- [ ] Wireshark launches without errors
+- [ ] xpra HTML5 client connects successfully
+- [ ] Packet capture works end-to-end
+- [ ] Packet analysis and filtering functional
+- [ ] WebSocket proxy integration works
+- [ ] Multi-session handling tested (3+ simultaneous captures)
+- [ ] Image size measured and documented
+- [ ] Tested on Docker 20.10, 24.x, 29.x
+- [ ] Startup time not negatively impacted
+- [ ] Memory/CPU usage unchanged
+- [ ] All existing tests pass
+
+## Expected Results
+
+### Phase 1: Safe Optimizations (Recommended)
+
+| Metric | Current | Target | Improvement |
+|--------|---------|--------|-------------|
+| Image Size | 2GB | ~1.5GB | **-25% (500MB)** |
+| Pull Time | 3-5 min | 2-3 min | **-40%** |
+| Startup Time | 5-6s | 5-6s | No change |
+| Functionality | Full | Full | No regression |
+| Compatibility | All | All | No change |
+
+### Phase 2: Experimental (If Needed)
+
+| Metric | Current | Target | Improvement |
+|--------|---------|--------|-------------|
+| Image Size | 2GB | ~1GB | **-50% (1GB)** |
+| Pull Time | 3-5 min | 1-2 min | **-60%** |
+| Startup Time | 5-6s | 5-7s | Slight increase |
+| Functionality | Full | Full | Risk of regressions |
+| Compatibility | All | Alpine only | Significant testing required |
+
+### Compression Comparison (Not Recommended)
+
+| Method | Size | Savings | Trade-offs |
+|--------|------|---------|------------|
+| **File cleanup** | ~1.5GB | 500MB | None |
+| UPX compression | ~1.9GB | 100MB | +0.6s startup, compatibility risk |
+| Transfer compression | 600MB | 1.4GB | Transfer only, no runtime benefit |
+
+## Related Files
+
+| File | Current State | Changes Needed |
+|------|---------------|----------------|
+| `gns3server/agent/web_wireshark/docker/Dockerfile` | Current 2GB image | Create optimized variant |
+| `gns3server/agent/web_wireshark/setup_wireshark_image.py` | Pulls/builds current image | Support optimized image option |
+| `gns3server/schemas/config.py` | WebWiresharkSettings | Add image variant config |
+| `gns3server/agent/web_wireshark/WEB_WIRESHARK.md` | Documents current image | Update with optimization notes |
+
+## Status
+
+### Phase 1: Safe Optimizations
+
+- [ ] Create `Dockerfile.optimized` with slim base + --no-install-recommends + cleanup
+- [ ] Local build and size verification
+- [ ] Functional testing (Wireshark, xpra, WebSocket)
+- [ ] Integration testing with GNS3 server
+- [ ] Document actual size reduction achieved
+- [ ] Deploy to staging for 1-week observation
+- [ ] Promote to production if stable
+
+### Phase 2: Experimental (Only if Phase 1 insufficient)
+
+- [ ] Research Alpine Wireshark/xpra package availability
+- [ ] Prototype Alpine build if feasible
+- [ ] Extensive compatibility testing
+- [ ] Performance benchmarking vs. Phase 1
+
+## Notes
+
+- All size estimates based on actual `docker history` and container filesystem analysis
+- Phase 1 optimizations are conservative and should be safe
+- Compression techniques (UPX, layer squashing) provide minimal benefit (1-5%)
+- File cleanup is **10x more effective** than compression (25% vs 2.5%)
+- Phase 2 requires significant research and testing effort
+- Backward compatibility must be maintained during transition
+- Consider maintaining both `latest` and `optimized` tags during migration period
+
+### Key Findings from Analysis
+
+1. **Major space waste**: 570MB of cleanable files (28.5% of image)
+   - Locale files: 151MB → 6MB (keep only en_US)
+   - ibus input framework: 130MB → 0MB (not needed in headless container)
+   - Documentation: 76MB → 0MB (docs, man pages, help)
+   - Desktop components: 37MB → 0MB (backgrounds, sounds)
+   - Development packages: 50MB → 0MB (21 -dev packages)
+
+2. **Compression not viable**:
+   - Binaries already stripped (no debug symbols)
+   - UPX only saves 20MB (1%) with 0.6s startup penalty
+   - Docker already compresses layers internally
+   - Resource files (fonts, themes) don't compress well
+
+3. **Best approach**: Clean up unnecessary files rather than compress
+   - 25x better compression ratio than UPX
+   - No performance impact
+   - Simpler build process
+   - Better compatibility

docs/index.html

@@ -1,3 +1,7 @@
+<!--
+SPDX-License-Identifier: CC-BY-SA-4.0
+See LICENSE file for licensing information.
+-->
 
     <!DOCTYPE html>
     <html>

docs/redoc.html

@@ -1,15 +1,19 @@
+<!--
+SPDX-License-Identifier: CC-BY-SA-4.0
+See LICENSE file for licensing information.
+-->
 
     <!DOCTYPE html>
     <html>
     <head>
-    <link type="text/css" rel="stylesheet" href="https://cdn.jsdelivr.net/npm/swagger-ui-dist@3.30.0/swagger-ui.css">
+    <link type="text/css" rel="stylesheet" href="/static/swagger-ui.css">
     <link rel="shortcut icon" href="https://fastapi.tiangolo.com/img/favicon.png">
     <title>GNS3 controller API - Swagger UI</title>
     </head>
     <body>
     <div id="swagger-ui">
     </div>
-    <script src="https://cdn.jsdelivr.net/npm/swagger-ui-dist@3.30.0/swagger-ui-bundle.js"></script>
+    <script src="/static/swagger-ui-bundle.js"></script>
     <!-- `SwaggerUIBundle` is now available on the page -->
     <script>
     const ui = SwaggerUIBundle({

gns3server/agent/__init__.py

@@ -0,0 +1,105 @@
+#
+# Copyright (C) 2025 GNS3 Technologies Inc.
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+"""
+Agent module with optional AI Copilot and MCP support.
+
+This module provides the AI Copilot and MCP (Model Context Protocol)
+functionality as optional features. If the respective dependencies are
+not installed, the affected features will be disabled but will not
+prevent the server from starting.
+
+Installation:
+    pip install gns3-server[ai-features]         # Install all AI features
+"""
+
+import logging
+import threading
+
+# Feature flag: AI Copilot is available
+AI_COPILOT_AVAILABLE = False
+
+# Try to import AI Copilot components
+try:
+    from .gns3_copilot.project_agent_manager import get_project_agent_manager
+    from .gns3_copilot.project_agent_manager import ProjectAgentManager
+    AI_COPILOT_AVAILABLE = True
+
+    # Start skills repository initialization in background.
+    # Clones/pulls GNS3-Skills during server startup.
+    # Git network timeouts are configured in SkillsManager (_GIT_TIMEOUT_ENV).
+    # The daemon thread auto-terminates when the process exits.
+    from gns3server.agent.gns3_copilot.skills.registry import _ensure_skills_manager
+
+    threading.Thread(target=_ensure_skills_manager, daemon=True).start()
+
+except ImportError as e:
+    # AI dependencies not installed, disable AI Copilot feature
+    logging.warning(
+        f"AI Copilot dependencies not installed: {e}. "
+        "AI features will be disabled. "
+        "Install with: pip install gns3-server[ai-features]"
+    )
+    AI_COPILOT_AVAILABLE = False
+
+    # Provide stub functions that raise helpful errors
+    async def get_project_agent_manager():
+        """
+        Get the global ProjectAgentManager singleton instance.
+
+        Raises:
+            RuntimeError: If AI Copilot dependencies are not installed
+        """
+        raise RuntimeError(
+            "AI Copilot is not available. "
+            "Install AI dependencies with: pip install gns3-server[ai-features]"
+        )
+
+    class ProjectAgentManager:
+        """
+        Stub class for ProjectAgentManager when AI dependencies are not installed.
+        """
+
+        def __init__(self):
+            raise RuntimeError(
+                "AI Copilot is not available. "
+                "Install AI dependencies with: pip install gns3-server[ai-features]"
+            )
+
+
+# Feature flag: MCP (Model Context Protocol) is available
+MCP_AVAILABLE = False
+
+# Try to import MCP dependencies
+try:
+    import mcp.server.fastmcp  # noqa: F401 — test import only
+    MCP_AVAILABLE = True
+except ImportError:
+    # MCP dependencies not installed, disable MCP feature
+    logging.warning(
+        "MCP dependencies not installed. "
+        "MCP features will be disabled. "
+        "Install with: pip install gns3-server[ai-features]"
+    )
+    MCP_AVAILABLE = False
+
+
+__all__ = [
+    "AI_COPILOT_AVAILABLE",
+    "MCP_AVAILABLE",
+    "get_project_agent_manager",
+    "ProjectAgentManager",
+]

gns3server/agent/gns3_copilot/__init__.py

@@ -0,0 +1,44 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# GNS3-Copilot - AI-powered Network Lab Assistant for GNS3
+#
+# This file is part of GNS3-Copilot project.
+#
+# GNS3-Copilot is free software: you can redistribute it and/or modify it
+# under the terms of the GNU General Public License as published by the
+# Free Software Foundation, either version 3 of the License, or (at your
+# option) any later version.
+#
+# GNS3-Copilot is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+# or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+# for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with GNS3-Copilot. If not, see <https://www.gnu.org/licenses/>.
+#
+# Copyright (C) 2025 Yue Guobin (岳国宾)
+# Author: Yue Guobin (岳国宾)
+#
+# Project Home: https://github.com/yueguobin/gns3-copilot
+#
+"""
+
+GNS3-Copilot - AI-powered network automation assistant for GNS3.
+
+This package provides a command-line interface for launching the GNS3-Copilot
+Streamlit application with support for Streamlit parameter passthrough.
+"""
+
+# Dynamic version management
+__version__: str = "unknown"
+try:
+    from importlib.metadata import version
+
+    __version__ = str(version("gns3-copilot"))
+except Exception:
+    __version__ = "unknown"
+
+__author__ = "Yue Guobin (岳国宾)"
+__description__ = "AI-powered network automation assistant for GNS3"
+__url__ = "https://github.com/yueguobin/gns3-copilot"

gns3server/agent/gns3_copilot/agent/__init__.py

@@ -0,0 +1,50 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# GNS3-Copilot - AI-powered Network Lab Assistant for GNS3
+#
+# This file is part of GNS3-Copilot project.
+#
+# GNS3-Copilot is free software: you can redistribute it and/or modify it
+# under the terms of the GNU General Public License as published by the
+# Free Software Foundation, either version 3 of the License, or (at your
+# option) any later version.
+#
+# GNS3-Copilot is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+# or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+# for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with GNS3-Copilot. If not, see <https://www.gnu.org/licenses/>.
+#
+# Copyright (C) 2025 Yue Guobin (岳国宾)
+# Author: Yue Guobin (岳国宾)
+#
+# Project Home: https://github.com/yueguobin/gns3-copilot
+#
+
+"""
+GNS3-Copilot Agent Package
+
+This package contains the main GNS3-Copilot agent implementation for
+network automation tasks using LangGraph workflow orchestration.
+
+"""
+
+from .gns3_copilot import agent_builder
+
+# Dynamic version management
+try:
+    from importlib.metadata import version
+
+    __version__ = version("gns3-copilot")
+except Exception:
+    __version__ = "unknown"
+
+__author__ = "Yue Guobin (岳国宾)"
+__description__ = "AI-powered network automation assistant for GNS3"
+__url__ = "https://github.com/yueguobin/gns3-copilot"
+
+__all__ = [
+    "agent_builder",
+]

gns3server/agent/gns3_copilot/agent/context_manager.py

@@ -0,0 +1,641 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# GNS3-Copilot - AI-powered Network Lab Assistant for GNS3
+#
+# Copyright (C) 2025 Yue Guobin (岳国宾)
+# Author: Yue Guobin (岳国宾)
+#
+# This file is part of GNS3-Copilot project.
+#
+# GNS3-Copilot is free software: you can redistribute it and/or modify it
+# under the terms of the GNU General Public License as published by the
+# Free Software Foundation, either version 3 of the License, or (at your
+# option) any later version.
+#
+# GNS3-Copilot is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+# or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+# for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with GNS3-Copilot. If not, see <https://www.gnu.org/licenses/>.
+#
+# Project Home: https://github.com/yueguobin/gns3-copilot
+#
+
+"""
+Context Manager for GNS3-Copilot - Using LangGraph pre_model_hook
+
+This module provides context window management using LangGraph's recommended
+pre_model_hook approach with accurate token counting:
+
+Key Features:
+- Accurate token counting using tiktoken (95%+ accuracy)
+- Template variable injection for topology info
+- Context strategy ratios (conservative/balanced/aggressive)
+- Message trimming using LangChain's native trim_messages
+- Tool definition token estimation
+- Detailed token breakdown logging
+
+Requirements:
+- tiktoken>=0.8.0 (required)
+"""
+
+import json
+import logging
+import os
+import warnings
+from pathlib import Path
+from typing import Any
+from typing import Callable
+
+# Configure tiktoken cache directory (must be set before importing tiktoken)
+_cache_dir = Path(__file__).parent.parent / "cache" / "tiktoken"
+_cache_dir.mkdir(parents=True, exist_ok=True)
+os.environ["TIKTOKEN_CACHE_DIR"] = str(_cache_dir)
+
+import tiktoken
+from langchain_core.messages import BaseMessage
+from langchain_core.messages import SystemMessage
+from langchain_core.messages import trim_messages
+
+logger = logging.getLogger(__name__)
+
+# ============================================================================
+# Token Counter Setup
+# ============================================================================
+
+# Initialize tiktoken encoding (required dependency)
+import time
+logger.debug("Initializing tiktoken encoding (cl100k_base)...")
+logger.debug(f"Cache directory: {_cache_dir}")
+logger.debug("This may take a moment on first run (downloading ~1.6MB encoding file from openaipublic.blob.core.windows.net)")
+start_time = time.time()
+_tiktoken_encoding = tiktoken.get_encoding("cl100k_base")
+elapsed = time.time() - start_time
+logger.debug(f"✓ tiktoken encoding loaded successfully (took {elapsed:.2f}s)")
+
+# ============================================================================
+# Constants
+# ============================================================================
+
+# Context strategy ratios (percentage of context limit to use for input)
+CONTEXT_STRATEGY_RATIOS = {
+    "conservative": 0.60,
+    "balanced": 0.75,
+    "aggressive": 0.85,
+}
+
+DEFAULT_CONTEXT_STRATEGY = "balanced"
+
+# Token unit conversion
+TOKENS_PER_K = 1000
+
+
+# ============================================================================
+# Token Counting Functions
+# ============================================================================
+
+
+def count_tokens(text: str) -> int:
+    """
+    Count tokens in text using tiktoken.
+
+    Uses cl100k_base encoding (GPT-4) which provides accurate counting
+    for most modern LLMs (OpenAI, Anthropic, DeepSeek, etc.).
+
+    Args:
+        text: Text to count tokens for
+
+    Returns:
+        Exact token count (not estimated)
+    """
+    if not text:
+        return 0
+
+    return len(_tiktoken_encoding.encode(text))
+
+
+def estimate_tool_tokens(tools: list[Any]) -> int:
+    """
+    Estimate token consumption for tool definitions.
+
+    Tool definitions are serialized as JSON and sent to LLM with each request.
+    This function estimates their token cost.
+
+    Args:
+        tools: List of LangChain tool objects
+
+    Returns:
+        Estimated token count for all tool definitions
+    """
+    if not tools:
+        return 0
+
+    total_tokens = 0
+
+    for tool in tools:
+        try:
+            # Build tool schema in OpenAI format
+            tool_schema = {
+                "type": "function",
+                "function": {
+                    "name": tool.name,
+                    "description": tool.description,
+                },
+            }
+
+            # Add parameters schema if available
+            if hasattr(tool, "args_schema") and tool.args_schema:
+                try:
+                    # Try Pydantic v2 method (model_json_schema)
+                    tool_schema["function"]["parameters"] = (
+                        tool.args_schema.model_json_schema()
+                    )
+                except AttributeError:
+                    # Fallback to Pydantic v1 method (schema)
+                    try:
+                        tool_schema["function"]["parameters"] = (
+                            tool.args_schema.schema()
+                        )
+                    except Exception:
+                        # Both methods failed, use empty schema
+                        tool_name = getattr(tool, "name", "unknown")
+                        logger.debug(
+                            "Failed to get schema for tool %s, using empty "
+                            "parameters",
+                            tool_name,
+                        )
+                        tool_schema["function"]["parameters"] = {}
+                except Exception as e:
+                    # model_json_schema() raised an exception
+                    tool_name = getattr(tool, "name", "unknown")
+                    logger.debug(
+                        "model_json_schema() failed for tool %s: %s, "
+                        "trying v1 fallback",
+                        tool_name,
+                        e,
+                    )
+                    try:
+                        tool_schema["function"]["parameters"] = (
+                            tool.args_schema.schema()
+                        )
+                    except Exception:
+                        tool_schema["function"]["parameters"] = {}
+
+            # Serialize to JSON and count tokens
+            schema_str = json.dumps(tool_schema, ensure_ascii=False)
+            tokens = count_tokens(schema_str)
+            total_tokens += tokens
+
+        except Exception as e:
+            tool_name = getattr(tool, "name", "unknown")
+            logger.debug(
+                "Failed to estimate tokens for tool %s: %s",
+                tool_name,
+                e,
+            )
+            # Rough fallback: 1000 tokens per tool
+            total_tokens += 1000
+
+    return total_tokens
+
+
+def _count_tokens_for_message(message: BaseMessage) -> int:
+    """
+    Token counter for LangChain's trim_messages.
+
+    This function is called by trim_messages for each message.
+
+    Args:
+        message: A single message (HumanMessage, AIMessage, SystemMessage,
+                 etc.)
+
+    Returns:
+        Estimated token count for the message
+    """
+    content = ""
+    if hasattr(message, "content") and message.content:
+        content = str(message.content)
+
+    return count_tokens(content)
+
+
+# ============================================================================
+# Pre-Model Hook Factory
+# ============================================================================
+
+
+def create_pre_model_hook(
+    system_prompt: str,
+    get_topology_func: Callable[[dict], Any] | None = None,
+    get_llm_config_func: Callable[[], dict[str, Any] | None] | None = None,
+    get_tools_func: Callable[[], list[Any]] | None = None,
+) -> Callable[[dict], dict]:
+    """
+    Create a pre_model_hook function for LangGraph agent.
+
+    This hook will be automatically called before each LLM invocation,
+    handling topology injection, tool token estimation, and message
+    trimming.
+
+    IMPORTANT USAGE REQUIREMENTS:
+        This hook MUST be passed via model.invoke() config, NOT used as
+        a Node return value.
+
+        CORRECT Usage:
+            model.invoke(messages,
+                        config={"configurable": {"pre_model_hook": pre_hook}})
+
+        INCORRECT Usage:
+            # ❌ Don't use as Node return value
+            def my_node(state):
+                return pre_hook(state)  # Wrong!
+
+        # ❌ Don't use with StateGraph if state uses add_messages reducer
+        class State(TypedDict):
+            messages: Annotated[list, add_messages]  # Incompatible!
+
+    COMPATIBILITY:
+        - Works with: model.invoke(config={"configurable":
+                                       {"pre_model_hook": ...}})
+        - Does NOT work as: StateGraph Node return value
+        - Does NOT work with: Annotated[list, add_messages] state reducers
+
+    The hook returns a complete message list that overwrites the model
+    input, which is correct for invoke() but wrong for state updates with
+    add_messages.
+
+    Args:
+        system_prompt: System prompt template (must contain
+                       {{topology_info}} placeholder)
+        get_topology_func: Function to extract topology from state
+        get_llm_config_func: Function to get LLM config from context
+        get_tools_func: Optional function to get tools list for token
+                       estimation
+
+    Returns:
+        A pre_model_hook function for use with model.invoke(config=...)
+
+    Thread Safety:
+        Thread-safe if get_llm_config_func uses request-scoped context
+        (e.g., contextvars)
+
+    Performance Notes:
+        - SystemMessage is reconstructed on each LLM call (intentional
+          design)
+        - Overhead: ~1-2ms per call (negligible compared to LLM latency)
+        - Trade-off: Simplicity > micro-optimization
+        - In ReAct loops with multiple LLM calls, topology is re-injected
+          each time
+        - This is acceptable for GNS3-Copilot's usage patterns (low
+          concurrency, short conversations)
+    """
+
+    def pre_model_hook(state: dict) -> dict:
+        """
+        LangGraph pre_model_hook - called before each LLM invocation.
+
+        This function is NOT a StateGraph Node. It is a preprocessing hook
+        that modifies the input to the LLM, not the agent state.
+
+        Usage Context:
+            Called automatically by LangChain when passed via:
+                model.invoke(messages,
+                            config={"configurable":
+                                   {"pre_model_hook": this}})
+
+        Args:
+            state: Current agent state containing messages and topology_info
+
+        Returns:
+            dict with 'messages' key containing prepared and trimmed messages
+            Note: This return value is used by LangChain to replace the model
+                  input, NOT to update the agent state.
+
+        Raises:
+            ValueError: If context_limit is missing or invalid
+        """
+        logger.debug(
+            "pre_model_hook invoked: messages=%d",
+            len(state.get("messages", [])),
+        )
+
+        messages = state.get("messages", [])
+        if not messages:
+            logger.debug("No messages in state, returning empty list")
+            return {"messages": []}
+
+        # Get LLM config
+        llm_config = get_llm_config_func() if get_llm_config_func else None
+
+        if not llm_config:
+            logger.error("LLM config not found. context_limit is required.")
+            raise ValueError(
+                "LLM config not found. context_limit is required."
+            )
+
+        if "context_limit" not in llm_config:
+            logger.error(
+                "context_limit not found in LLM config. "
+                "This is a required field. Please configure context_limit."
+            )
+            raise ValueError("context_limit is required in LLM config")
+
+        limit = llm_config["context_limit"]
+        if not isinstance(limit, int) or limit <= 0:
+            logger.error("Invalid context_limit: %s", limit)
+            raise ValueError(f"Invalid context_limit: {limit}")
+
+        context_limit_k = limit
+        strategy = llm_config.get("context_strategy", DEFAULT_CONTEXT_STRATEGY)
+
+        if strategy not in CONTEXT_STRATEGY_RATIOS:
+            logger.warning(
+                "Invalid context_strategy '%s', using '%s'",
+                strategy,
+                DEFAULT_CONTEXT_STRATEGY,
+            )
+            strategy = DEFAULT_CONTEXT_STRATEGY
+
+        # Step 1: Estimate tool tokens
+        tool_tokens = 0
+        if get_tools_func:
+            try:
+                tools = get_tools_func()
+                tool_tokens = estimate_tool_tokens(tools)
+                logger.debug(
+                    "Tool definitions estimated at ~%d tokens (%d tools)",
+                    tool_tokens,
+                    len(tools),
+                )
+            except Exception as e:
+                logger.warning("Failed to estimate tool tokens: %s", e)
+
+        # Step 2: Inject topology into system prompt
+        messages_with_system = _inject_topology_into_system(
+            messages=messages,
+            system_prompt=system_prompt,
+            state=state,
+            get_topology_func=get_topology_func,
+        )
+
+        # Step 3: Calculate token breakdown for logging and validation
+        system_message = messages_with_system[0]
+        system_tokens = _count_tokens_for_message(system_message)
+
+        # Calculate tokens for messages_with_system (including system)
+        messages_with_system_tokens = sum(
+            _count_tokens_for_message(m) for m in messages_with_system
+        )
+
+        # Calculate available budget
+        model_limit_tokens = context_limit_k * TOKENS_PER_K
+        strategy_ratio = CONTEXT_STRATEGY_RATIOS[strategy]
+        max_input_tokens = int(model_limit_tokens * strategy_ratio)
+
+        # Calculate max tokens for trim_messages
+        # Important: trim_messages counts ALL messages (including system),
+        # so we only subtract tool_tokens here, NOT system_tokens.
+        # Let trim_messages handle system.
+        max_tokens_for_trim = max_input_tokens - tool_tokens
+
+        # Validate budget and provide actionable warnings
+        if system_tokens + tool_tokens > max_input_tokens:  # noqa: E501
+            logger.error(
+                "System prompt (%d tokens) + tools (%d tokens) EXCEED input "
+                "budget (%d tokens). This will likely cause LLM call failures. "  # noqa: E501
+                "Recommendations: 1) Reduce system prompt length, 2) Reduce "
+                "number of tools, 3) Use a model with larger context window, "
+                "or 4) Switch to 'conservative' strategy.",
+                system_tokens,
+                tool_tokens,
+                max_input_tokens,
+            )
+        elif max_tokens_for_trim < system_tokens * 1.5:
+            # Less than 1.5x system tokens means very little room for history
+            logger.warning(
+                "System prompt (%d tokens) + tools (%d tokens) leave minimal "
+                "room for conversation history (%d tokens remaining). "
+                "Consider reducing system prompt length or number of tools.",
+                system_tokens,
+                tool_tokens,
+                max_tokens_for_trim - system_tokens,
+            )
+
+        # Debug log with clear terminology
+        logger.debug(
+            "Token breakdown: system=%d, all_messages=%d (system+history), "
+            "tools=%d, trim_budget=%d (limit=%dK, strategy=%s)",
+            system_tokens,
+            messages_with_system_tokens,
+            tool_tokens,
+            max_tokens_for_trim,
+            context_limit_k,
+            strategy,
+        )
+
+        # Step 4: Trim messages to fit
+        # Note: max_tokens_for_trim INCLUDES system message, trim_messages
+        # will handle it
+        try:
+            trimmed = trim_messages(
+                messages=messages_with_system,
+                max_tokens=max_tokens_for_trim,
+                strategy="last",
+                token_counter=_count_tokens_for_message,
+                include_system=True,
+            )
+
+            # Calculate final token counts
+            final_total = sum(_count_tokens_for_message(m) for m in trimmed)
+            usage_percent = (
+                (final_total + tool_tokens) / model_limit_tokens * 100
+            )
+
+            if len(trimmed) < len(messages_with_system):
+                logger.info(
+                    "Messages trimmed: %d → %d msgs. Total: ~%d tokens + %d "
+                    "tools = %d / %dK (%.1f%%), strategy=%s",
+                    len(messages_with_system),
+                    len(trimmed),
+                    final_total,
+                    tool_tokens,
+                    final_total + tool_tokens,
+                    context_limit_k,
+                    usage_percent,
+                    strategy,
+                )
+            else:
+                logger.info(
+                    "Context ready: %d msgs, ~%d tokens + %d tools = %d / %dK "
+                    "(%.1f%%), strategy=%s",
+                    len(trimmed),
+                    final_total,
+                    tool_tokens,
+                    final_total + tool_tokens,
+                    context_limit_k,
+                    usage_percent,
+                    strategy,
+                )
+
+            return {"messages": trimmed}
+
+        except Exception as e:
+            logger.error("Failed to trim messages: %s", e)
+            logger.warning("Returning original messages due to trimming error")
+            return {"messages": messages_with_system}
+
+    return pre_model_hook
+
+
+def _inject_topology_into_system(
+    messages: list,
+    system_prompt: str,
+    state: dict,
+    get_topology_func: Callable[[dict], Any] | None = None,
+) -> list:
+    """
+    Inject topology information into system prompt.
+
+    Args:
+        messages: Message list
+        system_prompt: System prompt template
+        state: Current state
+        get_topology_func: Optional function to extract topology
+
+    Returns:
+        Message list with system message prepended
+    """
+    if "{{topology_info}}" not in system_prompt:
+        logger.warning("system_prompt missing {{topology_info}} placeholder")
+        return messages
+
+    topology_data = None
+    if get_topology_func:
+        try:
+            topology_data = get_topology_func(state)
+        except Exception as e:
+            logger.warning("Failed to get topology: %s", e)
+
+    if topology_data:
+        topology_str = str(topology_data)
+        formatted_prompt = system_prompt.replace(
+            "{{topology_info}}", f"\n\n## Current Topology\n{topology_str}"
+        )
+        logger.info(
+            "✓ Topology injected: %d chars, nodes: %s",
+            len(topology_str),
+            list(topology_data.get("nodes", {}).keys())[:5],
+        )  # Show first 5 node names
+        logger.debug(
+            "Full topology data: %s", topology_str[:500]
+        )  # First 500 chars
+    else:
+        formatted_prompt = system_prompt.replace(
+            "{{topology_info}}", "(No topology information available)"
+        )
+        logger.warning("✗ Topology data is None, injecting placeholder")
+
+    # Filter out existing SystemMessage instances
+    non_system_messages = [
+        m for m in messages if not isinstance(m, SystemMessage)
+    ]
+
+    filtered_count = len(messages) - len(non_system_messages)
+    if filtered_count > 0:
+        logger.debug(
+            "Filtered out %d existing SystemMessage(s)", filtered_count
+        )
+
+    return [SystemMessage(content=formatted_prompt)] + non_system_messages
+
+
+# ============================================================================
+# Legacy Compatibility (Deprecated)
+# ============================================================================
+
+
+def prepare_context_messages(
+    state_messages: list[Any],
+    system_prompt: str,
+    topology_context: str | None = None,
+    model_name: str = "gpt-4o",
+    llm_config: dict[str, Any] | None = None,
+    tools: list[Any] | None = None,
+) -> list[Any]:
+    """
+    **DEPRECATED**: Use create_pre_model_hook() instead.
+    """
+    warnings.warn(
+        "prepare_context_messages() is deprecated. Use "
+        "create_pre_model_hook() instead.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+
+    if "{{topology_info}}" not in system_prompt:
+        formatted_prompt = system_prompt
+    elif topology_context:
+        formatted_prompt = system_prompt.replace(
+            "{{topology_info}}", f"\n\n## Current Topology\n{topology_context}"
+        )
+    else:
+        formatted_prompt = system_prompt.replace(
+            "{{topology_info}}", "(No topology information available)"
+        )
+
+    return [SystemMessage(content=formatted_prompt)] + state_messages
+
+
+# ============================================================================
+# Module Test
+# ============================================================================
+
+if __name__ == "__main__":
+    from langchain_core.messages import HumanMessage
+
+    print("=== Context Manager Module Test ===\n")
+
+    # Test token counting
+    print("Test 1: Token Counting")
+    print("  tiktoken encoding: cl100k_base")
+
+    test_text = "Hello world 你好世界"
+    tokens = count_tokens(test_text)
+    print(f"  '{test_text}' → {tokens} tokens")
+
+    # Test hook creation
+    print("\nTest 2: Create pre_model_hook")
+    system_prompt = "You are GNS3 Copilot.\n\n{{topology_info}}"
+
+    def mock_get_topology(state):
+        return {"project_id": "test", "nodes": 5}
+
+    def mock_get_config():
+        return {"context_limit": 8, "context_strategy": "conservative"}
+
+    def mock_get_tools():
+        return []  # No tools for test
+
+    hook = create_pre_model_hook(
+        system_prompt=system_prompt,
+        get_topology_func=mock_get_topology,
+        get_llm_config_func=mock_get_config,
+        get_tools_func=mock_get_tools,
+    )
+    print("✓ pre_model_hook created successfully")
+
+    # Test invocation
+    print("\nTest 3: Invoke pre_model_hook")
+    test_state = {
+        "messages": [
+            HumanMessage(f"Message {i}: {'x' * 50}") for i in range(5)
+        ],
+        "topology_info": {"project_id": "test123", "nodes": 3},
+    }
+
+    result = hook(test_state)
+    print(f"✓ Hook invoked: {len(result['messages'])} messages returned")
+
+    print("\n=== All Tests Passed ===")

gns3server/agent/gns3_copilot/agent/gns3_copilot.py

@@ -0,0 +1,715 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# GNS3-Copilot - AI-powered Network Lab Assistant for GNS3
+#
+# This file is part of GNS3-Copilot project.
+#
+# GNS3-Copilot is free software: you can redistribute it and/or modify it
+# under the terms of the GNU General Public License as published by the
+# Free Software Foundation, either version 3 of the License, or (at your
+# option) any later version.
+#
+# GNS3-Copilot is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+# or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+# for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with GNS3-Copilot. If not, see <https://www.gnu.org/licenses/>.
+#
+# Copyright (C) 2025 Yue Guobin (岳国宾)
+# Author: Yue Guobin (岳国宾)
+#
+# Project Home: https://github.com/yueguobin/gns3-copilot
+#
+
+# mypy: ignore-errors
+
+"""
+GNS3 Network Automation Assistant - LangGraph Agent
+
+This module implements the core LangGraph agent workflow for GNS3-Copilot,
+an AI-powered assistant for GNS3 network automation and management.
+
+The agent provides:
+- LangGraph-based state management and workflow
+- Mode-aware tool orchestration for GNS3 operations
+- Context-aware conversation handling
+- Automatic conversation title generation
+- Integration with GNS3 topology management
+
+Copilot Modes:
+- "teaching_assistant" (default): Diagnostic tools only, no configuration
+  changes
+- "lab_automation_assistant": Full diagnostic and configuration tools
+
+"""
+
+# Standard library imports
+import json
+import logging
+import operator
+from datetime import datetime
+from typing import Annotated
+from typing import Literal
+
+# Third-party imports
+from langchain.messages import AnyMessage
+from langchain.messages import SystemMessage
+from langchain.messages import ToolMessage
+from langchain_core.runnables import RunnableConfig
+from langgraph.graph import END
+from langgraph.graph import START
+from langgraph.graph import StateGraph
+from langgraph.managed.is_last_step import RemainingSteps
+from typing_extensions import TypedDict
+
+# Local imports
+from gns3server.agent.gns3_copilot.agent.context_manager import (
+    create_pre_model_hook,
+)
+from gns3server.agent.gns3_copilot.agent.model_factory import (
+    create_base_model_with_tools,
+)
+from gns3server.agent.gns3_copilot.agent.model_factory import (
+    create_title_model,
+)
+from gns3server.agent.gns3_copilot.gns3_client import GNS3TopologyTool
+from gns3server.agent.gns3_copilot.gns3_client.context_helpers import (
+    get_current_llm_config,
+)
+from gns3server.agent.gns3_copilot.prompts import load_system_prompt
+from gns3server.agent.gns3_copilot.skills.registry import get_prompt
+from gns3server.agent.gns3_copilot.tools_v2 import (
+    ExecuteMultipleDeviceCommands,
+)
+from gns3server.agent.gns3_copilot.tools_v2 import (
+    ExecuteMultipleDeviceConfigCommands,
+)
+from gns3server.agent.gns3_copilot.tools_v2 import GNS3CreateNodeTool
+from gns3server.agent.gns3_copilot.tools_v2 import GNS3LinkTool
+from gns3server.agent.gns3_copilot.tools_v2 import GNS3PacketFilterTool
+from gns3server.agent.gns3_copilot.tools_v2 import GNS3StartNodeTool
+from gns3server.agent.gns3_copilot.tools_v2 import GNS3StopNodeTool
+from gns3server.agent.gns3_copilot.tools_v2 import GNS3SuspendNodeTool
+from gns3server.agent.gns3_copilot.tools_v2 import GNS3TemplateTool
+from gns3server.agent.gns3_copilot.tools_v2 import GNS3UpdateNodeNameTool
+from gns3server.agent.gns3_copilot.tools_v2.vpcs_tools_netmiko import VPCSCommands
+from gns3server.agent.gns3_copilot.tools_v2 import PacketAnalysisTool
+from gns3server.agent.gns3_copilot.skills import DeviceSkillsTool
+from gns3server.agent.gns3_copilot.skills import InjectionSkillsTool
+from gns3server.agent.gns3_copilot.skills import PacketAnalysisSkillsTool
+
+# Set up logger for GNS3-Copilot
+logger = logging.getLogger(__name__)
+
+# Note: LLM model configuration is now managed by the new llm_model_configs
+# system. The model_factory module handles model creation with configuration
+# from the database.
+
+# Define tools for different copilot modes
+# Teaching assistant mode: READ-ONLY diagnostic tools only
+TEACHING_ASSISTANT_MODE_TOOLS = [
+    GNS3TemplateTool(),  # Get GNS3 node templates
+    GNS3CreateNodeTool(),  # Create new nodes in GNS3
+    GNS3LinkTool(),  # Create links between nodes
+    GNS3StartNodeTool(),  # Start GNS3 nodes
+    GNS3UpdateNodeNameTool(),  # Update node name
+    ExecuteMultipleDeviceCommands(),  # Execute show/display/debug commands
+    # (READ-ONLY)
+    PacketAnalysisTool(),  # Protocol-oriented packet analysis with tshark
+    PacketAnalysisSkillsTool(),  # Query packet analysis protocol definitions
+    DeviceSkillsTool(),  # Get device-specific skills and command knowledge
+]
+
+# Lab automation assistant mode: Full diagnostic AND configuration tools
+LAB_AUTOMATION_ASSISTANT_MODE_TOOLS = [
+    GNS3TemplateTool(),  # Get GNS3 node templates
+    GNS3CreateNodeTool(),  # Create new nodes in GNS3
+    GNS3LinkTool(),  # Create links between nodes
+    GNS3StartNodeTool(),  # Start GNS3 nodes
+    GNS3StopNodeTool(),  # Stop GNS3 nodes
+    GNS3SuspendNodeTool(),  # Suspend GNS3 nodes (preserve state)
+    GNS3UpdateNodeNameTool(),  # Update node name
+    ExecuteMultipleDeviceCommands(),  # Execute show/display/debug commands
+    # (READ-ONLY)
+    ExecuteMultipleDeviceConfigCommands(),  # Execute configuration commands
+    VPCSCommands(),  # Execute VPCS commands using Netmiko
+    PacketAnalysisTool(),  # Protocol-oriented packet analysis with tshark
+    PacketAnalysisSkillsTool(),  # Query packet analysis protocol definitions
+    DeviceSkillsTool(),  # Get device-specific skills and command knowledge
+]
+
+# Troubleshooting injection mode: Tools for injecting network faults
+# Focused on configuration commands and injection skills for fault injection
+TROUBLESHOOTING_INJECTION_MODE_TOOLS = [
+    ExecuteMultipleDeviceCommands(),  # Get device configurations (READ-ONLY)
+    ExecuteMultipleDeviceConfigCommands(),  # Inject configuration changes
+    GNS3PacketFilterTool(),  # Manage packet filters on links (delay, loss, corrupt, etc.)
+    InjectionSkillsTool(),  # Query injection skills and fault types
+    GNS3TopologyTool(),  # Get topology information
+]
+
+# Default tools (legacy support - will be overridden by mode-specific tools)
+tools = LAB_AUTOMATION_ASSISTANT_MODE_TOOLS
+
+# Create combined tool lookup for tool_node (supports all modes)
+# tool_node will receive tool calls based on mode-specific tools bound to the
+# model
+# Combine all tools from all modes and deduplicate by tool name
+ALL_TOOLS = LAB_AUTOMATION_ASSISTANT_MODE_TOOLS
+tools_by_name = {tool.name: tool for tool in ALL_TOOLS}
+
+# Add troubleshooting injection tools to the global tool registry
+for tool in TROUBLESHOOTING_INJECTION_MODE_TOOLS:
+    if tool.name not in tools_by_name:
+        tools_by_name[tool.name] = tool
+
+# Log application startup
+logger.info("GNS3-Copilot application starting up")
+
+# Constants for conversation title management
+DEFAULT_CONVERSATION_TITLE = "New Conversation"
+UNTITLED_SESSION_FALLBACK = "Untitled Session"
+TITLE_MAX_LENGTH = 40
+
+# Abort flags storage for session-level abort tracking
+# This is checked by conditional edge functions to stop the graph
+_abort_flags: dict[str, bool] = {}
+
+
+def check_abort_flag(session_id: str) -> bool:
+    """
+    Check if abort flag is set for a session.
+
+    Args:
+        session_id: Session identifier
+
+    Returns:
+        True if abort is requested, False otherwise
+    """
+    return _abort_flags.get(session_id, False)
+
+
+def set_abort_flag(session_id: str):
+    """
+    Set abort flag for a session.
+
+    Args:
+        session_id: Session identifier
+    """
+    _abort_flags[session_id] = True
+    logger.debug("Abort flag set for session: %s", session_id)
+
+
+def clear_abort_flag(session_id: str):
+    """
+    Clear abort flag for a session.
+
+    Args:
+        session_id: Session identifier
+    """
+    _abort_flags[session_id] = False
+    logger.debug("Abort flag cleared for session: %s", session_id)
+
+
+# Define state
+class MessagesState(TypedDict):
+    """
+    GNS3-Copilot conversation state management class.
+
+    Maintains the conversation state for the LangGraph workflow, including
+    message history, call counters, and session titles for comprehensive
+    dialogue management.
+
+    Attributes:
+        messages: List of conversation messages with cumulative updates using
+                 operator.add
+        llm_calls: Counter for tracking the number of LLM invocations
+        remaining_steps: Is automatically managed by LangGraph's RemainingSteps
+                       to track and limit recursion depth.
+        conversation_title: Optional conversation title for session
+                          identification and management
+        topology_info: Dictionary containing GNS3 project topology information
+        session_id: Session identifier for abort tracking
+        abort: Flag to signal abort request
+    """
+
+    messages: Annotated[list[AnyMessage], operator.add]
+
+    llm_calls: int
+
+    remaining_steps: RemainingSteps
+
+    # Optional conversation title
+    conversation_title: str | None
+
+    # Store GNS3 topology information
+    topology_info: dict | None
+
+    # Session identifier for abort tracking
+    session_id: str | None
+
+    # Abort flag to signal stop request
+    abort: bool
+
+
+# Define llm call  node
+def llm_call(state: dict, config: RunnableConfig | None = None):
+    """
+    LLM decides whether to call a tool or not.
+
+    Uses pre_model_hook pattern for automatic topology injection and
+    message trimming, ensuring separation of concerns and complete
+    history preservation in state["messages"].
+    """
+
+    logger.debug("LLM call node invoked")
+
+    # Get llm_config from request-scoped context variable
+    llm_config = get_current_llm_config()
+
+    if not llm_config:
+        logger.error("LLM config not found in context")
+        return {
+            "messages": [],
+            "llm_calls": state.get("llm_calls", 0),
+            "topology_info": None,
+        }
+
+    logger.debug(
+        "LLM config retrieved from context: provider=%s, model=%s",
+        llm_config.get("provider"),
+        llm_config.get("model"),
+    )
+
+    # Defensive check: skip LLM call if no user messages
+    messages = state.get("messages", [])
+    if not messages or len(messages) == 0:
+        logger.warning("No messages in state, skipping LLM call")
+        return {
+            "messages": [],
+            "llm_calls": state.get("llm_calls", 0),
+            "topology_info": None,
+        }
+
+    # Get project_id from config configurable (set when starting the chat)
+    project_id = None
+    topology_info = None
+    if config and config.get("configurable"):
+        project_id = config["configurable"].get("project_id")
+
+    # Retrieve topology information if available
+    if project_id:
+        try:
+            topology_tool = GNS3TopologyTool()
+            topology = topology_tool._run(project_id=project_id)
+
+            if topology and "error" not in topology:
+                topology_info = topology
+                logger.info(
+                    "Successfully retrieved topology for project_id: %s, "
+                    "name: %s",
+                    project_id,
+                    topology.get("name"),
+                )
+            else:
+                logger.warning(
+                    "Failed to retrieve topology for project_id %s: %s",
+                    project_id,
+                    topology.get("error", "Unknown error")
+                    if topology
+                    else "No result",
+                )
+        except Exception as e:
+            logger.warning(
+                "Error retrieving topology for project_id %s: %s",
+                project_id,
+                e,
+            )
+
+    # Store topology_info in state for pre_model_hook to access
+    state["topology_info"] = topology_info
+
+    # Select tools based on copilot_mode
+    copilot_mode = llm_config.get("copilot_mode", "teaching_assistant").lower()
+    if copilot_mode == "lab_automation_assistant":
+        mode_tools = LAB_AUTOMATION_ASSISTANT_MODE_TOOLS
+        logger.info(
+            "Using LAB_AUTOMATION_ASSISTANT mode tools (includes "
+            "configuration tools)"
+        )
+    elif copilot_mode == "troubleshooting_injection":
+        mode_tools = TROUBLESHOOTING_INJECTION_MODE_TOOLS
+        logger.info(
+            "Using TROUBLESHOOTING_INJECTION mode tools (fault injection)"
+        )
+    else:  # teaching_assistant mode (default)
+        mode_tools = TEACHING_ASSISTANT_MODE_TOOLS
+        logger.info(
+            "Using TEACHING_ASSISTANT mode tools (diagnostic tools only)"
+        )
+
+    # Create pre_model_hook for automatic topology injection and trimming
+    # Load system prompt based on copilot_mode configuration
+    system_prompt = load_system_prompt(llm_config)
+    pre_hook = create_pre_model_hook(
+        system_prompt=system_prompt,
+        get_topology_func=lambda s: s.get("topology_info"),
+        get_llm_config_func=get_current_llm_config,
+        get_tools_func=lambda: mode_tools,  # Pass mode-specific tools for
+        # token estimation
+    )
+
+    # Create fresh model with tools for each LLM call
+    logger.debug(
+        "Creating model with tools: provider=%s, model=%s, mode=%s, tools=%d",
+        llm_config.get("provider"),
+        llm_config.get("model"),
+        copilot_mode,
+        len(mode_tools),
+    )
+    model_with_tools = create_base_model_with_tools(
+        mode_tools, llm_config=llm_config
+    )
+
+    # Call pre_hook directly to prepare messages (topology injection +
+    # trimming)
+    # Note: LangGraph's pre_model_hook only works with prebuilt agents, not
+    # custom StateGraph
+    logger.debug("Calling pre_hook to prepare %d messages", len(messages))
+    prepared_state = pre_hook(
+        {"messages": messages, "topology_info": topology_info}
+    )
+    prepared_messages = prepared_state["messages"]
+    logger.info(
+        "Messages prepared: %d → %d", len(messages), len(prepared_messages)
+    )
+
+    # Invoke model with prepared messages
+    response = model_with_tools.invoke(prepared_messages)
+
+    # Add metadata with created_at timestamp to AI response
+    if hasattr(response, "metadata"):
+        existing_metadata = response.metadata or {}
+        response.metadata = {
+            **existing_metadata,
+            "created_at": datetime.utcnow().isoformat(),
+        }
+    else:
+        # LangChain messages should have metadata attribute, but defensive
+        # fallback
+        try:
+            response.metadata = {"created_at": datetime.utcnow().isoformat()}
+        except Exception:
+            logger.warning("Could not add metadata to AI response")
+
+    logger.info(
+        "LLM call completed: tool_calls=%d",
+        len(response.tool_calls) if hasattr(response, "tool_calls") else 0,
+    )
+
+    return {
+        "messages": [response],
+        "llm_calls": state.get("llm_calls", 0) + 1,
+        "topology_info": topology_info,
+        "session_id": state.get("session_id"),
+    }
+
+
+# Define generate title node
+def generate_title(
+    state: MessagesState, config: RunnableConfig | None = None
+) -> dict:
+    """
+    Generate a conversation title using a lightweight assistant LLM
+    (title_model). This node is only executed when no title has been set yet
+    (first round only).
+    """
+
+    # Get llm_config from request-scoped context variable
+    llm_config = get_current_llm_config()
+
+    if not llm_config:
+        logger.error("LLM config not found in context, cannot generate title")
+        return {"conversation_title": UNTITLED_SESSION_FALLBACK, "session_id": state.get("session_id")}
+
+    # Only generate a title if it hasn't been set yet
+    current_title = state.get("conversation_title")
+    if current_title in [None, "New Conversation"]:
+        logger.debug("Title generation triggered for session")
+        messages = state["messages"]
+
+        # Load title prompt from external repository
+        title_prompt = get_prompt("title")
+        if not title_prompt:
+            logger.error("Title prompt not found in external repository")
+            return {"conversation_title": UNTITLED_SESSION_FALLBACK, "session_id": state.get("session_id")}
+
+        # Build the prompt for title generation
+        title_prompt_messages = [
+            SystemMessage(content=title_prompt),
+            messages[0],  # User's first message
+            messages[-1],  # Assistant's final response in this turn
+        ]
+
+        # Call the title generation model (create fresh instance for each call)
+        try:
+            title_model = create_title_model(llm_config=llm_config)
+            response = title_model.invoke(
+                title_prompt_messages,
+                config={"configurable": {"foo_temperature": 1.0}},
+            )
+            raw_content = response.content
+
+            new_title = raw_content.strip()
+
+            # Validate the generated title
+            if not new_title or len(new_title) < 3:
+                raise ValueError(
+                    f"Generated title too short or empty: '{new_title}'"
+                )
+
+            if new_title in [
+                "New Conversation",
+                "Untitled Session",
+                "GNS3 Session",
+            ]:
+                raise ValueError(
+                    f"Generated title is a default value: '{new_title}'"
+                )
+
+            # Safety: truncate long titles and avoid line breaks
+            if len(new_title) > TITLE_MAX_LENGTH:
+                new_title = new_title[: TITLE_MAX_LENGTH - 2] + "..."
+
+            # Remove unwanted characters
+            new_title = (
+                new_title.replace("\n", " ").replace('"', "").replace("'", "")
+            )
+
+            logger.debug("Generated new title: %s", new_title)
+            return {"conversation_title": new_title, "session_id": state.get("session_id")}
+
+        except Exception as e:
+            logger.error(f"Title generation failed: {e}, using fallback")
+
+            # Improved fallback: Use user's first message content
+            if messages and len(messages) > 0:
+                first_message = messages[0]
+                if hasattr(first_message, "content"):
+                    fallback_title = first_message.content[:30].strip()
+                    # Remove newlines and extra spaces
+                    fallback_title = fallback_title.replace("\n", " ").strip()
+                    # Collapse multiple spaces
+                    while "  " in fallback_title:
+                        fallback_title = fallback_title.replace("  ", " ")
+
+                    # Truncate if needed
+                    if len(fallback_title) > 28:
+                        fallback_title = fallback_title[:28] + ".."
+
+                    if fallback_title:
+                        logger.info(
+                            "Using fallback title from user message: '%s'",
+                            fallback_title,
+                        )
+                        return {"conversation_title": fallback_title, "session_id": state.get("session_id")}
+
+            # Final fallback
+            logger.info(
+                "Using final fallback title: '%s'",
+                UNTITLED_SESSION_FALLBACK,
+            )
+            return {"conversation_title": UNTITLED_SESSION_FALLBACK, "session_id": state.get("session_id")}
+
+    # Title already exists → no update needed
+    return {}
+
+
+# Define tool node
+def tool_node(state: dict, config: RunnableConfig | None = None):
+    """Performs the tool call"""
+
+    tool_calls = state["messages"][-1].tool_calls
+    logger.debug("Tool node invoked: tool_calls=%d", len(tool_calls))
+
+    result = []
+    for tool_call in tool_calls:
+        tool_name = tool_call["name"]
+        logger.debug(
+            "Executing tool: %s with args: %s", tool_name, tool_call["args"]
+        )
+        tool = tools_by_name[tool_name]
+        try:
+            observation = tool.invoke(tool_call["args"])
+            logger.debug(
+                "Tool %s completed: output_length=%d",
+                tool_name,
+                len(str(observation)) if observation else 0,
+            )
+        except Exception as e:
+            logger.error("Tool %s failed: %s", tool_name, e, exc_info=True)
+            observation = f"Error: {str(e)}"
+
+        # Serialize observation to JSON string if it's not already a string
+        # This ensures ToolMessage.content is always JSON format, not Python
+        # str()
+        if not isinstance(observation, str):
+            observation = json.dumps(observation, ensure_ascii=False, indent=2)
+
+        # Create ToolMessage with metadata including created_at
+        tool_msg = ToolMessage(
+            content=observation,
+            tool_call_id=tool_call["id"],
+            name=tool_call["name"],
+            metadata={"created_at": datetime.utcnow().isoformat()},
+        )
+        result.append(tool_msg)
+
+    return {"messages": result, "session_id": state.get("session_id")}
+
+
+# Abort handler node - provides tool results when aborting
+def abort_handler_node(state: dict) -> dict:
+    """
+    Handles abort by providing tool result messages for pending tool_calls.
+    This ensures message history consistency and prevents checkpoint corruption.
+    """
+    messages = state.get("messages", [])
+    if not messages:
+        return {"session_id": state.get("session_id")}
+
+    last_message = messages[-1]
+    if not hasattr(last_message, "tool_calls") or not last_message.tool_calls:
+        return {"session_id": state.get("session_id")}
+
+    result = []
+    for tool_call in last_message.tool_calls:
+        tool_msg = ToolMessage(
+            content=json.dumps({
+                "status": "aborted",
+                "message": "Tool execution was aborted by user",
+                "tool_call_id": tool_call["id"],
+            }),
+            tool_call_id=tool_call["id"],
+            name=tool_call["name"],
+            metadata={"created_at": datetime.utcnow().isoformat(), "aborted": True},
+        )
+        result.append(tool_msg)
+
+    logger.info("Abort handler: generated %d aborted tool messages", len(result))
+    return {"messages": result, "session_id": state.get("session_id")}
+
+
+# Routing logic after the LLM node
+def should_continue(
+    state: MessagesState,
+) -> Literal["tool_node", "title_generator_node", "abort_handler_node", END]:
+    """
+    Determine the next step after the LLM has produced a response.
+
+    - If abort flag is set → end the conversation
+    - If the LLM requested any tool calls → route to tool_node
+    - If this is the first complete turn (llm_calls == 1) and no title
+      exists → generate a title
+    - Otherwise → conversation is complete, go to END
+    """
+    # Check abort flag first
+    session_id = state.get("session_id")
+    if session_id and check_abort_flag(session_id):
+        last_message = state["messages"][-1]
+        # If there's a tool_calls message, we need to handle it properly
+        if hasattr(last_message, "tool_calls") and last_message.tool_calls:
+            return "abort_handler_node"
+        return END
+
+    last_message = state["messages"][-1]
+    current_title = state.get("conversation_title")
+
+    # LLM requested one or more tool executions
+    if last_message.tool_calls:
+        return "tool_node"
+
+    # First full interaction completed and title not yet generated
+    if current_title in [None, "New Conversation"]:
+        return "title_generator_node"
+
+    # Normal completion (multi-turn conversation or title already exists)
+    return END
+
+
+# Routing logic after the tool node, Check remaining_steps
+def recursion_limit_continue(state: MessagesState) -> Literal["llm_call", END]:
+    """
+    Routing logic after tool execution to prevent infinite recursion.
+
+    Determines whether to continue with another LLM call or end the
+    conversation based on remaining steps and message type.
+
+    Args:
+        state: Current conversation state with messages and remaining steps
+
+    Returns:
+        "llm_call" to continue processing, END to terminate conversation
+
+    Logic:
+        - If abort flag is set → end the conversation
+        - If the last message is ToolMessage and steps >= 4: continue to LLM
+        - Otherwise: end the conversation to prevent infinite loops
+    """
+    # Check abort flag first
+    session_id = state.get("session_id")
+    if session_id and check_abort_flag(session_id):
+        return END
+
+    last_message = state["messages"][-1]
+    if isinstance(last_message, ToolMessage):
+        if state["remaining_steps"] < 4:
+            return END
+        return "llm_call"
+
+    return END
+
+
+# Build and compile the agent
+# Build workflow
+agent_builder = StateGraph(MessagesState)
+
+# Add nodes
+agent_builder.add_node("llm_call", llm_call)
+agent_builder.add_node("tool_node", tool_node)
+agent_builder.add_node("title_generator_node", generate_title)
+agent_builder.add_node("abort_handler_node", abort_handler_node)
+
+# Add edges to connect nodes
+agent_builder.add_edge(START, "llm_call")
+# Conditional routing after LLM response
+# Determines the next step based on whether LLM needs to call tools or
+# generate title
+agent_builder.add_conditional_edges(
+    "llm_call",
+    should_continue,
+    {
+        "tool_node": "tool_node",  # Route to tool execution if LLM requested
+        # tools
+        "title_generator_node": "title_generator_node",  # Generate title on
+        # first interaction
+        "abort_handler_node": "abort_handler_node",  # Handle abort with tool calls
+        END: END,  # End conversation if no tools needed
+    },
+)
+# Conditional routing after tool execution
+# Prevents infinite recursion by checking remaining steps before continuing
+agent_builder.add_conditional_edges(
+    "tool_node",
+    recursion_limit_continue,
+    {
+        "llm_call": "llm_call",  # Continue to LLM if tools executed and steps
+        # remain
+        END: END,  # End conversation to prevent infinite loops
+    },
+)
+
+agent_builder.add_edge("title_generator_node", END)
+agent_builder.add_edge("abort_handler_node", END)

gns3server/agent/gns3_copilot/agent/model_factory.py

@@ -0,0 +1,258 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# GNS3-Copilot - AI-powered Network Lab Assistant for GNS3
+#
+# This file is part of GNS3-Copilot project.
+#
+# GNS3-Copilot is free software: you can redistribute it and/or modify it
+# under the terms of the GNU General Public License as published by the
+# Free Software Foundation, either version 3 of the License, or (at your
+# option) any later version.
+#
+# GNS3-Copilot is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+# or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+# for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with GNS3-Copilot. If not, see <https://www.gnu.org/licenses/>.
+#
+# Copyright (C) 2025 Yue Guobin (岳国宾)
+# Author: Yue Guobin (岳国宾)
+#
+# Project Home: https://github.com/yueguobin/gns3-copilot
+#
+
+"""
+Model Factory for GNS3-Copilot Agent
+
+This module provides factory functions to create fresh LLM model instances.
+Configuration is passed directly from the database.
+
+"""
+
+import logging
+from typing import Any
+from typing import Optional
+
+from langchain.chat_models import init_chat_model
+
+logger = logging.getLogger(__name__)
+
+
+def _load_llm_config(
+    llm_config: Optional[dict[str, Any]] = None,
+) -> dict[str, str]:
+    """
+    Convert llm_config dict to model factory format.
+
+    Args:
+        llm_config: Configuration dictionary from database
+
+    Returns:
+        Dictionary containing model configuration.
+
+    Raises:
+        ValueError: If configuration is missing or invalid.
+    """
+    if not llm_config:
+        raise ValueError("LLM configuration is required")
+
+    logger.info(
+        "Using LLM config: provider=%s, model=%s",
+        llm_config.get("provider"),
+        llm_config.get("model"),
+    )
+
+    return {
+        "model_name": llm_config.get("model", ""),
+        "model_provider": llm_config.get("provider", ""),
+        "api_key": llm_config.get("api_key", ""),
+        "base_url": llm_config.get("base_url", ""),
+        "temperature": str(llm_config.get("temperature", "0")),
+    }
+
+
+def create_base_model(
+    llm_config: Optional[dict[str, Any]] = None,
+) -> Any:
+    """
+    Create a fresh base LLM model instance.
+
+    Args:
+        llm_config: Configuration dictionary from database
+
+    Returns:
+        Any: A new LLM model instance configured with current settings.
+              The actual type depends on the provider (e.g., ChatOpenAI, etc.).
+
+    Raises:
+        ValueError: If required configuration fields are missing or invalid.
+        RuntimeError: If model creation fails.
+    """
+    config_vars = _load_llm_config(llm_config)
+
+    # Log the loaded configuration (mask sensitive data)
+    logger.info(
+        "Creating base model: name=%s, provider=%s, base_url=%s, "
+        "temperature=%s",
+        config_vars["model_name"],
+        config_vars["model_provider"],
+        config_vars["base_url"] if config_vars["base_url"] else "default",
+        config_vars["temperature"],
+    )
+
+    # Validate required fields
+    if not config_vars["model_name"]:
+        raise ValueError("LLM configuration requires 'model' field")
+
+    if not config_vars["model_provider"]:
+        raise ValueError("LLM configuration requires 'provider' field")
+
+    try:
+        # Prepare parameters for init_chat_model
+        init_params = {
+            "model": config_vars["model_name"],
+            "model_provider": config_vars["model_provider"],
+            "api_key": config_vars["api_key"],
+            "base_url": config_vars["base_url"],
+            "temperature": config_vars["temperature"],
+            "configurable_fields": "any",
+            "config_prefix": "foo",
+        }
+
+        # Disable DeepSeek thinking mode to avoid reasoning_content handling issues
+        # DeepSeek models enable thinking mode by default, which returns reasoning_content
+        # that must be passed back to the API in subsequent requests. To simplify
+        # message handling and avoid 400 errors, we disable it here.
+        if config_vars["model_provider"] == "deepseek":
+            init_params["extra_body"] = {"thinking": {"type": "disabled"}}
+            logger.debug("DeepSeek thinking mode disabled")
+
+        model = init_chat_model(**init_params)
+
+        logger.debug("Base model created successfully")
+        return model
+
+    except Exception as e:
+        logger.error("Failed to create base model: %s", e)
+        raise RuntimeError(f"Failed to create base model: {e}") from e
+
+
+def create_title_model(
+    llm_config: Optional[dict[str, Any]] = None,
+) -> Any:
+    """
+    Create a fresh title generation model instance.
+
+    This creates a model instance suitable for generating conversation titles.
+    It uses the same configuration as the base model but with a higher
+    temperature for more creative output.
+
+    Args:
+        llm_config: Configuration dictionary from database
+
+    Returns:
+        Any: A new LLM model instance for title generation.
+              The actual type depends on the provider.
+
+    Raises:
+        ValueError: If required configuration fields are missing or invalid.
+        RuntimeError: If model creation fails.
+    """
+    config_vars = _load_llm_config(llm_config)
+
+    logger.info(
+        "Creating title model: name=%s, provider=%s, base_url=%s, "
+        "temperature=1.0",
+        config_vars["model_name"],
+        config_vars["model_provider"],
+        config_vars["base_url"] if config_vars["base_url"] else "default",
+    )
+
+    # Validate required fields
+    if not config_vars["model_name"]:
+        raise ValueError("LLM configuration requires 'model' field")
+
+    if not config_vars["model_provider"]:
+        raise ValueError("LLM configuration requires 'provider' field")
+
+    try:
+        # Prepare parameters for init_chat_model
+        init_params = {
+            "model": config_vars["model_name"],
+            "model_provider": config_vars["model_provider"],
+            "api_key": config_vars["api_key"],
+            "base_url": config_vars["base_url"],
+            "temperature": "1.0",  # Higher temperature for more creative titles
+            "configurable_fields": "any",
+            "config_prefix": "foo",
+        }
+
+        # Disable DeepSeek thinking mode to avoid reasoning_content handling issues
+        # DeepSeek models enable thinking mode by default, which returns reasoning_content
+        # that must be passed back to the API in subsequent requests. To simplify
+        # message handling and avoid 400 errors, we disable it here.
+        if config_vars["model_provider"] == "deepseek":
+            init_params["extra_body"] = {"thinking": {"type": "disabled"}}
+            logger.debug("DeepSeek thinking mode disabled for title model")
+
+        model = init_chat_model(**init_params)
+
+        logger.debug("Title model created successfully")
+        return model
+
+    except Exception as e:
+        logger.error("Failed to create title model: %s", e)
+        raise RuntimeError(f"Failed to create title model: {e}") from e
+
+
+def create_model_with_tools(
+    model: Any,
+    tools: list[Any],
+) -> Any:
+    """
+    Bind tools to a model instance.
+
+    Args:
+        model: The base model instance.
+        tools: List of tools to bind to the model.
+
+    Returns:
+        Any: A model instance with tools bound (type varies by provider).
+
+    Raises:
+        RuntimeError: If tool binding fails.
+    """
+    try:
+        model_with_tools = model.bind_tools(tools)
+        logger.debug("Model bound with %d tools successfully", len(tools))
+        return model_with_tools
+    except Exception as e:
+        logger.error("Failed to bind tools to model: %s", e)
+        raise RuntimeError(f"Failed to bind tools to model: {e}") from e
+
+
+def create_base_model_with_tools(
+    tools: list[Any],
+    llm_config: Optional[dict[str, Any]] = None,
+) -> Any:
+    """
+    Create a fresh base model instance with tools bound.
+
+    This is a convenience function that combines creating the base model
+    and binding tools to it.
+
+    Args:
+        tools: List of tools to bind to the model.
+        llm_config: Configuration dictionary from database
+
+    Returns:
+        Any: A new model instance with tools bound (type varies by provider).
+
+    Raises:
+        ValueError: If required configuration fields are missing.
+        RuntimeError: If model creation or tool binding fails.
+    """
+    base_model = create_base_model(llm_config)
+    return create_model_with_tools(base_model, tools)

gns3server/agent/gns3_copilot/agent_service.py

@@ -0,0 +1,782 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# GNS3-Copilot - AI-powered Network Lab Assistant for GNS3
+#
+# This file is part of GNS3-Copilot project.
+#
+# GNS3-Copilot is free software: you can redistribute it and/or modify it
+# under the terms of the GNU General Public License as published by the
+# Free Software Foundation, either version 3 of the License, or (at your
+# option) any later version.
+#
+# GNS3-Copilot is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+# or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+# for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with GNS3-Copilot. If not, see <https://www.gnu.org/licenses/>.
+#
+# Copyright (C) 2025 Yue Guobin (岳国宾)
+# Author: Yue Guobin (岳国宾)
+#
+# Project Home: https://github.com/yueguobin/gns3-copilot
+#
+"""
+
+GNS3 Copilot Agent Service
+
+Provides project-level Agent instances with SQLite checkpoint management.
+Each project has its own AgentService with a dedicated checkpoint database
+in the project directory.
+"""
+
+import asyncio
+import json
+import logging
+import os
+from datetime import datetime
+from typing import Any
+from typing import AsyncGenerator
+from typing import Dict
+from typing import List
+from typing import Optional
+from uuid import uuid4
+
+import aiosqlite
+from langchain_core.messages import HumanMessage
+from langgraph.checkpoint.sqlite.aio import AsyncSqliteSaver
+
+from gns3server.agent.gns3_copilot.agent.gns3_copilot import agent_builder
+from gns3server.agent.gns3_copilot.chat_sessions_repository import (
+    ChatSessionsRepository,
+)
+from gns3server.agent.gns3_copilot.gns3_client.context_helpers import (
+    set_current_jwt_token,
+)
+from gns3server.agent.gns3_copilot.gns3_client.context_helpers import (
+    set_current_llm_config,
+)
+from gns3server.agent.gns3_copilot.utils.error_handler import format_error_message
+from gns3server.agent.gns3_copilot.utils.message_converters import (
+    convert_langchain_to_openai,
+)
+from gns3server.agent.gns3_copilot.utils.tool_call_stream import (
+    ToolCallStreamAccumulator,
+)
+
+log = logging.getLogger(__name__)
+
+
+class AgentService:
+    """
+    Project-level Agent Service with async checkpoint management.
+
+    Manages a LangGraph agent instance with SQLite-based state persistence
+    for a single GNS3 project.
+    """
+
+    def __init__(self, project_path: str):
+        """
+        Initialize AgentService for a project.
+
+        Args:
+            project_path: Path to the GNS3 project directory
+        """
+        self.project_path = project_path
+        self._checkpointer: Optional[AsyncSqliteSaver] = None
+        self._checkpointer_conn: Optional[aiosqlite.Connection] = None
+        self._checkpointer_path: Optional[str] = None
+        self._graph = None
+        self._init_lock = asyncio.Lock()
+        self._initialized = False
+
+    def abort_session(self, session_id: str):
+        """
+        Signal abort for a session.
+
+        Args:
+            session_id: Session identifier
+        """
+        from gns3server.agent.gns3_copilot.agent.gns3_copilot import (
+            set_abort_flag,
+        )
+
+        set_abort_flag(session_id)
+        log.info("Abort signal set for session: %s", session_id)
+
+    def _get_checkpoint_dir(self) -> str:
+        """Get or create the checkpoint directory for this project."""
+        checkpoint_dir = os.path.join(self.project_path, "gns3-copilot")
+        os.makedirs(checkpoint_dir, exist_ok=True)
+        return checkpoint_dir
+
+    async def _get_checkpointer(self) -> AsyncSqliteSaver:
+        """
+        Get or create the SQLite checkpointer for this project.
+
+        Returns:
+            AsyncSqliteSaver instance
+        """
+        async with self._init_lock:
+            if self._checkpointer is not None:
+                return self._checkpointer
+
+            checkpoint_dir = self._get_checkpoint_dir()
+            checkpointer_path = os.path.join(
+                checkpoint_dir, "copilot_checkpoints.db"
+            )
+
+            log.debug("Creating checkpointer at: %s", checkpointer_path)
+
+            # Close existing connection if switching projects
+            if self._checkpointer_conn:
+                try:
+                    await self._checkpointer_conn.close()
+                    log.debug("Closed previous checkpointer connection")
+                except Exception as e:
+                    log.warning(
+                        "Error closing old checkpointer connection: %s", e
+                    )
+
+            # Create new connection
+            conn = await aiosqlite.connect(checkpointer_path)
+            # Enable WAL mode for better concurrent performance
+            await conn.execute("PRAGMA journal_mode=WAL;")
+            self._checkpointer_conn = (
+                conn  # Save connection reference to prevent GC
+            )
+            self._checkpointer = AsyncSqliteSaver(conn)
+
+            # CRITICAL: Initialize database schema
+            await self._checkpointer.setup()
+
+            # Create chat_sessions table in the same database
+            await self._create_chat_sessions_table(conn)
+
+            self._checkpointer_path = checkpointer_path
+            self._initialized = True
+
+            log.info("Project checkpointer created at: %s", checkpointer_path)
+            return self._checkpointer
+
+    async def _create_chat_sessions_table(self, conn: aiosqlite.Connection):
+        """
+        Create the chat_sessions table in the checkpoint database.
+
+        Args:
+            conn: aiosqlite connection
+        """
+        await conn.execute("""
+            CREATE TABLE IF NOT EXISTS chat_sessions (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                thread_id TEXT UNIQUE NOT NULL,
+                user_id TEXT NOT NULL,
+                project_id TEXT NOT NULL,
+                title TEXT DEFAULT 'New Conversation',
+
+                -- Statistics
+                message_count INTEGER DEFAULT 0,
+                llm_calls_count INTEGER DEFAULT 0,
+                input_tokens INTEGER DEFAULT 0,
+                output_tokens INTEGER DEFAULT 0,
+                total_tokens INTEGER DEFAULT 0,
+
+                -- Timestamps
+                last_message_at TIMESTAMP,
+                created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+                updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+
+                -- Reserved fields (JSON strings)
+                metadata TEXT DEFAULT '{}',
+                stats TEXT DEFAULT '{}',
+
+                -- Pin feature
+                pinned BOOLEAN DEFAULT FALSE
+            )
+        """)
+
+        # Create indexes
+        await conn.execute(
+            "CREATE INDEX IF NOT EXISTS idx_thread_id ON "
+            "chat_sessions(thread_id)"
+        )
+        await conn.execute(
+            "CREATE INDEX IF NOT EXISTS idx_user_project ON "
+            "chat_sessions(user_id, project_id)"
+        )
+
+        # Check if pinned column exists, add it if not (migration for existing
+        # databases)
+        cursor = await conn.execute("PRAGMA table_info(chat_sessions)")
+        columns = await cursor.fetchall()
+        column_names = [col[1] for col in columns]
+
+        if "pinned" not in column_names:
+            log.debug("Adding pinned column to existing chat_sessions table")
+            await conn.execute(
+                "ALTER TABLE chat_sessions ADD COLUMN pinned BOOLEAN DEFAULT "
+                "FALSE"
+            )
+            await conn.commit()
+
+        # Create pinned index (after column is guaranteed to exist)
+        await conn.execute(
+            "CREATE INDEX IF NOT EXISTS idx_pinned_updated ON "
+            "chat_sessions(pinned DESC, updated_at DESC)"
+        )
+
+        await conn.commit()
+        log.debug("chat_sessions table created in checkpoint database")
+
+    async def _get_graph(self):
+        """Get or compile the LangGraph agent."""
+        if self._graph is None:
+            checkpointer = await self._get_checkpointer()
+            self._graph = agent_builder.compile(checkpointer=checkpointer)
+            log.info(
+                "LangGraph agent compiled for project: %s", self.project_path
+            )
+        return self._graph
+
+    async def stream_chat(
+        self,
+        message: str,
+        session_id: str,
+        project_id: Optional[str] = None,
+        user_id: Optional[str] = None,
+        jwt_token: Optional[str] = None,
+        mode: str = "text",
+        llm_config: Optional[Dict[str, Any]] = None,
+    ) -> AsyncGenerator[Dict[str, Any], None]:
+        """
+        Stream chat responses from the agent.
+
+        Args:
+            message: User message
+            session_id: Session/thread ID for conversation continuity
+            project_id: GNS3 project ID (optional, for context)
+            user_id: User ID for metadata tracking
+            jwt_token: JWT token for API authentication (optional)
+            mode: Interaction mode (default: "text")
+            llm_config: LLM configuration dict (provider, model, api_key,
+                       etc.)
+
+        Yields:
+            Dict containing SSE-compatible response chunks
+        """
+        log.info(
+            "Stream chat started: project_id=%s, user_id=%s, session_id=%s, "
+            "mode=%s",
+            project_id,
+            user_id,
+            session_id,
+            mode,
+        )
+
+        # Ensure checkpointer is initialized
+        if not self._checkpointer_conn:
+            await self._get_checkpointer()
+
+        # Get or create chat session
+        repo = ChatSessionsRepository(self._checkpointer_conn)
+        session = await repo.get_session_by_thread(session_id)
+        is_new_session = session is None
+
+        if is_new_session:
+            # Create new session
+            copilot_mode = llm_config.get("copilot_mode", "teaching_assistant").lower()
+            session = await repo.create_session(
+                thread_id=session_id,
+                user_id=user_id or "",
+                project_id=project_id or "",
+                title="New Conversation",
+                copilot_mode=copilot_mode,
+            )
+            log.debug(
+                "Created new chat session: thread_id=%s, copilot_mode=%s",
+                session_id,
+                copilot_mode
+            )
+
+        # Set request-scoped context variables (memory-only, not persisted)
+        if jwt_token:
+            set_current_jwt_token(jwt_token)
+            log.debug("JWT token set in context")
+        if llm_config:
+            set_current_llm_config(llm_config)
+            log.debug(
+                "LLM config set in context: provider=%s, model=%s",
+                llm_config.get("provider"),
+                llm_config.get("model"),
+            )
+
+        # Build config - only thread-safe identifiers
+        # Determine recursion_limit based on copilot_mode
+        copilot_mode = llm_config.get("copilot_mode", "teaching_assistant").lower()
+        if copilot_mode == "troubleshooting_injection":
+            recursion_limit = 100  # Need more recursion depth for fault injection workflow
+            log.debug("Using extended recursion_limit for troubleshooting_injection mode: 100")
+        else:
+            recursion_limit = 25  # Default recursion limit
+
+        config = {
+            "configurable": {
+                "thread_id": session_id,
+                "project_id": project_id,
+            },
+            "metadata": {
+                "user_id": user_id,
+                "copilot_mode": copilot_mode,  # Store mode in checkpoint metadata
+            },
+            "recursion_limit": recursion_limit,
+        }
+
+        # Build inputs
+        # Determine remaining_steps based on copilot_mode
+        # Troubleshooting injection mode needs more steps for multi-tool workflow
+        if copilot_mode == "troubleshooting_injection":
+            remaining_steps = 50  # Need more steps for fault injection workflow
+            log.debug("Using extended remaining_steps for troubleshooting_injection mode: 50")
+        else:
+            remaining_steps = 20  # Default for other modes
+
+        inputs = {
+            "messages": [
+                HumanMessage(
+                    content=message,
+                    id=str(uuid4()),
+                    metadata={"created_at": datetime.utcnow().isoformat()},
+                )
+            ],
+            "llm_calls": 0,
+            "remaining_steps": remaining_steps,
+            "session_id": session_id,
+            "abort": False,
+        }
+
+        # Clear abort flag for this session at the start of stream
+        from gns3server.agent.gns3_copilot.agent.gns3_copilot import (
+            clear_abort_flag,
+        )
+
+        clear_abort_flag(session_id)
+        log.debug("Abort flag cleared for session: %s", session_id)
+
+        # Get the compiled graph
+        graph = await self._get_graph()
+        log.debug("LangGraph graph obtained, starting stream")
+
+        # Track statistics for session update
+        message_count = 1  # User message
+        llm_calls_count = 0
+        input_tokens = 0
+        output_tokens = 0
+        last_message_at = datetime.utcnow().isoformat()
+
+        # Track if we've counted the AI response for this turn
+        ai_response_counted = False
+        tool_messages_counted = 0
+
+        # Initialize tool call stream accumulator for handling progressive
+        # tool call arguments
+        tool_call_accumulator = ToolCallStreamAccumulator()
+
+        # Track if stream was aborted
+        stream_aborted = False
+
+        # Stream events
+        try:
+            async for event in graph.astream_events(
+                inputs, config=config, version="v2"
+            ):
+                event_type = event.get("event", "")
+                data = event.get("data", {})
+
+                # Track LLM calls and tokens
+                if event_type == "on_chat_model_start":
+                    # Filter out title_generator_node from statistics
+                    langgraph_node = event.get("metadata", {}).get(
+                        "langgraph_node", ""
+                    )
+                    if langgraph_node != "title_generator_node":
+                        llm_calls_count += 1
+                        log.debug(
+                            "LLM call started, count=%d", llm_calls_count
+                        )
+                    else:
+                        log.debug(
+                            "Skipping LLM call count for internal node: "
+                            "title_generator_node"
+                        )
+
+                elif event_type == "on_chat_model_end":
+                    # Filter out title_generator_node from token counting
+                    langgraph_node = event.get("metadata", {}).get(
+                        "langgraph_node", ""
+                    )
+                    if langgraph_node == "title_generator_node":
+                        log.debug(
+                            "Skipping token counting for internal node: "
+                            "title_generator_node"
+                        )
+                    else:
+                        # Extract token usage from response metadata
+                        # Try multiple possible locations where token usage
+                        # might be stored
+                        token_info_found = False
+
+                        # Method 1: response.usage_metadata
+                        response = data.get("response", {})
+                        if hasattr(response, "usage_metadata"):
+                            usage = response.usage_metadata
+                            if usage:
+                                input_tokens += usage.get("input_tokens", 0)
+                                output_tokens += usage.get("output_tokens", 0)
+                                token_info_found = True
+
+                        # Method 2: output.usage_metadata
+                        if not token_info_found:
+                            output_msg = data.get("output", {})
+                            if hasattr(output_msg, "usage_metadata"):
+                                usage = output_msg.usage_metadata
+                                if usage:
+                                    input_tokens += usage.get(
+                                        "input_tokens", 0
+                                    )
+                                    output_tokens += usage.get(
+                                        "output_tokens", 0
+                                    )
+                                    token_info_found = True
+
+                        # Method 3: Check data directly for token usage fields
+                        if not token_info_found:
+                            if "input_tokens" in data:
+                                input_tokens += data.get("input_tokens", 0)
+                            if "output_tokens" in data:
+                                output_tokens += data.get("output_tokens", 0)
+                            if (
+                                "input_tokens" in data
+                                or "output_tokens" in data
+                            ):
+                                token_info_found = True
+
+                        # Count AI response as one message (only once per turn)
+                        if not ai_response_counted:
+                            message_count += 1
+                            ai_response_counted = True
+
+                # Track tool messages
+                elif event_type == "on_tool_end":
+                    message_count += 1  # Tool result message
+                    tool_messages_counted += 1
+                    log.debug(
+                        "Tool message counted, message_count=%d", message_count
+                    )
+
+                # Convert event to chunk for SSE streaming
+                # Use accumulator for on_chat_model_stream events to handle
+                # progressive tool calls
+
+                # Filter out internal nodes (title_generator_node) from
+                # streaming to frontend
+                langgraph_node = event.get("metadata", {}).get(
+                    "langgraph_node", ""
+                )
+                if langgraph_node == "title_generator_node":
+                    # Skip all events from the title_generator_node (internal
+                    # use only)
+                    log.debug(
+                        "Skipping event from internal node: "
+                        "title_generator_node"
+                    )
+                    continue
+
+                if event_type == "on_chat_model_stream":
+                    chunks = tool_call_accumulator.process_event(event)
+                    for chunk in chunks:
+                        # Add session_id to each chunk
+                        chunk["session_id"] = session_id
+                        log.debug(
+                            "Yielding accumulated chunk: type=%s",
+                            chunk.get("type"),
+                        )
+                        yield chunk
+                else:
+                    # Use stateless converter for other events
+                    chunk = self._convert_event_to_chunk(event, session_id)
+                    if chunk:
+                        log.debug("Yielding chunk: type=%s", chunk.get("type"))
+                        yield chunk
+
+            # Check if stream was aborted and yield tool_end events for aborted tools
+            from gns3server.agent.gns3_copilot.agent.gns3_copilot import (
+                check_abort_flag,
+            )
+
+            if check_abort_flag(session_id):
+                log.info("Stream aborted, yielding tool_end events: session_id=%s", session_id)
+                # Get final state to find aborted tool messages
+                final_state = await graph.aget_state(config)
+                if final_state and "messages" in final_state.values:
+                    for msg in final_state.values["messages"]:
+                        # Check if this is an aborted tool message
+                        if hasattr(msg, "metadata") and msg.metadata.get("aborted"):
+                            yield {
+                                "type": "tool_end",
+                                "tool_name": getattr(msg, "name", "unknown"),
+                                "tool_output": msg.content if hasattr(msg, "content") else "",
+                                "session_id": session_id,
+                            }
+
+            # Update session statistics after successful stream
+            await repo.update_session(
+                thread_id=session_id,
+                message_count=message_count,
+                llm_calls_count=llm_calls_count,
+                input_tokens=input_tokens,
+                output_tokens=output_tokens,
+                total_tokens=input_tokens + output_tokens,
+                last_message_at=last_message_at,
+            )
+            log.info(
+                "Session statistics updated: thread_id=%s, messages=%d, "
+                "llm_calls=%d, tokens=%d+%d=%d",
+                session_id,
+                message_count,
+                llm_calls_count,
+                input_tokens,
+                output_tokens,
+                input_tokens + output_tokens,
+            )
+
+            # Sync auto-generated title from checkpoint state
+            final_state = await graph.aget_state(config)
+            if final_state and "conversation_title" in final_state.values:
+                generated_title = final_state.values["conversation_title"]
+                current_session = await repo.get_session_by_thread(session_id)
+                if (
+                    current_session
+                    and current_session.title != generated_title
+                ):
+                    await repo.update_session(
+                        thread_id=session_id, title=generated_title
+                    )
+                    log.info(
+                        "Auto-generated title synced: thread_id=%s, title=%s",
+                        session_id,
+                        generated_title,
+                    )
+
+        except Exception as e:
+            log.error("Error in stream_chat: %s", e, exc_info=True)
+            yield {
+                "type": "error",
+                "error": format_error_message(e),
+                "session_id": session_id,
+            }
+
+    def _convert_event_to_chunk(
+        self, event: Dict[str, Any], session_id: str
+    ) -> Optional[Dict[str, Any]]:
+        """
+        Convert LangGraph event to API response chunk.
+
+        Args:
+            event: LangGraph event from astream_events
+            session_id: Session ID for the response
+
+        Returns:
+            Dict for SSE response or None if event should be filtered
+
+        Note:
+            on_chat_model_stream events are handled by
+            ToolCallStreamAccumulator before calling this method, so they are
+            not processed here.
+        """
+        event_type = event.get("event", "")
+        data = event.get("data", {})
+
+        if event_type == "on_tool_start":
+            # Tool execution started
+            # Extract tool_call_id from event metadata to associate with
+            # tool_call event
+            tool_call_id = event.get("metadata", {}).get("tool_call_id", "")
+            return {
+                "type": "tool_start",
+                "tool_name": event.get("name", ""),
+                "tool_call_id": tool_call_id,
+                "session_id": session_id,
+            }
+
+        elif event_type == "on_tool_end":
+            # Tool execution completed
+            # Extract tool output and convert to JSON string
+            output = data.get("output", "")
+            # Convert output to JSON string if it's not already a string
+            # This ensures dict/list outputs are properly serialized for
+            # frontend parsing
+            if not isinstance(output, str):
+                output = json.dumps(output, ensure_ascii=False, indent=2)
+            return {
+                "type": "tool_end",
+                "tool_name": event.get("name", ""),
+                "tool_output": output,
+                "session_id": session_id,
+            }
+
+        return None
+
+    async def get_history(
+        self, session_id: str, limit: int = 100
+    ) -> Dict[str, Any]:
+        """
+        Get conversation history for a session.
+
+        Args:
+            session_id: Session/thread ID
+            limit: Maximum number of messages to retrieve
+
+        Returns:
+            Dict containing thread_id, title, and messages
+        """
+        config = {"configurable": {"thread_id": session_id}}
+
+        try:
+            graph = await self._get_graph()
+            state = await graph.aget_state(config)
+
+            if state and "messages" in state.values:
+                messages = []
+                for msg in state.values["messages"][-limit:]:
+                    messages.append(self._convert_message_to_dict(msg))
+
+                title = state.values.get(
+                    "conversation_title", "New Conversation"
+                )
+
+                return {
+                    "thread_id": session_id,
+                    "title": title,
+                    "messages": messages,
+                }
+        except Exception as e:
+            log.error("Error getting history: %s", e, exc_info=True)
+
+        return {
+            "thread_id": session_id,
+            "title": "New Conversation",
+            "messages": [],
+        }
+
+    def _convert_message_to_dict(self, msg) -> Dict[str, Any]:
+        """Convert a LangChain message to OpenAI-compatible dict format."""
+        return convert_langchain_to_openai(msg)
+
+    async def list_sessions(
+        self, user_id: Optional[str] = None, copilot_mode: Optional[str] = None, limit: int = 100
+    ) -> List[Dict[str, Any]]:
+        """
+        List chat sessions for this project.
+
+        Args:
+            user_id: Filter by user ID (optional)
+            copilot_mode: Filter by copilot mode (optional)
+            limit: Maximum number of sessions to return
+
+        Returns:
+            List of session dictionaries
+        """
+        if not self._checkpointer_conn:
+            await self._get_checkpointer()
+
+        repo = ChatSessionsRepository(self._checkpointer_conn)
+        sessions = await repo.list_sessions(user_id=user_id, copilot_mode=copilot_mode, limit=limit)
+        return [s.to_dict() for s in sessions]
+
+    async def delete_session(self, session_id: str) -> bool:
+        """
+        Delete a chat session and its checkpoints.
+
+        Args:
+            session_id: Thread ID to delete
+
+        Returns:
+            True if deleted, False if not found
+        """
+        if not self._checkpointer_conn:
+            await self._get_checkpointer()
+
+        repo = ChatSessionsRepository(self._checkpointer_conn)
+        return await repo.delete_session(session_id)
+
+    async def rename_session(
+        self, session_id: str, new_title: str
+    ) -> Optional[Dict[str, Any]]:
+        """
+        Rename a chat session.
+
+        Args:
+            session_id: Thread ID
+            new_title: New title
+
+        Returns:
+            Updated session dictionary or None
+        """
+        if not self._checkpointer_conn:
+            await self._get_checkpointer()
+
+        repo = ChatSessionsRepository(self._checkpointer_conn)
+        session = await repo.update_session(
+            thread_id=session_id, title=new_title
+        )
+        return session.to_dict() if session else None
+
+    async def pin_session(
+        self, session_id: str, pinned: bool = True
+    ) -> Optional[Dict[str, Any]]:
+        """
+        Pin or unpin a chat session.
+
+        Args:
+            session_id: Thread ID
+            pinned: True to pin, False to unpin
+
+        Returns:
+            Updated session dictionary or None
+        """
+        if not self._checkpointer_conn:
+            await self._get_checkpointer()
+
+        repo = ChatSessionsRepository(self._checkpointer_conn)
+        session = await repo.pin_session(thread_id=session_id, pinned=pinned)
+        return session.to_dict() if session else None
+
+    async def close(self):
+        """
+        Close the checkpointer connection and cleanup resources.
+        """
+        async with self._init_lock:
+            if self._checkpointer_conn:
+                try:
+                    # Add timeout to prevent blocking on database close
+                    await asyncio.wait_for(
+                        self._checkpointer_conn.close(),
+                        timeout=5.0
+                    )
+                    log.debug(
+                        "Checkpointer connection closed for: %s",
+                        self.project_path,
+                    )
+                except asyncio.TimeoutError:
+                    log.warning(
+                        "Checkpointer connection close timeout for: %s (forcing cleanup)",
+                        self.project_path,
+                    )
+                except Exception as e:
+                    log.warning("Error closing checkpointer connection: %s", e)
+                finally:
+                    self._checkpointer_conn = None
+                    self._checkpointer = None
+                    self._graph = None
+                    self._initialized = False

gns3server/agent/gns3_copilot/chat_sessions_repository.py

@@ -0,0 +1,447 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# GNS3-Copilot - AI-powered Network Lab Assistant for GNS3
+#
+# This file is part of GNS3-Copilot project.
+#
+# GNS3-Copilot is free software: you can redistribute it and/or modify it
+# under the terms of the GNU General Public License as published by the
+# Free Software Foundation, either version 3 of the License, or (at your
+# option) any later version.
+#
+# GNS3-Copilot is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+# or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+# for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with GNS3-Copilot. If not, see <https://www.gnu.org/licenses/>.
+#
+# Copyright (C) 2025 Yue Guobin (岳国宾)
+# Author: Yue Guobin (岳国宾)
+#
+# Project Home: https://github.com/yueguobin/gns3-copilot
+#
+"""
+
+Chat Sessions Repository for managing chat session data.
+
+Provides CRUD operations for the chat_sessions table in the project's
+checkpoint database.
+"""
+
+import json
+import logging
+from datetime import datetime
+from typing import Any
+from typing import Dict
+from typing import List
+from typing import Optional
+
+import aiosqlite
+
+log = logging.getLogger(__name__)
+
+
+class ChatSession:
+    """Chat session model."""
+
+    def __init__(
+        self,
+        id: Optional[int] = None,
+        thread_id: str = "",
+        user_id: str = "",
+        project_id: str = "",
+        title: str = "New Conversation",
+        message_count: int = 0,
+        llm_calls_count: int = 0,
+        input_tokens: int = 0,
+        output_tokens: int = 0,
+        total_tokens: int = 0,
+        last_message_at: Optional[str] = None,
+        created_at: Optional[str] = None,
+        updated_at: Optional[str] = None,
+        metadata: str = "{}",
+        stats: str = "{}",
+        pinned: bool = False,
+    ):
+        self.id = id
+        self.thread_id = thread_id
+        self.user_id = user_id
+        self.project_id = project_id
+        self.title = title
+        self.message_count = message_count
+        self.llm_calls_count = llm_calls_count
+        self.input_tokens = input_tokens
+        self.output_tokens = output_tokens
+        self.total_tokens = total_tokens
+        self.last_message_at = last_message_at
+        self.created_at = created_at
+        self.updated_at = updated_at
+        self.metadata = metadata
+        self.stats = stats
+        self.pinned = pinned
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary."""
+        return {
+            "id": self.id,
+            "thread_id": self.thread_id,
+            "user_id": self.user_id,
+            "project_id": self.project_id,
+            "title": self.title,
+            "message_count": self.message_count,
+            "llm_calls_count": self.llm_calls_count,
+            "input_tokens": self.input_tokens,
+            "output_tokens": self.output_tokens,
+            "total_tokens": self.total_tokens,
+            "last_message_at": self.last_message_at,
+            "created_at": self.created_at,
+            "updated_at": self.updated_at,
+            "metadata": json.loads(self.metadata) if self.metadata else {},
+            "stats": json.loads(self.stats) if self.stats else {},
+            "pinned": self.pinned,
+        }
+
+
+class ChatSessionsRepository:
+    """
+    Repository for managing chat sessions in the checkpoint database.
+    """
+
+    def __init__(self, conn: aiosqlite.Connection):
+        """
+        Initialize repository with a database connection.
+
+        Args:
+            conn: aiosqlite connection to the checkpoint database
+        """
+        self.conn = conn
+
+    async def create_session(
+        self,
+        thread_id: str,
+        user_id: str,
+        project_id: str,
+        title: str = "New Conversation",
+        copilot_mode: Optional[str] = None,
+    ) -> ChatSession:
+        """
+        Create a new chat session.
+
+        Args:
+            thread_id: Unique thread identifier
+            user_id: User ID
+            project_id: Project ID
+            title: Session title
+            copilot_mode: Copilot mode (optional)
+
+        Returns:
+            Created ChatSession
+        """
+        now = datetime.utcnow().isoformat()
+        # Build metadata JSON
+        metadata = {"copilot_mode": copilot_mode} if copilot_mode else {}
+        metadata_json = json.dumps(metadata)
+
+        cursor = await self.conn.execute(
+            """
+            INSERT INTO chat_sessions (
+                thread_id, user_id, project_id, title,
+                metadata, created_at, updated_at
+            ) VALUES (?, ?, ?, ?, ?, ?, ?)
+            """,
+            (thread_id, user_id, project_id, title, metadata_json, now, now),
+        )
+        await self.conn.commit()
+
+        session_id = cursor.lastrowid
+        log.info(
+            "Created chat session: id=%s, thread_id=%s, copilot_mode=%s",
+            session_id, thread_id, copilot_mode
+        )
+
+        return await self.get_session_by_id(session_id)
+
+    async def get_session_by_id(
+        self, session_id: int
+    ) -> Optional[ChatSession]:
+        """
+        Get a session by its database ID.
+
+        Args:
+            session_id: Database row ID
+
+        Returns:
+            ChatSession or None
+        """
+        cursor = await self.conn.execute(
+            "SELECT * FROM chat_sessions WHERE id = ?", (session_id,)
+        )
+        row = await cursor.fetchone()
+
+        if row:
+            return self._row_to_session(row)
+        return None
+
+    async def get_session_by_thread(
+        self, thread_id: str
+    ) -> Optional[ChatSession]:
+        """
+        Get a session by thread_id.
+
+        Args:
+            thread_id: Thread identifier
+
+        Returns:
+            ChatSession or None
+        """
+        cursor = await self.conn.execute(
+            "SELECT * FROM chat_sessions WHERE thread_id = ?", (thread_id,)
+        )
+        row = await cursor.fetchone()
+
+        if row:
+            return self._row_to_session(row)
+        return None
+
+    async def list_sessions(
+        self,
+        user_id: Optional[str] = None,
+        project_id: Optional[str] = None,
+        copilot_mode: Optional[str] = None,
+        limit: int = 100,
+    ) -> List[ChatSession]:
+        """
+        List sessions with optional filters.
+
+        Args:
+            user_id: Filter by user ID
+            project_id: Filter by project ID
+            copilot_mode: Filter by copilot mode (metadata field)
+            limit: Maximum number of sessions to return
+
+        Returns:
+            List of ChatSession
+        """
+        query = "SELECT * FROM chat_sessions"
+        params = []
+
+        conditions = []
+        if user_id:
+            conditions.append("user_id = ?")
+            params.append(user_id)
+        if project_id:
+            conditions.append("project_id = ?")
+            params.append(project_id)
+        if copilot_mode:
+            # Filter by JSON metadata field
+            conditions.append("json_extract(metadata, '$.copilot_mode') = ?")
+            params.append(copilot_mode)
+
+        if conditions:
+            query += " WHERE " + " AND ".join(conditions)
+
+        # Sort by pinned status first, then by updated_at
+        query += " ORDER BY pinned DESC, updated_at DESC LIMIT ?"
+        params.append(limit)
+
+        cursor = await self.conn.execute(query, params)
+        rows = await cursor.fetchall()
+
+        return [self._row_to_session(row) for row in rows]
+
+    async def update_session(
+        self,
+        thread_id: str,
+        title: Optional[str] = None,
+        message_count: Optional[int] = None,
+        llm_calls_count: Optional[int] = None,
+        input_tokens: Optional[int] = None,
+        output_tokens: Optional[int] = None,
+        total_tokens: Optional[int] = None,
+        last_message_at: Optional[str] = None,
+    ) -> Optional[ChatSession]:
+        """
+        Update a session.
+
+        Args:
+            thread_id: Thread identifier
+            title: New title
+            message_count: Increment message count
+            llm_calls_count: Increment LLM call count
+            input_tokens: Add to input tokens
+            output_tokens: Add to output tokens
+            total_tokens: Add to total tokens
+            last_message_at: Last message timestamp
+
+        Returns:
+            Updated ChatSession or None
+        """
+        updates = []
+        params = []
+
+        now = datetime.utcnow().isoformat()
+
+        if title is not None:
+            updates.append("title = ?")
+            params.append(title)
+
+        if message_count is not None:
+            updates.append("message_count = message_count + ?")
+            params.append(message_count)
+
+        if llm_calls_count is not None:
+            updates.append("llm_calls_count = llm_calls_count + ?")
+            params.append(llm_calls_count)
+
+        if input_tokens is not None:
+            updates.append("input_tokens = input_tokens + ?")
+            params.append(input_tokens)
+
+        if output_tokens is not None:
+            updates.append("output_tokens = output_tokens + ?")
+            params.append(output_tokens)
+
+        if total_tokens is not None:
+            updates.append("total_tokens = total_tokens + ?")
+            params.append(total_tokens)
+
+        if last_message_at is not None:
+            updates.append("last_message_at = ?")
+            params.append(last_message_at)
+
+        if not updates:
+            return await self.get_session_by_thread(thread_id)
+
+        updates.append("updated_at = ?")
+        params.append(now)
+        params.append(thread_id)
+
+        query = (
+            f"UPDATE chat_sessions SET {', '.join(updates)} WHERE thread_id "
+            f"= ?"
+        )
+
+        await self.conn.execute(query, params)
+        await self.conn.commit()
+
+        log.debug("Updated chat session: thread_id=%s", thread_id)
+        return await self.get_session_by_thread(thread_id)
+
+    async def delete_session(self, thread_id: str) -> bool:
+        """
+        Delete a session by thread_id.
+
+        Args:
+            thread_id: Thread identifier
+
+        Returns:
+            True if deleted, False if not found
+        """
+        # First, delete the checkpoint data
+        await self.conn.execute(
+            "DELETE FROM checkpoints WHERE thread_id = ?", (thread_id,)
+        )
+
+        # Then delete the session
+        cursor = await self.conn.execute(
+            "DELETE FROM chat_sessions WHERE thread_id = ?", (thread_id,)
+        )
+        await self.conn.commit()
+
+        deleted = cursor.rowcount > 0
+        if deleted:
+            log.info(
+                "Deleted chat session and checkpoints: thread_id=%s", thread_id
+            )
+
+        return deleted
+
+    async def delete_all_sessions(self, project_id: str) -> int:
+        """
+        Delete all sessions for a project.
+
+        Args:
+            project_id: Project ID
+
+        Returns:
+            Number of sessions deleted
+        """
+        # Get all thread_ids for this project
+        cursor = await self.conn.execute(
+            "SELECT thread_id FROM chat_sessions WHERE project_id = ?",
+            (project_id,),
+        )
+        rows = await cursor.fetchall()
+        thread_ids = [row[0] for row in rows]
+
+        # Delete checkpoints and sessions
+        for thread_id in thread_ids:
+            await self.conn.execute(
+                "DELETE FROM checkpoints WHERE thread_id = ?", (thread_id,)
+            )
+
+        cursor = await self.conn.execute(
+            "DELETE FROM chat_sessions WHERE project_id = ?", (project_id,)
+        )
+        await self.conn.commit()
+
+        deleted_count = cursor.rowcount
+        if deleted_count > 0:
+            log.info(
+                "Deleted %d sessions for project: %s",
+                deleted_count,
+                project_id,
+            )
+
+        return deleted_count
+
+    async def pin_session(
+        self, thread_id: str, pinned: bool = True
+    ) -> Optional[ChatSession]:
+        """
+        Pin or unpin a session.
+
+        Args:
+            thread_id: Thread identifier
+            pinned: True to pin, False to unpin
+
+        Returns:
+            Updated ChatSession or None
+        """
+        now = datetime.utcnow().isoformat()
+        await self.conn.execute(
+            "UPDATE chat_sessions SET pinned = ?, updated_at = ? WHERE "
+            "thread_id = ?",
+            (1 if pinned else 0, now, thread_id),
+        )
+        await self.conn.commit()
+
+        log.debug(
+            "Session pin status updated: thread_id=%s, pinned=%s",
+            thread_id,
+            pinned,
+        )
+        return await self.get_session_by_thread(thread_id)
+
+    def _row_to_session(self, row) -> ChatSession:
+        """Convert database row to ChatSession object."""
+        return ChatSession(
+            id=row[0],
+            thread_id=row[1],
+            user_id=row[2],
+            project_id=row[3],
+            title=row[4],
+            message_count=row[5],
+            llm_calls_count=row[6],
+            input_tokens=row[7],
+            output_tokens=row[8],
+            total_tokens=row[9],
+            last_message_at=row[10],
+            created_at=row[11],
+            updated_at=row[12],
+            metadata=row[13],
+            stats=row[14],
+            pinned=bool(row[15]) if len(row) > 15 else False,
+        )

gns3server/agent/gns3_copilot/configs/__init__.py

@@ -0,0 +1,22 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# GNS3-Copilot - AI-powered Network Lab Assistant for GNS3
+#
+# Copyright (C) 2025 Yue Guobin
+#
+
+"""
+Configuration package for GNS3 Copilot.
+"""
+
+from .skills_config import (
+    SKILLS_CONFIG,
+    get_skills_config,
+    update_skills_config,
+)
+
+__all__ = [
+    "SKILLS_CONFIG",
+    "get_skills_config",
+    "update_skills_config",
+]

gns3server/agent/gns3_copilot/configs/skills_config.py

@@ -0,0 +1,86 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# GNS3-Copilot - AI-powered Network Lab Assistant for GNS3
+#
+# This file is part of GNS3-Copilot project.
+#
+# GNS3-Copilot is free software: you can redistribute it and/or modify it
+# under the terms of the GNU General Public License as published by the
+# Free Software Foundation, either version 3 of the License, or (at your
+# option) any later version.
+#
+# GNS3-Copilot is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+# or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+# for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with GNS3-Copilot. If not, see <https://www.gnu.org/licenses/>.
+#
+# Copyright (C) 2025 Yue Guobin
+# Author: Yue Guobin
+#
+# Project Home: https://github.com/yueguobin/gns3-copilot
+#
+
+"""
+Skills Configuration
+
+This module contains configuration for the external skills repository.
+"""
+
+from gns3server.config import Config
+
+# Default skills repository configuration
+SKILLS_CONFIG = {
+    # Git repository URL for skills
+    "repo_url": "https://github.com/gns3/gns3-skills.git",
+
+    # Git branch to use
+    "branch": "main",
+
+    # Automatically pull updates on reload
+    "auto_update": True,
+
+    # Enable external skills loading
+    # If False, use the built-in hardcoded skills
+    "enabled": True,
+}
+
+
+def get_skills_config() -> dict:
+    """
+    Get the skills configuration.
+
+    Priority:
+    1. GNS3 server config (gns3_server.conf → [Server] → skills_*)
+    2. Hardcoded defaults
+
+    Returns:
+        Dictionary containing skills configuration
+    """
+    config = SKILLS_CONFIG.copy()
+    try:
+        server = Config.instance().settings.Server
+        if server.skills_repo_url:
+            config["repo_url"] = server.skills_repo_url
+        if server.skills_repo_branch:
+            config["branch"] = server.skills_repo_branch
+        config["auto_update"] = server.skills_auto_update
+    except Exception:
+        pass
+    return config
+
+
+def update_skills_config(**kwargs):
+    """
+    Update skills configuration.
+
+    Args:
+        **kwargs: Configuration key-value pairs to update
+    """
+    for key, value in kwargs.items():
+        if key in SKILLS_CONFIG:
+            SKILLS_CONFIG[key] = value
+        else:
+            raise ValueError(f"Unknown configuration key: {key}")

gns3server/agent/gns3_copilot/gns3_client/__init__.py

@@ -0,0 +1,98 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# GNS3-Copilot - AI-powered Network Lab Assistant for GNS3
+#
+# This file is part of GNS3-Copilot project.
+#
+# GNS3-Copilot is free software: you can redistribute it and/or modify it
+# under the terms of the GNU General Public License as published by the
+# Free Software Foundation, either version 3 of the License, or (at your
+# option) any later version.
+#
+# GNS3-Copilot is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+# or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+# for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with GNS3-Copilot. If not, see <https://www.gnu.org/licenses/>.
+#
+# Copyright (C) 2025 Yue Guobin (岳国宾)
+# Author: Yue Guobin (岳国宾)
+#
+# Project Home: https://github.com/yueguobin/gns3-copilot
+#
+
+"""
+GNS3 Client Package
+
+This package provides a Python interface for interacting with GNS3 servers.
+Adapted from the upstream gns3fy project with modifications for compatibility
+with langchain and reduced dependency conflicts.
+
+Main classes:
+- Gns3Connector: Connector for GNS3 server API interaction
+- Project: GNS3 Project management
+- Node: GNS3 Node management
+- Link: GNS3 Link management
+- GNS3TopologyTool: GNS3 topology reading tool
+- GNS3ProjectInfoTool: GNS3 project info tool
+
+Main functions:
+- get_gns3_connector: Factory function to create Gns3Connector
+- get_gns3_connector_with_llm_config: Create connector AND retrieve LLM config
+- get_gns3_server_host: Get GNS3 server hostname from Controller or Config
+- get_llm_config: Get LLM model configuration for a user
+
+Upstream gns3fy: https://github.com/davidban77/gns3fy
+"""
+
+from .connector_factory import get_gns3_connector
+from .connector_factory import get_gns3_connector_with_llm_config
+from .connector_factory import get_gns3_server_host
+from .connector_factory import get_llm_config
+from .context_helpers import get_current_jwt_token
+from .context_helpers import get_current_llm_config
+from .context_helpers import set_current_jwt_token
+from .context_helpers import set_current_llm_config
+from .custom_gns3fy import CONSOLE_TYPES
+from .custom_gns3fy import LINK_TYPES
+from .custom_gns3fy import NODE_TYPES
+from .custom_gns3fy import Gns3Connector
+from .custom_gns3fy import Link
+from .custom_gns3fy import Node
+from .custom_gns3fy import Project
+from .gns3_project_info import GNS3ProjectInfoTool
+from .gns3_topology_reader import GNS3TopologyTool
+
+# Dynamic version management
+try:
+    from importlib.metadata import version
+
+    __version__ = version("gns3-copilot")
+except Exception:
+    __version__ = "unknown"
+
+__author__ = "Yue Guobin (岳国宾)"
+__description__ = "AI-powered network automation assistant for GNS3"
+__url__ = "https://github.com/yueguobin/gns3-copilot"
+
+__all__ = [
+    "Gns3Connector",
+    "Project",
+    "Node",
+    "Link",
+    "NODE_TYPES",
+    "CONSOLE_TYPES",
+    "LINK_TYPES",
+    "GNS3TopologyTool",
+    "GNS3ProjectInfoTool",
+    "get_gns3_connector",
+    "get_gns3_connector_with_llm_config",
+    "get_gns3_server_host",
+    "get_llm_config",
+    "set_current_jwt_token",
+    "get_current_jwt_token",
+    "set_current_llm_config",
+    "get_current_llm_config",
+]

gns3server/agent/gns3_copilot/gns3_client/connector_factory.py

@@ -0,0 +1,476 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# GNS3-Copilot - AI-powered Network Lab Assistant for GNS3
+#
+# This file is part of GNS3-Copilot project.
+#
+# GNS3-Copilot is free software: you can redistribute it and/or modify it
+# under the terms of the GNU General Public License as published by the
+# Free Software Foundation, either version 3 of the License, or (at your
+# option) any later version.
+#
+# GNS3-Copilot is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+# or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+# for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with GNS3-Copilot. If not, see <https://www.gnu.org/licenses/>.
+#
+# Copyright (C) 2025 Yue Guobin (岳国宾)
+# Author: Yue Guobin (岳国宾)
+#
+# Project Home: https://github.com/yueguobin/gns3-copilot
+#
+
+"""
+GNS3 Connector Factory Module
+
+This module provides factory functions for creating Gns3Connector instances
+with JWT token authentication and context-aware configuration management.
+
+⚠️ WARNING: This module is shared with the MCP (Model Context Protocol) service.
+The get_gns3_connector() function is used by both gns3-copilot and MCP.
+Modifications must be tested with BOTH.
+
+Features:
+- Context variable based request-scoped data management (JWT tokens, LLM
+  config)
+- Auto-detection of GNS3 server URL from Controller/Config
+- Fallback URL strategy for flexible deployment
+- LLM configuration retrieval for users
+
+"""
+
+# Standard library imports
+import asyncio
+import concurrent.futures
+import logging
+from typing import Optional
+from uuid import UUID
+
+from gns3server.agent.gns3_copilot.gns3_client.context_helpers import (
+    get_current_jwt_token,
+)
+
+# Local imports
+from gns3server.agent.gns3_copilot.gns3_client.custom_gns3fy import (
+    Gns3Connector,
+)
+
+logger = logging.getLogger(__name__)
+
+# Fallback default URL
+DEFAULT_GNS3_URL = "http://127.0.0.1:3080"
+
+
+def _get_url_from_controller() -> Optional[str]:
+    """Try to get GNS3 server URL from running Controller instance.
+
+    Returns:
+        URL string if successful, None otherwise
+    """
+    try:
+        from gns3server.controller import Controller
+
+        controller = Controller.instance()
+        local_compute = controller.get_compute("local")
+
+        url = (
+            f"{local_compute.protocol}://{local_compute.host}:"
+            f"{local_compute.port}"
+        )
+        logger.debug(
+            "Got GNS3 URL from Controller: %s (protocol=%s, host=%s, port=%s)",
+            url,
+            local_compute.protocol,
+            local_compute.host,
+            local_compute.port,
+        )
+        return url
+    except ImportError as e:
+        logger.debug("Cannot import Controller: %s", str(e))
+        return None
+    except AttributeError as e:
+        logger.debug("Controller instance not available: %s", str(e))
+        return None
+    except KeyError as e:
+        logger.debug("Local compute not found in Controller: %s", str(e))
+        return None
+    except Exception as e:
+        logger.warning(
+            "Unexpected error getting URL from Controller: %s", str(e)
+        )
+        return None
+
+
+def _get_url_from_config() -> Optional[str]:
+    """Try to get GNS3 server URL from Config settings.
+
+    Returns:
+        URL string if successful, None otherwise
+    """
+    try:
+        from gns3server.config import Config
+
+        server_config = Config.instance().settings.Server
+        url = (
+            f"{server_config.protocol.value}://{server_config.host}:"
+            f"{server_config.port}"
+        )
+        logger.debug(
+            "Got GNS3 URL from Config: %s (protocol=%s, host=%s, port=%s)",
+            url,
+            server_config.protocol.value,
+            server_config.host,
+            server_config.port,
+        )
+        return url
+    except ImportError as e:
+        logger.debug("Cannot import Config: %s", str(e))
+        return None
+    except AttributeError as e:
+        logger.debug("Config settings not available: %s", str(e))
+        return None
+    except Exception as e:
+        logger.warning("Unexpected error getting URL from Config: %s", str(e))
+        return None
+
+
+def get_gns3_connector(
+    jwt_token: Optional[str] = None, url: Optional[str] = None
+) -> Optional[Gns3Connector]:
+    """Create and return a Gns3Connector instance with JWT authentication.
+
+    URL Resolution Strategy (in order):
+        1. Explicitly provided `url` parameter
+        2. Runtime configuration from Controller.instance().compute("local")
+        3. Static configuration from Config.instance().settings.Server
+        4. Fallback to DEFAULT_GNS3_URL (http://127.0.0.1:3080)
+
+    Args:
+        jwt_token: JWT token for authentication (optional, will be retrieved
+                    from context if not provided)
+        url: GNS3 server URL (optional, auto-detected if not provided)
+
+    Returns:
+        Gns3Connector instance if parameters are valid, None otherwise
+
+    Example:
+        # Auto-detect URL from Controller or Config
+        connector = get_gns3_connector(jwt_token="your_jwt_token")
+
+        # Or specify custom URL
+        connector = get_gns3_connector(
+            jwt_token="your_jwt_token",
+            url="http://custom-server:3080"
+        )
+
+        if connector:
+            projects = connector.projects
+        else:
+            logger.error("Failed to create GNS3 connector")
+    """
+    try:
+        # Validate JWT token
+        # If not provided, try to get from current request context
+        if not jwt_token:
+            jwt_token = get_current_jwt_token()
+            if not jwt_token:
+                logger.error("JWT token is required")
+                return None
+
+        # Resolve URL with fallback strategy
+        if url is None:
+            logger.debug("No URL provided, attempting auto-detection...")
+
+            # Strategy 1: Try to get from running Controller
+            url = _get_url_from_controller()
+            if url:
+                logger.info("Using GNS3 server URL from Controller: %s", url)
+            else:
+                # Strategy 2: Fall back to Config
+                logger.debug("Controller not available, trying Config...")
+                url = _get_url_from_config()
+                if url:
+                    logger.info("Using GNS3 server URL from Config: %s", url)
+                else:
+                    # Strategy 3: Use default fallback
+                    logger.debug("Config not available, using default URL")
+                    url = DEFAULT_GNS3_URL
+                    logger.warning(
+                        "Using fallback default URL: %s. This may not be "
+                        "correct if your GNS3 server is configured "
+                        "differently. Consider providing the URL explicitly.",
+                        url,
+                    )
+        else:
+            logger.info("Using explicitly provided GNS3 server URL: %s", url)
+
+        # Validate URL
+        if not url:
+            logger.error("Failed to resolve GNS3 server URL")
+            return None
+
+        # Create connector
+        logger.debug("Creating Gns3Connector with URL=%s", url)
+        connector = Gns3Connector(
+            url=url,
+            jwt_token=jwt_token,
+            api_version=3,
+        )
+        logger.info("Successfully created Gns3Connector for URL: %s", url)
+        return connector
+
+    except Exception as e:
+        logger.error(
+            "Failed to create Gns3Connector: %s", str(e), exc_info=True
+        )
+        return None
+
+
+async def get_gns3_connector_with_llm_config(
+    user_id, jwt_token: str, url: Optional[str] = None, app=None
+) -> Optional[dict]:
+    """
+    Create Gns3Connector and retrieve LLM model configuration for the user.
+
+    This is a convenience function that combines:
+    1. get_gns3_connector() - Create GNS3 API connector
+    2. get_llm_config() - Retrieve user's default LLM config with API key
+
+    Args:
+        user_id: User UUID (can be string or UUID object)
+        jwt_token: JWT token for authentication
+        url: GNS3 server URL (optional, auto-detected if not provided)
+        app: FastAPI application instance (optional, for direct database
+            access)
+
+    Returns:
+        Dictionary with keys:
+        - connector: Gns3Connector instance
+        - llm_config: Dict with provider, api_key, model, etc.
+        Or None if failed
+
+    Example:
+        result = await get_gns3_connector_with_llm_config(user_id, jwt_token)
+        if result:
+            connector = result["connector"]
+            llm_config = result["llm_config"]
+
+            # Use connector for GNS3 operations
+            projects = connector.projects
+
+            # Use LLM config for AI operations
+            provider = llm_config["provider"]
+            api_key = llm_config["api_key"]
+            model = llm_config["model"]
+        else:
+            logger.error("Failed to initialize GNS3 connector or LLM config")
+    """
+    try:
+        # Convert user_id to UUID if it's a string
+        if isinstance(user_id, str):
+            user_id = UUID(user_id)
+
+        # Step 1: Create GNS3 connector
+        connector = get_gns3_connector(jwt_token=jwt_token, url=url)
+        if not connector:
+            logger.error("Failed to create GNS3 connector")
+            return None
+
+        # Step 2: Detect URL if not provided
+        if url is None:
+            url = _detect_url_for_api()
+
+        # Step 3: Get LLM config
+        llm_config = get_llm_config(
+            user_id=user_id, jwt_token=jwt_token, app=app
+        )
+
+        if not llm_config:
+            logger.warning(f"No LLM config found for user {user_id}")
+            # Still return result with connector only
+            return {"connector": connector, "llm_config": None}
+
+        logger.info(
+            f"Successfully initialized GNS3 connector and LLM config for "
+            f"user {user_id}: connector_url={connector.url}, "
+            f"llm_provider={llm_config.get('provider')}, "
+            f"llm_model={llm_config.get('model')}"
+        )
+
+        return {"connector": connector, "llm_config": llm_config}
+
+    except Exception as e:
+        logger.error(
+            f"Failed to get GNS3 connector with LLM config: {e}", exc_info=True
+        )
+        return None
+
+
+def _detect_url_for_api() -> Optional[str]:
+    """
+    Detect GNS3 server URL for API calls.
+
+    Uses the same priority order as get_gns3_connector:
+    1. Controller.instance().compute("local")
+    2. Config.instance().settings.Server
+    3. Fallback to DEFAULT_GNS3_URL
+
+    Returns:
+        URL string, or None if detection failed
+    """
+    logger.debug("Detecting GNS3 server URL for API calls")
+
+    # Try Controller first
+    url = _get_url_from_controller()
+    if url:
+        logger.debug("Using URL from Controller for API call: %s", url)
+        return url
+
+    # Try Config
+    url = _get_url_from_config()
+    if url:
+        logger.debug("Using URL from Config for API call: %s", url)
+        return url
+
+    # Fallback
+    logger.debug("Using fallback URL for API call: %s", DEFAULT_GNS3_URL)
+    return DEFAULT_GNS3_URL
+
+
+def get_gns3_server_host() -> str:
+    """
+    Get GNS3 server hostname from Controller or Config.
+
+    This is a convenience function for extracting the hostname only, useful
+    for Nornir tools that need the GNS3 server address.
+
+    Uses the same priority order as get_gns3_connector:
+    1. Controller.instance().compute("local")
+    2. Config.instance().settings.Server
+    3. Fallback to DEFAULT_GNS3_URL host
+
+    Returns:
+        Hostname/IP address string
+
+    Example:
+        from gns3server.agent.gns3_copilot.gns3_client import (
+            get_gns3_server_host,
+        )
+
+        host = get_gns3_server_host()
+        print(f"GNS3 server host: {host}")
+    """
+    url = _detect_url_for_api()
+
+    # Extract host from URL
+    # URL format: protocol://host:port
+    try:
+        # Remove protocol prefix
+        host_part = url.split("://")[1]
+        # Extract host (before the port)
+        host = host_part.split(":")[0]
+        logger.debug("Extracted GNS3 server host: %s from URL: %s", host, url)
+        return host
+    except Exception as e:
+        logger.warning(
+            "Failed to extract host from URL %s: %s, using fallback", url, e
+        )
+        return DEFAULT_GNS3_URL.split("://")[1].split(":")[0]
+
+
+def get_llm_config(user_id, jwt_token: str, app=None) -> Optional[dict]:
+    """
+    Get LLM model configuration for a user.
+
+    This function retrieves the user's LLM configuration from the database.
+    When `app` is provided, it directly accesses the database (bypassing API
+    restrictions). Otherwise, it falls back to API call (which may mask
+    group config API keys).
+
+    Args:
+        user_id: User UUID (can be string or UUID object)
+        jwt_token: JWT token for authentication
+        app: FastAPI application instance (optional, for direct database
+            access)
+
+    Returns:
+        Dictionary with LLM configuration keys (provider, model, api_key,
+        etc.), or None if not found.
+
+    Example:
+        from gns3server.agent.gns3_copilot.gns3_client import (
+            get_llm_config,
+        )
+
+        config = get_llm_config(user_id, jwt_token)
+        if config:
+            provider = config['provider']
+            model = config['model']
+            api_key = config['api_key']
+    """
+    try:
+        # Convert user_id to UUID if it's a string
+        if isinstance(user_id, str):
+            user_id = UUID(user_id)
+
+        # If app is provided, use direct database access (preferred)
+        if app is not None:
+            from gns3server.agent.gns3_copilot.utils.llm_config_helper import (
+                get_user_llm_config_with_app,
+            )
+
+            # Run the async function in sync context
+            try:
+                loop = asyncio.get_running_loop()
+                # We're in an async context with a running loop
+                # This shouldn't happen since this is a sync function
+                with concurrent.futures.ThreadPoolExecutor() as executor:
+                    future = executor.submit(
+                        asyncio.run, get_user_llm_config_with_app(user_id, app)
+                    )
+                    return future.result(timeout=10)
+            except RuntimeError:
+                # No running event loop - we're in a sync context
+                pass
+
+            # Try to get an existing event loop, or create a new one
+            try:
+                loop = asyncio.get_event_loop()
+                if loop.is_running():
+                    # Loop is running but not the running loop (edge case)
+                    with concurrent.futures.ThreadPoolExecutor() as executor:
+                        future = executor.submit(
+                            asyncio.run,
+                            get_user_llm_config_with_app(user_id, app),
+                        )
+                        return future.result(timeout=10)
+                else:
+                    # Loop exists but not running - use it
+                    return loop.run_until_complete(
+                        get_user_llm_config_with_app(user_id, app)
+                    )
+            except RuntimeError:
+                # No event loop exists - create a new one
+                loop = asyncio.new_event_loop()
+                asyncio.set_event_loop(loop)
+                try:
+                    return loop.run_until_complete(
+                        get_user_llm_config_with_app(user_id, app)
+                    )
+                finally:
+                    loop.close()
+
+        # Fallback: No app provided, try API call (will mask group config API
+        # keys)
+        logger.warning(
+            "No app provided for get_llm_config, group config API keys may be "
+            "masked"
+        )
+        return None
+
+    except Exception as e:
+        logger.error("Failed to get LLM config for user %s: %s", user_id, e)
+        return None

gns3server/agent/gns3_copilot/gns3_client/context_helpers.py

@@ -0,0 +1,135 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# GNS3-Copilot - AI-powered Network Lab Assistant for GNS3
+#
+# This file is part of GNS3-Copilot project.
+#
+# GNS3-Copilot is free software: you can redistribute it and/or modify it
+# under the terms of the GNU General Public License as published by the
+# Free Software Foundation, either version 3 of the License, or (at your
+# option) any later version.
+#
+# GNS3-Copilot is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+# or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+# for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with GNS3-Copilot. If not, see <https://www.gnu.org/licenses/>.
+#
+# Copyright (C) 2025 Yue Guobin (岳国宾)
+# Author: Yue Guobin (岳国宾)
+#
+# Project Home: https://github.com/yueguobin/gns3-copilot
+#
+
+"""
+Request-Scoped Context Helpers for GNS3-Copilot
+
+This module provides context variable management for request-scoped data
+(JWT tokens and LLM configurations) using Python's contextvars module.
+
+These functions are separated into their own module to avoid circular imports
+between agent_service.py, gns3_copilot.py, and gns3_client modules.
+
+Key Features:
+- Thread-safe and async-safe request-scoped context management
+- Automatic cleanup when request context ends
+- No manual cleanup required
+
+Usage:
+    from gns3server.agent.gns3_copilot.gns3_client.context_helpers import (
+        set_current_jwt_token,
+        get_current_jwt_token,
+        set_current_llm_config,
+        get_current_llm_config,
+    )
+
+    # In request handler
+    set_current_jwt_token(token)
+    set_current_llm_config(config)
+
+    # In downstream code
+    token = get_current_jwt_token()
+    config = get_current_llm_config()
+"""
+
+import logging
+from contextvars import ContextVar
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+# Context variables for request-scoped data
+# Automatically cleaned up when request context ends
+_jwt_token_context: ContextVar[Optional[str]] = ContextVar(
+    "_jwt_token_context", default=None
+)
+_llm_config_context: ContextVar[Optional[dict]] = ContextVar(
+    "_llm_config_context", default=None
+)
+
+
+def set_current_jwt_token(token: str) -> None:
+    """Set the JWT token for the current request context.
+
+    Args:
+        token: JWT token string
+    """
+    _jwt_token_context.set(token)
+    logger.debug("JWT token set in context")
+
+
+def get_current_jwt_token() -> Optional[str]:
+    """Get the JWT token for the current request context.
+
+    Returns:
+        JWT token string if available, None otherwise
+    """
+    token = _jwt_token_context.get()
+    if token:
+        logger.debug("JWT token retrieved from context")
+    else:
+        logger.warning("JWT token not found in context")
+    return token
+
+
+def set_current_llm_config(config: dict) -> None:
+    """Set the LLM config for the current request context.
+
+    Args:
+        config: LLM configuration dictionary with provider, model, api_key,
+                etc.
+    """
+    _llm_config_context.set(config)
+    logger.debug(
+        "LLM config set in context: provider=%s, model=%s",
+        config.get("provider"),
+        config.get("model"),
+    )
+
+
+def get_current_llm_config() -> Optional[dict]:
+    """Get the LLM config for the current request context.
+
+    Returns:
+        LLM configuration dict if available, None otherwise
+    """
+    config = _llm_config_context.get()
+    if config:
+        logger.debug(
+            "LLM config retrieved from context: provider=%s, model=%s",
+            config.get("provider"),
+            config.get("model"),
+        )
+    else:
+        logger.warning("LLM config not found in context")
+    return config
+
+
+__all__ = [
+    "set_current_jwt_token",
+    "get_current_jwt_token",
+    "set_current_llm_config",
+    "get_current_llm_config",
+]

gns3server/agent/gns3_copilot/gns3_client/gns3_project_info.py

@@ -0,0 +1,178 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# GNS3-Copilot - AI-powered Network Lab Assistant for GNS3
+#
+# This file is part of GNS3-Copilot project.
+#
+# GNS3-Copilot is free software: you can redistribute it and/or modify it
+# under the terms of the GNU General Public License as published by the
+# Free Software Foundation, either version 3 of the License, or (at your
+# option) any later version.
+#
+# GNS3-Copilot is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+# or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+# for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with GNS3-Copilot. If not, see <https://www.gnu.org/licenses/>.
+#
+# Copyright (C) 2025 Yue Guobin (岳国宾)
+# Author: Yue Guobin (岳国宾)
+#
+# Project Home: https://github.com/yueguobin/gns3-copilot
+#
+
+"""
+GNS3 Project Info Tool
+
+This module provides a LangChain BaseTool to retrieve basic information of a
+specific GNS3 project by project ID. Returns project name, status, node count,
+and link count.
+
+"""
+
+import logging
+from pprint import pprint
+from typing import Any
+
+from langchain.tools import BaseTool
+
+from gns3server.agent.gns3_copilot.gns3_client import Project
+from gns3server.agent.gns3_copilot.gns3_client import get_gns3_connector
+
+# Configure logging
+logger = logging.getLogger(__name__)
+
+
+class GNS3ProjectInfoTool(BaseTool):
+    """LangChain tool for retrieving GNS3 project basic information."""
+
+    name: str = "gns3_project_info"
+    description: str = """
+    Retrieves basic information of a GNS3 project including name, status,
+    node count and link count.
+
+    Input: `project_id` (str, required): UUID of the GNS3 project.
+
+    Output: Dictionary with:
+    - `project_id`: Project UUID
+    - `name`: Project name
+    - `status`: Project status (opened/closed)
+    - `node_count`: Number of nodes in the project
+    - `link_count`: Number of links in the project
+
+    Returns a tuple format: (name, project_id, node_count, link_count, status)
+    """
+
+    def _run(
+        self,
+        tool_input: Any = None,
+        run_manager: Any = None,
+        project_id: str | None = None,
+    ) -> dict:
+        """
+        Synchronous method to retrieve basic information of a specific GNS3 project.
+
+        Args:
+            tool_input : Input parameters, typically a dict or Pydantic model.
+            run_manager : Callback manager for tool run.
+            project_id : The UUID of the specific GNS3 project.
+
+        Returns:
+            dict: A dictionary containing project info (name, project_id, node_count,
+                  link_count, status), or an error dictionary if an exception occurs
+                  or project_id is not provided.
+        """
+
+        # Log received input
+        logger.info(
+            "Received tool_input: %s, project_id: %s", tool_input, project_id
+        )
+
+        try:
+            # Validate project_id parameter
+            if not project_id:
+                logger.error("project_id parameter is required.")
+                return {
+                    "error": (
+                        "project_id parameter is required. Please provide a valid "
+                        "project UUID."
+                    )
+                }
+
+            # Initialize Gns3Connector using factory function
+            logger.debug("Connecting to GNS3 server...")
+            server = get_gns3_connector()
+
+            if server is None:
+                logger.error("Failed to create GNS3 connector")
+                return {
+                    "error": (
+                        "Failed to connect to GNS3 server. Please check your "
+                        "configuration."
+                    )
+                }
+
+            # Use the provided project_id directly
+            logger.info(
+                f"Retrieving project info for project_id: {project_id}"
+            )
+            project = Project(project_id=project_id, connector=server)
+            project.get()  # Load project details
+
+            # Get node and link counts
+            nodes_inventory = project.nodes_inventory()
+            links_summary = project.links_summary(is_print=False)
+
+            node_count = len(nodes_inventory) if nodes_inventory else 0
+            link_count = len(links_summary) if links_summary else 0
+
+            # Build result in tuple format consistent with GNS3ProjectList
+            result = {
+                "project_id": project.project_id,
+                "name": project.name,
+                "status": project.status,
+                "node_count": node_count,
+                "link_count": link_count,
+                "tuple": (
+                    project.name,
+                    project.project_id,
+                    node_count,
+                    link_count,
+                    project.status,
+                ),
+            }
+
+            # Log result
+            logger.info(
+                "Project info retrieved: name=%s, status=%s, nodes=%d, links=%d",
+                project.name,
+                project.status,
+                node_count,
+                link_count,
+            )
+
+            return result
+
+        except Exception as e:
+            logger.error("Error retrieving GNS3 project info: %s", str(e))
+            return {"error": f"Failed to retrieve project info: {str(e)}"}
+
+
+if __name__ == "__main__":
+    # Test the tool
+    tool = GNS3ProjectInfoTool()
+
+    # Example usage with project_id
+    # Replace with an actual project UUID from your GNS3 server
+    example_project_id = "0c0fde25-6ead-4413-a283-ea8fd2324291"
+
+    print("Testing GNS3ProjectInfoTool with project_id...")
+    result = tool._run(project_id=example_project_id)
+    pprint(result)
+
+    # Test without project_id (should return error)
+    print("\nTesting without project_id (should return error)...")
+    error_result = tool._run()
+    pprint(error_result)

gns3server/agent/gns3_copilot/gns3_client/gns3_topology_reader.py

@@ -0,0 +1,189 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# GNS3-Copilot - AI-powered Network Lab Assistant for GNS3
+#
+# This file is part of GNS3-Copilot project.
+#
+# GNS3-Copilot is free software: you can redistribute it and/or modify it
+# under the terms of the GNU General Public License as published by the
+# Free Software Foundation, either version 3 of the License, or (at your
+# option) any later version.
+#
+# GNS3-Copilot is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+# or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+# for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with GNS3-Copilot. If not, see <https://www.gnu.org/licenses/>.
+#
+# Copyright (C) 2025 Yue Guobin (岳国宾)
+# Author: Yue Guobin (岳国宾)
+#
+# Project Home: https://github.com/yueguobin/gns3-copilot
+#
+
+"""
+GNS3 Topology Reader Tool
+
+This module provides a LangChain BaseTool to retrieve the topology of a
+specific GNS3 project by project ID. Returns nodes, links, and project
+metadata.
+
+⚠️ WARNING: This module is shared with the MCP (Model Context Protocol) service.
+GNS3TopologyTool._run() is called by MCP device config handlers.
+The jwt_token/url parameters were added for MCP compatibility.
+Modifications must be tested with BOTH gns3-copilot AND MCP.
+"""
+
+import copy
+import logging
+from pprint import pprint
+from typing import Any
+
+from langchain.tools import BaseTool
+
+from gns3server.agent.gns3_copilot.gns3_client import Project
+from gns3server.agent.gns3_copilot.gns3_client import get_gns3_connector
+
+# Configure logging
+logger = logging.getLogger(__name__)
+
+
+# Define LangChain tool class
+class GNS3TopologyTool(BaseTool):
+    """LangChain tool for retrieving GNS3 project topology information."""
+
+    name: str = "gns3_topology_reader"
+    description: str = """
+    Retrieves the topology of a GNS3 project including nodes and links.
+
+    Input: `project_id` (str, required): UUID of the GNS3 project.
+
+    Output: Dictionary with:
+    - `project_id`, `name`, `status`: Project metadata
+    - `nodes`: Dict of node details (node_id, name, ports, console_port,
+               type, etc.)
+    - `links`: List of link connections
+
+    Use this to understand network structure before making changes.
+    """
+
+    def _run(
+        self,
+        tool_input: Any = None,
+        run_manager: Any = None,
+        project_id: str | None = None,
+        jwt_token: str | None = None,
+        url: str | None = None,
+    ) -> dict:
+        """
+        Synchronous method to retrieve the topology of a specific GNS3 project.
+
+        Args:
+            tool_input: Input parameters, typically a dict or Pydantic model
+                       containing server_url.
+            run_manager: Callback manager for tool run.
+            project_id: The UUID of the specific GNS3 project to retrieve
+                        topology from.
+            jwt_token: JWT token for authentication (used by MCP handlers).
+            url: GNS3 server URL (used by MCP handlers).
+
+        Returns:
+            dict: A dictionary containing the project ID, name, status, nodes,
+                  and links, or an error dictionary if an exception occurs
+                  or project_id is not provided.
+        """
+
+        # Log received input
+        logger.info(
+            "Received tool_input: %s, project_id: %s", tool_input, project_id
+        )
+
+        try:
+            # Validate project_id parameter
+            if not project_id:
+                logger.error("project_id parameter is required.")
+                return {
+                    "error": "project_id parameter is required. "
+                    "Please provide a valid project UUID."
+                }
+
+            # Initialize Gns3Connector using factory function
+            # jwt_token/url can be passed explicitly (e.g. from MCP handlers)
+            # or auto-detected (e.g. from gns3-copilot agent)
+            logger.debug("Connecting to GNS3 server...")
+            server = get_gns3_connector(jwt_token=jwt_token, url=url)
+
+            if server is None:
+                logger.error("Failed to create GNS3 connector")
+                return {
+                    "error": "Failed to connect to GNS3 server. Please check "
+                    "your configuration."
+                }
+
+            # Use the provided project_id directly
+            logger.info(f"Retrieving topology for project_id: {project_id}")
+            project = Project(project_id=project_id, connector=server)
+            project.get()  # Load project details
+
+            # Get topology JSON: includes nodes (devices), links, etc.
+            topology = {
+                "project_id": project.project_id,
+                "name": project.name,
+                "status": project.status,
+                "nodes": self._clean_nodes_ports(
+                    copy.deepcopy(project.nodes_inventory())
+                ),
+                "links": project.links_summary(is_print=False),
+            }
+
+            # Log topology result
+            logger.info(
+                "Topology retrieved: project_id=%s, name=%s, nodes=%d, "
+                "links=%d",
+                topology.get("project_id"),
+                topology.get("name"),
+                len(topology.get("nodes", {})),
+                len(topology.get("links", [])),
+            )
+            logger.debug("Topology details: %s", topology)
+
+            return topology
+
+        except Exception as e:
+            logger.error("Error retrieving GNS3 topology: %s", str(e))
+            return {"error": f"Failed to retrieve topology: {str(e)}"}
+
+    def _clean_nodes_ports(self, data: dict) -> dict:
+        """
+        Clean and simplify the nodes data structure.
+
+        Simplify each node's ports list to only keep name and short_name
+        fields.
+        """
+        for node in data.values():  # Iterate through R-1, R-2, R-3, R-4
+            if "ports" in node and isinstance(node["ports"], list):
+                node["ports"] = [
+                    {"name": port["name"], "short_name": port["short_name"]}
+                    for port in node["ports"]
+                ]
+        return data
+
+
+if __name__ == "__main__":
+    # Test the tool
+    tool = GNS3TopologyTool()
+
+    # Example usage with project_id
+    # Replace with an actual project UUID from your GNS3 server
+    example_project_id = "0c0fde25-6ead-4413-a283-ea8fd2324291"
+
+    print("Testing GNS3TopologyTool with project_id...")
+    result = tool._run(project_id=example_project_id)
+    pprint(result)
+
+    # Test without project_id (should return error)
+    print("\nTesting without project_id (should return error)...")
+    error_result = tool._run()
+    pprint(error_result)

gns3server/agent/gns3_copilot/project_agent_manager.py

@@ -0,0 +1,158 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# GNS3-Copilot - AI-powered Network Lab Assistant for GNS3
+#
+# This file is part of GNS3-Copilot project.
+#
+# GNS3-Copilot is free software: you can redistribute it and/or modify it
+# under the terms of the GNU General Public License as published by the
+# Free Software Foundation, either version 3 of the License, or (at your
+# option) any later version.
+#
+# GNS3-Copilot is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+# or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+# for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with GNS3-Copilot. If not, see <https://www.gnu.org/licenses/>.
+#
+# Copyright (C) 2025 Yue Guobin (岳国宾)
+# Author: Yue Guobin (岳国宾)
+#
+# Project Home: https://github.com/yueguobin/gns3-copilot
+#
+"""
+
+Project Agent Manager
+
+Manages AgentService instances for GNS3 projects using a singleton pattern.
+Each project has its own AgentService with a dedicated SQLite checkpoint
+database.
+"""
+
+import asyncio
+import logging
+from typing import Dict
+from typing import Optional
+
+from gns3server.agent.gns3_copilot.agent_service import AgentService
+
+log = logging.getLogger(__name__)
+
+
+class ProjectAgentManager:
+    """
+    Singleton manager for project-level Agent services.
+
+    Manages the lifecycle of AgentService instances, ensuring that each project
+    has exactly one AgentService instance. Handles cleanup of resources when
+    projects are closed.
+    """
+
+    _instance: Optional["ProjectAgentManager"] = None
+    _lock: asyncio.Lock = asyncio.Lock()
+    _agents: Dict[str, AgentService] = {}
+
+    def __new__(cls):
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+            cls._instance._agents = {}
+            cls._instance._lock = asyncio.Lock()
+        return cls._instance
+
+    async def get_agent(
+        self, project_id: str, project_path: str
+    ) -> AgentService:
+        """
+        Get or create an AgentService for a project.
+
+        Args:
+            project_id: GNS3 project ID
+            project_path: Path to the GNS3 project directory
+
+        Returns:
+            AgentService instance for the project
+        """
+        async with self._lock:
+            if project_id not in self._agents:
+                log.info(
+                    "Creating new AgentService for project: %s at %s",
+                    project_id,
+                    project_path,
+                )
+                self._agents[project_id] = AgentService(project_path)
+            return self._agents[project_id]
+
+    async def remove_agent(self, project_id: str):
+        """
+        Remove and cleanup an AgentService for a project.
+
+        Should be called when a project is closed to free resources.
+
+        Args:
+            project_id: GNS3 project ID
+        """
+        async with self._lock:
+            if project_id in self._agents:
+                log.info("Removing AgentService for project: %s", project_id)
+                agent = self._agents.pop(project_id)
+                await agent.close()
+
+    async def close_all(self):
+        """
+        Close all AgentService instances and cleanup resources.
+
+        Should be called on server shutdown.
+        """
+        async with self._lock:
+            log.info(
+                "Closing all AgentService instances (%d projects)",
+                len(self._agents),
+            )
+            for project_id, agent in self._agents.items():
+                log.debug("Closing AgentService for project: %s", project_id)
+                await agent.close()
+            self._agents.clear()
+
+    def has_agent(self, project_id: str) -> bool:
+        """
+        Check if an AgentService exists for a project.
+
+        Args:
+            project_id: GNS3 project ID
+
+        Returns:
+            True if AgentService exists, False otherwise
+        """
+        return project_id in self._agents
+
+    @property
+    def active_projects(self) -> list[str]:
+        """
+        Get list of project IDs with active AgentService instances.
+
+        Returns:
+            List of project IDs
+        """
+        return list(self._agents.keys())
+
+
+# Global singleton instance
+_project_agent_manager: Optional[ProjectAgentManager] = None
+_manager_lock = asyncio.Lock()
+
+
+async def get_project_agent_manager() -> ProjectAgentManager:
+    """
+    Get the global ProjectAgentManager singleton instance.
+
+    Returns:
+        ProjectAgentManager instance
+    """
+    global _project_agent_manager
+    async with _manager_lock:
+        if _project_agent_manager is None:
+            _project_agent_manager = ProjectAgentManager()
+            log.info("ProjectAgentManager singleton created")
+        return _project_agent_manager

gns3server/agent/gns3_copilot/prompts/__init__.py

@@ -0,0 +1,52 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# GNS3-Copilot - AI-powered Network Lab Assistant for GNS3
+#
+# This file is part of GNS3-Copilot project.
+#
+# GNS3-Copilot is free software: you can redistribute it and/or modify it
+# under the terms of the GNU General Public License as published by the
+# Free Software Foundation, either version 3 of the License, or (at your
+# option) any later version.
+#
+# GNS3-Copilot is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+# or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+# for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with GNS3-Copilot. If not, see <https://www.gnu.org/licenses/>.
+#
+# Copyright (C) 2025 Yue Guobin (岳国宾)
+# Author: Yue Guobin (岳国宾)
+#
+# Project Home: https://github.com/yueguobin/gns3-copilot
+#
+
+"""
+Prompts Module for GNS3-Copilot
+
+This package provides system prompts loading utilities for the GNS3-Copilot AI agent.
+
+All system prompts are now loaded from the external GNS3-Skills repository:
+https://github.com/gns3/gns3-skills
+
+Available prompts (loaded from external repository):
+- lab_automation_assistant.md: Lab automation mode (diagnostics + config)
+- teaching_assistant.md: Teaching assistant mode (diagnostics only)
+- troubleshooting_injection.md: Fault injection specialist
+- title.md: Title generation prompt template
+
+Use the SkillsManager to load these prompts:
+    from gns3server.agent.gns3_copilot.skills.manager import skills_manager
+
+    # Load prompts
+    lab_prompt = skills_manager.load_prompt("lab_automation_assistant")
+    teaching_prompt = skills_manager.load_prompt("teaching_assistant")
+    injection_prompt = skills_manager.load_prompt("troubleshooting_injection")
+    title_prompt = skills_manager.load_prompt("title")
+"""
+
+from .prompt_loader import load_system_prompt
+
+__all__ = ["load_system_prompt"]

gns3server/agent/gns3_copilot/prompts/prompt_loader.py

@@ -0,0 +1,115 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# GNS3-Copilot - AI-powered Network Lab Assistant for GNS3
+#
+# This file is part of GNS3-Copilot project.
+#
+# GNS3-Copilot is free software: you can redistribute it and/or modify it
+# under the terms of the GNU General Public License as published by the
+# Free Software Foundation, either version 3 of the License, or (at your
+# option) any later version.
+#
+# GNS3-Copilot is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+# or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+# for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with GNS3-Copilot. If not, see <https://www.gnu.org/licenses/>.
+#
+# Copyright (C) 2025 Yue Guobin (� Yue Guobin)
+# Author: Yue Guobin (岳国宾)
+#
+# Project Home: https://github.com/yueguobin/gns3-copilot
+#
+
+"""
+Prompt Loader for GNS3-Copilot
+
+This module provides utilities for loading system prompts from the external
+GNS3-Skills repository.
+Supports multiple prompt variants based on LLM model configuration.
+
+Available Modes (controlled by config.copilot_mode in llm_model_configs):
+- "teaching_assistant" (default): Teaching assistant mode - diagnostics only,
+  no configuration
+- "lab_automation_assistant": Full lab automation assistant mode - diagnostics
+  and configuration enabled
+- "troubleshooting_injection": Troubleshooting issue injection mode
+
+All prompts are loaded from the external GNS3-Skills repository via SkillsManager.
+"""
+
+import logging
+
+from gns3server.agent.gns3_copilot.skills.registry import get_prompt
+
+logger = logging.getLogger(__name__)
+
+
+def load_system_prompt(llm_config: dict | None = None) -> str:
+    """
+    Load the system prompt for GNS3-Copilot from the external repository.
+
+    The prompt mode is controlled by the `copilot_mode` field in the LLM
+    model config:
+    - "teaching_assistant" (default): Teaching assistant mode - diagnostics
+      only, no configuration
+    - "lab_automation_assistant": Full lab automation assistant mode -
+      diagnostics and configuration enabled
+    - "troubleshooting_injection": Troubleshooting issue injection mode -
+      inject network faults for practice
+
+    Prompts are loaded from the external GNS3-Skills repository via SkillsManager.
+
+    Args:
+        llm_config: LLM model configuration dictionary (flattened structure
+                   from get_user_llm_config_full)
+
+    Returns:
+        str: The system prompt string, or empty string if not found.
+    """
+    if not llm_config:
+        logger.debug(
+            "No LLM config provided, using default TEACHING_ASSISTANT "
+            "prompt mode"
+        )
+        return _load_prompt("teaching_assistant")
+
+    # llm_config is a flattened dict with copilot_mode at the top level
+    # Example: {"provider": "...", "model": "...", "copilot_mode": "...", ...}
+    mode = llm_config.get("copilot_mode", "teaching_assistant").lower()
+
+    if mode == "lab_automation_assistant":
+        logger.debug(
+            "Using LAB_AUTOMATION_ASSISTANT prompt mode (diagnostics + "
+            "configuration)"
+        )
+        return _load_prompt("lab_automation_assistant")
+    elif mode == "troubleshooting_injection":
+        logger.debug(
+            "Using TROUBLESHOOTING_INJECTION prompt mode (fault injection)"
+        )
+        return _load_prompt("troubleshooting_injection")
+    else:
+        logger.debug("Using TEACHING_ASSISTANT prompt mode (diagnostics only)")
+        return _load_prompt("teaching_assistant")
+
+
+def _load_prompt(prompt_name: str) -> str:
+    """
+    Load a prompt from the external skills repository.
+
+    Args:
+        prompt_name: Name of the prompt (e.g., "teaching_assistant")
+
+    Returns:
+        Prompt content as string, or empty string if not found
+    """
+    prompt = get_prompt(prompt_name)
+    if prompt:
+        logger.debug(f"Loaded prompt '{prompt_name}' from external repository")
+        return prompt
+
+    logger.warning(f"Prompt '{prompt_name}' not found in external repository")
+    return ""

gns3server/agent/gns3_copilot/skills/__init__.py

@@ -0,0 +1,72 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# GNS3-Copilot - AI-powered Network Lab Assistant for GNS3
+#
+# This file is part of GNS3-Copilot project.
+#
+# GNS3-Copilot is free software: you can redistribute it and/or modify it
+# under the terms of the GNU General Public License as published by the
+# Free Software Foundation, either version 3 of the License, or (at your
+# option) any later version.
+#
+# GNS3-Copilot is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+# or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+# for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with GNS3-Copilot. If not, see <https://www.gnu.org/licenses/>.
+#
+# Copyright (C) 2025 Yue Guobin
+# Author: Yue Guobin
+#
+# Project Home: https://github.com/yueguobin/gns3-copilot
+#
+
+"""
+Skills Package
+
+This package provides skills management for GNS3 Copilot.
+All skills are loaded from the external GNS3-Skills repository.
+
+Directory Structure:
+- skills/
+  - registry.py      # SKILLS_REGISTRY and get_skill()
+  - manager.py       # SkillsManager - Git clone/pull and hot reload
+  - loader.py        # SkillsLoader - YAML/Markdown file loading
+"""
+
+from .registry import (
+    SKILLS_REGISTRY,
+    INJECTION_SKILLS_REGISTRY,
+    get_skill,
+    get_injection_skill,
+    DeviceSkillsTool,
+    InjectionSkillsTool,
+    PacketAnalysisSkillsTool,
+    set_skills_manager,
+    get_skills_manager,
+    reload_injection_skills,
+    reload_forbidden_commands,
+    reload_skills_repository,
+    get_skills_repository_info,
+)
+from .manager import SkillsManager
+from .loader import SkillsLoader
+
+__all__ = [
+    "SKILLS_REGISTRY",
+    "INJECTION_SKILLS_REGISTRY",
+    "get_skill",
+    "get_injection_skill",
+    "DeviceSkillsTool",
+    "InjectionSkillsTool",
+    "PacketAnalysisSkillsTool",
+    "SkillsManager",
+    "SkillsLoader",
+    "set_skills_manager",
+    "get_skills_manager",
+    "reload_injection_skills",
+    "reload_skills_repository",
+    "get_skills_repository_info",
+]

gns3server/agent/gns3_copilot/skills/loader.py

@@ -0,0 +1,320 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# GNS3-Copilot - AI-powered Network Lab Assistant for GNS3
+#
+# This file is part of GNS3-Copilot project.
+#
+# GNS3-Copilot is free software: you can redistribute it and/or modify it
+# under the terms of the GNU General Public License as published by the
+# Free Software Foundation, either version 3 of the License, or (at your
+# option) any later version.
+#
+# GNS3-Copilot is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+# or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+# for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with GNS3-Copilot. If not, see <https://www.gnu.org/licenses/>.
+#
+# Copyright (C) 2025 Yue Guobin
+# Author: Yue Guobin
+#
+# Project Home: https://github.com/yueguobin/gns3-copilot
+#
+
+"""
+Skills Loader
+
+This module provides functionality to load skills from YAML files.
+Supports loading injection skills and device/feature skills.
+"""
+
+import logging
+import os
+from pathlib import Path
+from typing import Any, Dict
+
+try:
+    import yaml
+except ImportError:
+    yaml = None
+
+logger = logging.getLogger(__name__)
+
+
+class SkillsLoader:
+    """
+    Load skills from YAML files in the skills directory.
+
+    This loader reads YAML files and converts them to the skill dictionary
+    format expected by the skills registry.
+    """
+
+    def __init__(self, skills_dir: str):
+        """
+        Initialize the skills loader.
+
+        Args:
+            skills_dir: Path to the skills directory containing YAML files
+        """
+        self.skills_dir = Path(skills_dir)
+        if not self.skills_dir.exists():
+            logger.warning(f"Skills directory does not exist: {self.skills_dir}")
+
+    def load_injection_skills(self) -> Dict[str, Dict[str, Any]]:
+        """
+        Load all injection skills from YAML files.
+
+        Returns:
+            Dictionary mapping skill keys to skill definitions
+        """
+        if yaml is None:
+            logger.error("PyYAML is not installed. Cannot load skills from YAML.")
+            return {}
+
+        skills = {}
+        injection_dir = self.skills_dir / "injection"
+
+        if not injection_dir.exists():
+            logger.warning(f"Injection skills directory not found: {injection_dir}")
+            return {}
+
+        for yaml_file in injection_dir.glob("*.yaml"):
+            try:
+                skill_data = self._load_yaml(yaml_file)
+                if not skill_data:
+                    logger.warning(f"Skipping empty YAML file: {yaml_file}")
+                    continue
+                # Generate key from filename (e.g., "ospf_issues.yaml" -> "injection_ospf")
+                skill_key = f"injection_{yaml_file.stem}"
+                skills[skill_key] = skill_data
+                logger.debug(f"Loaded injection skill: {skill_key} from {yaml_file}")
+            except Exception as e:
+                logger.error(f"Failed to load skill from {yaml_file}: {e}")
+
+        logger.debug(f"Loaded {len(skills)} injection skills from {injection_dir}")
+        return skills
+
+    def load_device_skills(self) -> Dict[str, Dict[str, Any]]:
+        """
+        Load all device skills from YAML files.
+
+        Returns:
+            Dictionary mapping skill keys to skill definitions
+        """
+        if yaml is None:
+            logger.error("PyYAML is not installed. Cannot load skills from YAML.")
+            return {}
+
+        skills = {}
+        device_dir = self.skills_dir / "device"
+
+        if not device_dir.exists():
+            logger.warning(f"Device skills directory not found: {device_dir}")
+            return {}
+
+        for yaml_file in device_dir.glob("*.yaml"):
+            try:
+                skill_data = self._load_yaml(yaml_file)
+                if not skill_data:
+                    logger.warning(f"Skipping empty YAML file: {yaml_file}")
+                    continue
+                # Use device_type from YAML content as the key
+                # Fallback to filename stem if device_type not present
+                skill_key = skill_data.get("device_type") if isinstance(skill_data, dict) else None
+                if not skill_key:
+                    skill_key = yaml_file.stem
+                    logger.warning(f"No device_type in {yaml_file}, using filename '{skill_key}' as key")
+                skills[skill_key] = skill_data
+                logger.debug(f"Loaded device skill: {skill_key} from {yaml_file}")
+            except Exception as e:
+                logger.error(f"Failed to load skill from {yaml_file}: {e}")
+
+        logger.debug(f"Loaded {len(skills)} device skills from device directory")
+        return skills
+
+    def load_feature_skills(self) -> Dict[str, Dict[str, Any]]:
+        """
+        Load all feature skills from YAML files.
+
+        Feature skills are network planning and design functionalities
+        (e.g., topology planner), not device-specific features.
+
+        Returns:
+            Dictionary mapping skill keys to skill definitions
+        """
+        if yaml is None:
+            logger.error("PyYAML is not installed. Cannot load skills from YAML.")
+            return {}
+
+        skills = {}
+        feature_dir = self.skills_dir / "feature"
+
+        if not feature_dir.exists():
+            logger.warning(f"Feature skills directory not found: {feature_dir}")
+            return {}
+
+        for yaml_file in feature_dir.glob("*.yaml"):
+            try:
+                skill_data = self._load_yaml(yaml_file)
+                if not skill_data:
+                    logger.warning(f"Skipping empty YAML file: {yaml_file}")
+                    continue
+                # Use device_type from YAML content as the key
+                # Fallback to filename stem if device_type not present
+                skill_key = skill_data.get("device_type") if isinstance(skill_data, dict) else None
+                if not skill_key:
+                    skill_key = yaml_file.stem
+                    logger.warning(f"No device_type in {yaml_file}, using filename '{skill_key}' as key")
+                skills[skill_key] = skill_data
+                logger.debug(f"Loaded feature skill: {skill_key} from {yaml_file}")
+            except Exception as e:
+                logger.error(f"Failed to load feature skill from {yaml_file}: {e}")
+
+        logger.debug(f"Loaded {len(skills)} feature skills from feature directory")
+        return skills
+
+    def load_prompt(self, prompt_name: str) -> str:
+        """
+        Load a prompt from a markdown file.
+
+        Args:
+            prompt_name: Name of the prompt file (without .md extension)
+
+        Returns:
+            Prompt content as string, or empty string if not found
+        """
+        prompts_dir = self.skills_dir / "prompts"
+        prompt_file = prompts_dir / f"{prompt_name}.md"
+
+        if not prompt_file.exists():
+            logger.warning(f"Prompt file not found: {prompt_file}")
+            return ""
+
+        try:
+            with open(prompt_file, "r", encoding="utf-8") as f:
+                content = f.read()
+            logger.debug(f"Loaded prompt: {prompt_name} from {prompt_file}")
+            return content
+        except Exception as e:
+            logger.error(f"Failed to load prompt from {prompt_file}: {e}")
+            return ""
+
+    def load_forbidden_commands(self) -> list:
+        """
+        Load forbidden commands from the config directory.
+
+        Returns:
+            List of forbidden command patterns, or empty list if not found
+        """
+        config_dir = self.skills_dir / "config"
+        config_file = config_dir / "forbidden_commands.txt"
+
+        if not config_file.exists():
+            logger.warning(f"Forbidden commands file not found: {config_file}")
+            return []
+
+        try:
+            commands = []
+            with open(config_file, "r", encoding="utf-8") as f:
+                for line in f:
+                    line = line.strip()
+                    if not line or line.startswith("#"):
+                        continue
+                    commands.append(line.lower())
+            logger.debug(f"Loaded {len(commands)} forbidden commands from {config_file}")
+            return commands
+        except Exception as e:
+            logger.error(f"Failed to load forbidden commands from {config_file}: {e}")
+            return []
+
+    def load_packet_analysis_protocols(self) -> Dict[str, Dict[str, Any]]:
+        """
+        Load packet analysis protocol definitions from YAML files.
+
+        Returns:
+            Dictionary mapping protocol keys to protocol definitions.
+            Each protocol contains tshark_field, display_filter, and filter_examples.
+        """
+        if yaml is None:
+            logger.error("PyYAML is not installed. Cannot load packet analysis protocols.")
+            return {}
+
+        protocols = {}
+        packet_analysis_dir = self.skills_dir / "packet_analysis"
+
+        if not packet_analysis_dir.exists():
+            logger.debug(f"Packet analysis directory not found: {packet_analysis_dir}")
+            return {}
+
+        for yaml_file in packet_analysis_dir.glob("*.yaml"):
+            try:
+                protocol_data = self._load_yaml(yaml_file)
+                if not protocol_data:
+                    logger.warning(f"Skipping empty YAML file: {yaml_file}")
+                    continue
+
+                # Use protocol_key field from YAML as the key
+                protocol_key = protocol_data.get("protocol_key")
+                if not protocol_key:
+                    logger.warning(f"No 'protocol_key' field in {yaml_file}, skipping")
+                    continue
+
+                protocols[protocol_key] = protocol_data
+                logger.debug(f"Loaded packet analysis protocol: {protocol_key} from {yaml_file}")
+            except Exception as e:
+                logger.error(f"Failed to load protocol from {yaml_file}: {e}")
+
+        logger.debug(f"Loaded {len(protocols)} packet analysis protocols from {packet_analysis_dir}")
+        return protocols
+
+    def _load_yaml(self, file_path: Path) -> Dict[str, Any]:
+        """
+        Load a YAML file and return its content.
+
+        Args:
+            file_path: Path to the YAML file
+
+        Returns:
+            Parsed YAML content as dictionary, or empty dict if file is empty
+        """
+        with open(file_path, "r", encoding="utf-8") as f:
+            data = yaml.safe_load(f)
+        if not isinstance(data, dict):
+            logger.warning(f"YAML file {file_path} is empty or has invalid format")
+            return {}
+        return data
+
+    def validate_skill_format(self, skill_data: Dict[str, Any]) -> bool:
+        """
+        Validate that a skill dictionary has the required fields.
+
+        Args:
+            skill_data: Skill dictionary to validate
+
+        Returns:
+            True if valid, False otherwise
+        """
+        required_fields = ["name", "description", "issues"]
+        for field in required_fields:
+            if field not in skill_data:
+                logger.error(f"Skill missing required field: {field}")
+                return False
+
+        if not isinstance(skill_data["issues"], dict):
+            logger.error("Skill 'issues' field must be a dictionary")
+            return False
+
+        for issue_key, issue_data in skill_data["issues"].items():
+            if not isinstance(issue_data, dict):
+                logger.error(f"Issue '{issue_key}' must be a dictionary")
+                return False
+
+            issue_required = ["name", "description"]
+            for field in issue_required:
+                if field not in issue_data:
+                    logger.error(f"Issue '{issue_key}' missing required field: {field}")
+                    return False
+
+        return True

gns3server/agent/gns3_copilot/skills/manager.py

@@ -0,0 +1,467 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# GNS3-Copilot - AI-powered Network Lab Assistant for GNS3
+#
+# This file is part of GNS3-Copilot project.
+#
+# GNS3-Copilot is free software: you can redistribute it and/or modify it
+# under the terms of the GNU General Public License as published by the
+# Free Software Foundation, either version 3 of the License, or (at your
+# option) any later version.
+#
+# GNS3-Copilot is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+# or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+# for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with GNS3-Copilot. If not, see <https://www.gnu.org/licenses/>.
+#
+# Copyright (C) 2025 Yue Guobin
+# Author: Yue Guobin
+#
+# Project Home: https://github.com/yueguobin/gns3-copilot
+#
+
+"""
+Skills Manager
+
+This module provides functionality to manage the skills repository,
+including Git operations and hot reload of skills.
+"""
+
+import logging
+import os
+from pathlib import Path
+from typing import Optional, Dict, Any
+
+try:
+    import git
+except ImportError:
+    git = None
+
+from gns3server.config import Config
+from .loader import SkillsLoader
+
+logger = logging.getLogger(__name__)
+
+# Git timeout settings for network operations.
+# Applied per-command via the `env` parameter to avoid polluting
+# the global process environment.
+_GIT_TIMEOUT_ENV = {
+    'GIT_HTTP_TIMEOUT': '10',           # Connection timeout (default: 120s)
+    'GIT_HTTP_LOW_SPEED_TIME': '5',     # Slow speed threshold window
+    'GIT_HTTP_LOW_SPEED_LIMIT': '10240', # < 10 KB/s = slow → abort
+}
+
+
+class SkillsManager:
+    """
+    Manage skills repository and hot reload functionality.
+
+    This class handles:
+    - Cloning the skills repository
+    - Pulling latest updates
+    - Hot reloading skills into memory
+    - Version tracking
+    """
+
+    def __init__(
+        self,
+        repo_url: str = None,
+        branch: str = "main",
+        auto_update: bool = False
+    ):
+        """
+        Initialize the skills manager.
+
+        Args:
+            repo_url: Git repository URL (default: https://github.com/gns3/gns3-skills.git)
+            branch: Git branch to use (default: "main")
+            auto_update: Whether to automatically pull updates on reload
+        """
+        if repo_url is None:
+            repo_url = "https://github.com/gns3/gns3-skills.git"
+
+        # Get local path from GNS3 config directory
+        config_dir = Config.instance().config_dir
+        local_path = os.path.join(config_dir, "skills")
+
+        self.repo_url = repo_url
+        self.local_path = Path(local_path)
+        self.branch = branch
+        self.auto_update = auto_update
+        self.loader = SkillsLoader(str(local_path))
+        self._repo: Optional["git.Repo"] = None
+        self._prompt_count = 0
+
+        if git is None:
+            logger.warning("GitPython is not installed. Skills management features will be limited.")
+
+    def initialize(self) -> bool:
+        """
+        Initialize the skills repository.
+
+        Behavior:
+        - If no local repo → clone from remote
+        - If local repo exists → open and run _update_if_needed()
+
+        Returns:
+            True if successful, False otherwise
+        """
+        try:
+            if not self.local_path.exists():
+                logger.info(f"Creating skills directory: {self.local_path}")
+                self.local_path.mkdir(parents=True, exist_ok=True)
+
+            if not (self.local_path / ".git").exists():
+                return self._clone()
+
+            # Repo exists, open it
+            try:
+                self._repo = git.Repo(self.local_path)
+            except Exception as e:
+                logger.error(f"Failed to open existing repository: {e}")
+                return False
+
+            self._update_if_needed()
+            return True
+        except Exception as e:
+            logger.error(f"Failed to initialize skills repository: {e}")
+            return False
+
+    def _update_if_needed(self) -> None:
+        """
+        Check local repo status and pull updates if safe.
+
+        - Uncommitted changes → warn and skip
+        - Behind remote → pull
+        - Up to date → nothing
+        - Network error → use existing files, log warning
+        """
+        if git is None or self._repo is None:
+            return
+
+        # Check for uncommitted changes
+        if self._repo.is_dirty(untracked_files=True):
+            logger.warning(
+                "Skills repository has uncommitted changes, skipping pull. "
+                "Commit or stash changes in %s to enable automatic updates.",
+                self.local_path
+            )
+            return
+
+        # Fetch remote
+        try:
+            origin = self._repo.remotes.origin
+            origin.fetch(env=_GIT_TIMEOUT_ENV)
+        except Exception as e:
+            logger.warning(f"Failed to fetch remote: {e}. Using local files.")
+            return
+
+        # Check if behind and pull
+        try:
+            behind_commits = list(self._repo.iter_commits(
+                f'{self.branch}..origin/{self.branch}'
+            ))
+            if behind_commits:
+                logger.info(
+                    "Skills repository is behind by %d commit(s), pulling...",
+                    len(behind_commits)
+                )
+                origin.pull(self.branch, env=_GIT_TIMEOUT_ENV)
+                logger.info(f"Updated to commit {self.get_current_version()}")
+            else:
+                logger.info("Skills repository is up to date")
+        except Exception as e:
+            logger.warning(f"Failed to pull updates: {e}. Using local files.")
+
+    def _clone(self) -> bool:
+        """
+        Clone the skills repository.
+
+        Returns:
+            True if successful, False otherwise
+        """
+        if git is None:
+            logger.error("GitPython is not installed. Cannot clone repository.")
+            return False
+
+        try:
+            self._repo = git.Repo.clone_from(
+                self.repo_url,
+                self.local_path,
+                branch=self.branch,
+                env=_GIT_TIMEOUT_ENV
+            )
+            logger.info(f"Successfully cloned skills repository to {self.local_path}")
+            return True
+        except git.GitCommandError as e:
+            logger.error(f"Git clone failed: {e}")
+            return False
+
+    def reload_skills(self) -> bool:
+        """
+        Hot reload skills from YAML files into the registry.
+
+        Loads the latest skill definitions from YAML files and updates
+        the INJECTION_SKILLS_REGISTRY.
+
+        Returns:
+            True if successful, False otherwise
+        """
+        try:
+            # Import here to avoid circular dependency
+            from .registry import INJECTION_SKILLS_REGISTRY, SKILLS_REGISTRY
+
+            # Load new injection skills from YAML files
+            new_injection_skills = self.loader.load_injection_skills()
+
+            if not new_injection_skills:
+                logger.warning("No injection skills loaded, keeping existing skills")
+                return False
+
+            # Validate injection skills
+            for skill_key, skill_data in new_injection_skills.items():
+                if not self.loader.validate_skill_format(skill_data):
+                    logger.error(f"Invalid skill format for {skill_key}, skipping")
+                    continue
+
+            # Load new device skills from YAML files
+            new_device_skills = self.loader.load_device_skills()
+
+            # Load new feature skills from YAML files
+            new_feature_skills = self.loader.load_feature_skills()
+
+            # Merge device and feature skills into single registry
+            all_skills = {}
+            all_skills.update(new_device_skills)
+            all_skills.update(new_feature_skills)
+
+            # Update registries (safe replace - never leaves dict empty)
+            for k in list(INJECTION_SKILLS_REGISTRY):
+                if k not in new_injection_skills:
+                    del INJECTION_SKILLS_REGISTRY[k]
+            INJECTION_SKILLS_REGISTRY.update(new_injection_skills)
+
+            for k in list(SKILLS_REGISTRY):
+                if k not in all_skills:
+                    del SKILLS_REGISTRY[k]
+            SKILLS_REGISTRY.update(all_skills)
+
+            logger.info(f"Loaded {len(new_injection_skills)} injection skills, {len(new_device_skills)} device skills, and {len(new_feature_skills)} feature skills")
+            return True
+        except Exception as e:
+            logger.error(f"Failed to reload skills: {e}")
+            return False
+
+    def reload_packet_analysis_protocols(self) -> bool:
+        """
+        Hot reload packet analysis protocol definitions from YAML files.
+
+        Loads the latest protocol definitions from YAML files and updates
+        the PACKET_ANALYSIS_REGISTRY.
+
+        Returns:
+            True if successful, False otherwise
+        """
+        try:
+            from .registry import PACKET_ANALYSIS_REGISTRY
+
+            # Load new packet analysis protocols from YAML files
+            new_protocols = self.loader.load_packet_analysis_protocols()
+
+            # Update registry (safe replace - never leaves dict empty)
+            for k in list(PACKET_ANALYSIS_REGISTRY):
+                if k not in new_protocols:
+                    del PACKET_ANALYSIS_REGISTRY[k]
+            PACKET_ANALYSIS_REGISTRY.update(new_protocols)
+
+            logger.info(f"Successfully reloaded {len(new_protocols)} packet analysis protocols")
+            return True
+        except Exception as e:
+            logger.error(f"Failed to reload packet analysis protocols: {e}")
+            return False
+
+    def reload_prompts(self) -> bool:
+        """
+        Hot reload prompts from Markdown files.
+
+        Loads the latest prompt definitions from Markdown files in
+        the skills repository.
+
+        Returns:
+            True if successful, False otherwise
+        """
+        try:
+            # Available prompt names
+            prompt_names = [
+                "lab_automation_assistant",
+                "teaching_assistant",
+                "troubleshooting_injection",
+                "title"
+            ]
+
+            # Load all prompts
+            loaded_count = 0
+            for prompt_name in prompt_names:
+                prompt_content = self.loader.load_prompt(prompt_name)
+                if prompt_content:
+                    loaded_count += 1
+                else:
+                    logger.warning(f"Failed to load prompt: {prompt_name}")
+
+            if loaded_count == 0:
+                logger.warning("No prompts loaded, keeping existing prompts")
+                return False
+
+            self._prompt_count = loaded_count
+            logger.info(f"Loaded {loaded_count} prompts")
+            return True
+        except Exception as e:
+            logger.error(f"Failed to reload prompts: {e}")
+            return False
+
+    def load_prompt(self, prompt_name: str) -> str:
+        """
+        Load a specific prompt from the skills repository.
+
+        Args:
+            prompt_name: Name of the prompt (without .md extension)
+
+        Returns:
+            Prompt content as string, or empty string if not found
+        """
+        try:
+            return self.loader.load_prompt(prompt_name)
+        except Exception as e:
+            logger.error(f"Failed to load prompt '{prompt_name}': {e}")
+            return ""
+
+    def load_forbidden_commands(self) -> list:
+        """
+        Load forbidden command patterns from the skills repository.
+
+        Returns:
+            List of forbidden command patterns, or empty list if not found
+        """
+        try:
+            return self.loader.load_forbidden_commands()
+        except Exception as e:
+            logger.error(f"Failed to load forbidden commands: {e}")
+            return []
+
+    def get_current_version(self) -> str:
+        """
+        Get the current git commit hash of the skills repository.
+
+        Returns:
+            Commit hash as string, or empty string if not available
+        """
+        if git is None or self._repo is None:
+            try:
+                self._repo = git.Repo(self.local_path)
+            except Exception:
+                return ""
+
+        try:
+            return self._repo.head.commit.hexsha
+        except Exception:
+            return ""
+
+    def get_skill_count(self) -> int:
+        """
+        Get the number of currently loaded injection skills.
+
+        Returns:
+            Number of skills in the registry
+        """
+        try:
+            from .registry import INJECTION_SKILLS_REGISTRY
+            return len(INJECTION_SKILLS_REGISTRY)
+        except Exception:
+            return 0
+
+    def get_prompt_count(self) -> int:
+        """
+        Get the number of currently loaded prompts.
+
+        Returns:
+            Number of prompts loaded
+        """
+        return self._prompt_count
+
+    def get_repository_info(self) -> Dict[str, Any]:
+        """
+        Get information about the skills repository.
+
+        Returns:
+            Dictionary containing repository information
+        """
+        return {
+            "repo_url": self.repo_url,
+            "local_path": str(self.local_path),
+            "branch": self.branch,
+            "current_version": self.get_current_version(),
+            "skill_count": self.get_skill_count(),
+            "prompt_count": self.get_prompt_count(),
+            "auto_update": self.auto_update,
+            "is_initialized": (self.local_path / ".git").exists()
+        }
+
+    def rollback(self, commit_hash: str) -> bool:
+        """
+        Rollback the skills repository to a specific commit.
+
+        Args:
+            commit_hash: Git commit hash to rollback to
+
+        Returns:
+            True if successful, False otherwise
+        """
+        if git is None:
+            logger.error("GitPython is not installed. Cannot rollback.")
+            return False
+
+        try:
+            if self._repo is None:
+                self._repo = git.Repo(self.local_path)
+
+            self._repo.git.reset("--hard", commit_hash)
+            logger.info(f"Successfully rolled back to commit {commit_hash}")
+
+            # Reload skills after rollback
+            return self.reload_skills()
+        except git.GitCommandError as e:
+            logger.error(f"Git rollback failed: {e}")
+            return False
+
+    def get_available_versions(self, limit: int = 10) -> list:
+        """
+        Get a list of recent commit hashes.
+
+        Args:
+            limit: Maximum number of commits to return
+
+        Returns:
+            List of commit information dictionaries
+        """
+        if git is None:
+            return []
+
+        try:
+            if self._repo is None:
+                self._repo = git.Repo(self.local_path)
+
+            commits = []
+            for commit in self._repo.iter_commits(max_count=limit):
+                commits.append({
+                    "hash": commit.hexsha,
+                    "message": commit.message.strip(),
+                    "author": str(commit.author),
+                    "date": commit.committed_datetime.isoformat()
+                })
+            return commits
+        except Exception as e:
+            logger.error(f"Failed to get commit history: {e}")
+            return []

gns3server/agent/gns3_copilot/skills/registry.py

@@ -0,0 +1,857 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# GNS3-Copilot - AI-powered Network Lab Assistant for GNS3
+#
+# This file is part of GNS3-Copilot project.
+#
+# GNS3-Copilot is free software: you can redistribute it and/or modify it
+# under the terms of the GNU General Public License as published by the
+# Free Software Foundation, either version 3 of the License, or (at your
+# option) any later version.
+#
+# GNS3-Copilot is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+# or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+# for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with GNS3-Copilot. If not, see <https://www.gnu.org/licenses/>.
+#
+# Copyright (C) 2025 Yue Guobin
+# Author: Yue Guobin
+#
+# Project Home: https://github.com/yueguobin/gns3-copilot
+#
+
+"""
+Skill Registry and Tools
+
+This module provides:
+- SKILLS_REGISTRY: Device/feature skills (VPCS, topology, etc.)
+- INJECTION_SKILLS_REGISTRY: Fault injection skills only
+- get_skill(): Function to retrieve device/feature skills
+- get_injection_skill(): Function to retrieve injection skills
+- DeviceSkillsTool: LangChain tool for device/feature skills
+- InjectionSkillsTool: LangChain tool for injection skills
+"""
+
+import json
+import logging
+from typing import Any
+
+from langchain.tools import BaseTool
+from langchain_core.callbacks import CallbackManagerForToolRun
+
+# command_filter imports are done locally in functions
+# to avoid circular import (command_filter also imports from registry)
+
+logger = logging.getLogger(__name__)
+
+# Device/Feature skills registry - loaded from external repository
+SKILLS_REGISTRY: dict[str, dict[str, Any]] = {}
+
+# Injection skills registry - fault injection skills only
+# This registry can be hot-reloaded via SkillsManager
+INJECTION_SKILLS_REGISTRY: dict[str, dict[str, Any]] = {}
+
+# Packet analysis protocols registry - loaded from external repository
+# Contains protocol definitions for tshark-based packet analysis
+PACKET_ANALYSIS_REGISTRY: dict[str, dict[str, Any]] = {}
+
+# Global skills manager instance for hot reload
+_skills_manager = None
+_init_in_progress = False
+
+
+def set_skills_manager(manager):
+    """
+    Set the global skills manager instance.
+
+    The skills manager handles Git operations and hot reload of skills.
+
+    Args:
+        manager: SkillsManager instance
+    """
+    global _skills_manager
+    _skills_manager = manager
+
+
+def _ensure_skills_manager():
+    """
+    Initialize the SkillsManager (idempotent, retryable on failure).
+
+    Reads config, creates SkillsManager, clones/pulls repo,
+    and loads skills/prompts into memory. Safe to call from
+    background threads - uses _init_in_progress to prevent
+    concurrent initialization.
+
+    On failure, resets _init_in_progress so future calls
+    (e.g., /reload/skills API) can retry. On success, the
+    manager is stored in _skills_manager and subsequent
+    calls return immediately.
+    """
+    global _skills_manager, _init_in_progress
+
+    if _skills_manager is not None:
+        return
+
+    if _init_in_progress:
+        return
+
+    _init_in_progress = True
+
+    try:
+        from gns3server.agent.gns3_copilot.configs.skills_config import get_skills_config
+        from gns3server.agent.gns3_copilot.skills.manager import SkillsManager
+
+        config = get_skills_config()
+
+        if not config.get("enabled", False):
+            logger.info("External skills repository is disabled")
+            return
+
+        logger.info("Initializing SkillsManager")
+
+        manager = SkillsManager(
+            repo_url=config.get("repo_url"),
+            branch=config.get("branch", "main"),
+            auto_update=config.get("auto_update", False)
+        )
+
+        if not manager.initialize():
+            logger.error("Failed to initialize skills repository")
+            return
+
+        if manager.reload_skills():
+            logger.debug(f"Loaded {manager.get_skill_count()} injection skills")
+        else:
+            logger.warning("Failed to reload injection skills")
+
+        if manager.reload_prompts():
+            logger.debug(f"Loaded {manager.get_prompt_count()} prompts")
+        else:
+            logger.warning("Failed to reload prompts")
+
+        if manager.reload_packet_analysis_protocols():
+            logger.debug(f"Loaded {len(PACKET_ANALYSIS_REGISTRY)} packet analysis protocols")
+        else:
+            logger.warning("Failed to reload packet analysis protocols")
+
+        _skills_manager = manager
+        logger.debug("SkillsManager initialized successfully")
+
+    except Exception as e:
+        logger.error(f"Error initializing skills manager: {e}", exc_info=True)
+    finally:
+        _init_in_progress = False
+
+
+def get_skills_manager():
+    """
+    Get the global skills manager instance, initializing on first access.
+
+    Returns:
+        SkillsManager instance or None
+    """
+    _ensure_skills_manager()
+    return _skills_manager
+
+
+def reload_skills_repository() -> dict[str, Any]:
+    """
+    Reload the entire skills repository.
+
+    Performs one git update check, then reloads all skills, prompts,
+    and forbidden commands from local files.
+
+    Returns:
+        Dictionary with combined reload results.
+    """
+    manager = get_skills_manager()
+    if manager is None:
+        return {
+            "success": False,
+            "message": "Skills manager not initialized",
+        }
+
+    # One git update for the entire repository
+    manager._update_if_needed()
+
+    # Reload everything from local files
+    skills_ok = manager.reload_skills()
+    prompts_ok = manager.reload_prompts()
+    protocols_ok = manager.reload_packet_analysis_protocols()
+
+    # Reload forbidden commands (local import to avoid circular dependency)
+    from gns3server.agent.gns3_copilot.utils.command_filter import reload_forbidden_commands as _reload_fc
+    from gns3server.agent.gns3_copilot.utils.command_filter import get_forbidden_commands
+
+    _reload_fc()
+    forbidden_commands = get_forbidden_commands()
+
+    return {
+        "success": skills_ok or prompts_ok or protocols_ok,
+        "skills": skills_ok,
+        "skill_count": manager.get_skill_count(),
+        "prompts": prompts_ok,
+        "prompt_count": manager.get_prompt_count(),
+        "protocols": protocols_ok,
+        "protocol_count": len(PACKET_ANALYSIS_REGISTRY),
+        "forbidden_commands": len(forbidden_commands),
+        "version": manager.get_current_version(),
+    }
+
+
+def reload_injection_skills() -> dict[str, Any]:
+    """
+    Trigger hot reload of injection skills.
+
+    This function uses the global skills manager to pull latest changes
+    from the skills repository and reload the INJECTION_SKILLS_REGISTRY.
+
+    Returns:
+        Dictionary with status information:
+        {
+            "success": bool,
+            "message": str,
+            "skill_count": int,
+            "version": str
+        }
+    """
+    manager = get_skills_manager()
+    if manager is None:
+        return {
+            "success": False,
+            "message": "Skills manager not initialized",
+            "skill_count": len(INJECTION_SKILLS_REGISTRY),
+            "version": ""
+        }
+
+    try:
+        success = manager.reload_skills()
+        return {
+            "success": success,
+            "message": "Skills reloaded successfully" if success else "Failed to reload skills",
+            "skill_count": manager.get_skill_count(),
+            "version": manager.get_current_version()
+        }
+    except Exception as e:
+        logger.error(f"Error during skills reload: {e}")
+        return {
+            "success": False,
+            "message": f"Error: {str(e)}",
+            "skill_count": len(INJECTION_SKILLS_REGISTRY),
+            "version": ""
+        }
+
+
+def reload_prompts() -> dict[str, Any]:
+    """
+    Trigger hot reload of system prompts.
+
+    This function uses the global skills manager to pull latest changes
+    from the skills repository and reload prompts from disk.
+
+    Returns:
+        Dictionary with status information:
+        {
+            "success": bool,
+            "message": str,
+            "prompt_count": int,
+            "version": str
+        }
+    """
+    manager = get_skills_manager()
+    if manager is None:
+        return {
+            "success": False,
+            "message": "Skills manager not initialized",
+            "prompt_count": 0,
+            "version": ""
+        }
+
+    try:
+        success = manager.reload_prompts()
+        return {
+            "success": success,
+            "message": "Prompts reloaded successfully" if success else "Failed to reload prompts",
+            "prompt_count": manager.get_prompt_count(),
+            "version": manager.get_current_version()
+        }
+    except Exception as e:
+        logger.error(f"Error during prompts reload: {e}")
+        manager = get_skills_manager()
+        return {
+            "success": False,
+            "message": f"Error: {str(e)}",
+            "prompt_count": manager.get_prompt_count() if manager else 0,
+            "version": ""
+        }
+
+
+def reload_forbidden_commands() -> dict[str, Any]:
+    """
+    Hot reload forbidden commands from the skills repository.
+
+    Directly loads and caches commands from the skills repository.
+
+    Returns:
+        Dictionary with status information:
+        {
+            "success": bool,
+            "message": str,
+            "command_count": int,
+            "version": str
+        }
+    """
+    try:
+        from gns3server.agent.gns3_copilot.utils.command_filter import reload_forbidden_commands as _reload
+        from gns3server.agent.gns3_copilot.utils.command_filter import get_forbidden_commands
+
+        _reload()
+        commands = get_forbidden_commands()
+        manager = get_skills_manager()
+        return {
+            "success": True,
+            "message": "Forbidden commands reloaded",
+            "command_count": len(commands),
+            "version": manager.get_current_version() if manager else ""
+        }
+    except Exception as e:
+        logger.error(f"Error during forbidden commands reload: {e}")
+        return {
+            "success": False,
+            "message": f"Error: {str(e)}",
+            "command_count": 0,
+            "version": ""
+        }
+
+
+def get_prompt(prompt_name: str) -> str:
+    """
+    Get a system prompt by name, always loading from disk.
+
+    Args:
+        prompt_name: Name of the prompt (e.g., "teaching_assistant")
+
+    Returns:
+        Prompt content as string, or empty string if not found
+    """
+    # Always load from skills manager (no cache), triggers lazy init
+    manager = get_skills_manager()
+    if manager:
+        try:
+            prompt = manager.load_prompt(prompt_name)
+            if prompt:
+                return prompt
+        except Exception as e:
+            logger.error(f"Error loading prompt '{prompt_name}': {e}")
+
+    logger.warning(f"Prompt not found: {prompt_name}")
+    return ""
+
+
+def get_skills_repository_info() -> dict[str, Any]:
+    """
+    Get information about the skills repository.
+
+    Returns:
+        Dictionary with repository information
+    """
+    manager = get_skills_manager()
+    if manager is None:
+        return {
+            "initialized": False,
+            "message": "Skills manager not initialized"
+        }
+
+    return manager.get_repository_info()
+
+
+def get_skill(
+    device_type: str,
+    category: str | None = None,
+    detail: str = "full",
+    issue: str | None = None,
+) -> dict[str, Any]:
+    """
+    Get skill by device_type, with configurable detail level.
+
+    Args:
+        device_type: The device type identifier
+        category: Optional category filter
+        detail: Detail level - "index" (names only), "summary" (+desc/sev/diff), "full" (all)
+        issue: Optional specific issue key to retrieve
+
+    Returns:
+        Skill dictionary (detail varies by level), or error dict
+    """
+    skill = SKILLS_REGISTRY.get(device_type, {})
+
+    if not skill:
+        for did, s in SKILLS_REGISTRY.items():
+            if s.get("name", "").lower() == device_type.lower():
+                skill = s
+                break
+
+    if not skill:
+        return {
+            "error": f"Unknown device_type: {device_type}",
+            "available_device_types": list(SKILLS_REGISTRY.keys()),
+        }
+
+    if category:
+        skill_category = skill.get("category", "")
+        if category.lower() != skill_category.lower():
+            return {
+                "error": f"device_type '{device_type}' is not in category '{category}'",
+                "device_category": skill.get("category"),
+                "available_in_category": [
+                    did for did, s in SKILLS_REGISTRY.items()
+                    if s.get("category", "").lower() == category.lower()
+                ],
+            }
+
+    issues = skill.get("issues", {})
+
+    # Single issue lookup (most token-efficient)
+    if issue:
+        issue_def = issues.get(issue)
+        if not issue_def:
+            return {
+                "error": f"Unknown issue '{issue}' in {device_type}",
+                "available_issues": list(issues.keys()),
+            }
+        return {
+            "device_type": device_type,
+            "skill_name": skill.get("name"),
+            "issue": {issue: issue_def},
+        }
+
+    if detail == "index":
+        # Minimal: only issue keys and names (90%+ token savings)
+        return {
+            "device_type": device_type,
+            "name": skill.get("name"),
+            "description": skill.get("description"),
+            "issues": {k: v["name"] for k, v in issues.items()},
+        }
+
+    if detail == "summary":
+        # Moderate: names + description + severity + difficulty
+        return {
+            "device_type": device_type,
+            "name": skill.get("name"),
+            "description": skill.get("description"),
+            "issues": {
+                k: {
+                    "name": v["name"],
+                    "description": v.get("description", ""),
+                    "severity": v.get("severity", ""),
+                    "difficulty": v.get("difficulty", ""),
+                }
+                for k, v in issues.items()
+            },
+        }
+
+    # Full detail (original behavior)
+    result = dict(skill)
+    result["device_type"] = device_type
+    return result
+
+
+def list_available_skills(category: str | None = None) -> list[dict[str, str]]:
+    """List all available device/feature skills, optionally filtered by category."""
+    skills = []
+    for did, skill in SKILLS_REGISTRY.items():
+        if category:
+            if skill.get("category", "").lower() == category.lower():
+                skills.append({
+                    "device_type": did,
+                    "name": skill.get("name", did),
+                    "category": skill.get("category"),
+                })
+        else:
+            skills.append({
+                "device_type": did,
+                "name": skill.get("name", did),
+                "category": skill.get("category"),
+            })
+    return skills
+
+
+def get_injection_skill(
+    device_type: str,
+    detail: str = "full",
+    issue: str | None = None,
+) -> dict[str, Any]:
+    """
+    Get injection fault skill by device_type, with configurable detail level.
+
+    Args:
+        device_type: The injection fault type (e.g., "injection_ospf")
+        detail: Detail level - "index" (names only), "summary" (+desc/sev/diff), "full" (all)
+        issue: Optional specific issue key to retrieve
+
+    Returns:
+        Skill dictionary (detail varies by level), or error dict
+    """
+    skill = INJECTION_SKILLS_REGISTRY.get(device_type, {})
+
+    if not skill:
+        return {
+            "error": f"Unknown injection fault type: {device_type}",
+            "available_fault_types": list(INJECTION_SKILLS_REGISTRY.keys()),
+            "hint": "Use {'action': 'list'} to see all available fault types"
+        }
+
+    issues = skill.get("issues", {})
+
+    # Single issue lookup (most token-efficient)
+    if issue:
+        issue_def = issues.get(issue)
+        if not issue_def:
+            return {
+                "error": f"Unknown issue '{issue}' in {device_type}",
+                "available_issues": list(issues.keys()),
+            }
+        return {
+            "device_type": device_type,
+            "skill_name": skill.get("name"),
+            "issue": {issue: issue_def},
+        }
+
+    if detail == "index":
+        # Minimal: only issue keys and names (90%+ token savings)
+        return {
+            "device_type": device_type,
+            "name": skill.get("name"),
+            "description": skill.get("description"),
+            "issues": {k: v["name"] for k, v in issues.items()},
+        }
+
+    if detail == "summary":
+        # Moderate: names + description + severity + difficulty
+        return {
+            "device_type": device_type,
+            "name": skill.get("name"),
+            "description": skill.get("description"),
+            "issues": {
+                k: {
+                    "name": v["name"],
+                    "description": v.get("description", ""),
+                    "severity": v.get("severity", ""),
+                    "difficulty": v.get("difficulty", ""),
+                }
+                for k, v in issues.items()
+            },
+        }
+
+    # Full detail (original behavior)
+    result = dict(skill)
+    result["device_type"] = device_type
+    return result
+
+
+def list_available_injection_skills(context: list[str] | None = None) -> list[dict[str, str]]:
+    """
+    List available injection fault skills, optionally filtered by context.
+
+    Args:
+        context: List of protocol/service keywords (e.g., ["ospf", "bgp", "vlan"]).
+                 Only returns skills whose category matches any keyword.
+
+    Returns:
+        List of skill info dicts with device_type, name, and category.
+    """
+    skills = []
+    for did, skill in INJECTION_SKILLS_REGISTRY.items():
+        category = skill.get("category", "")
+        if context:
+            # Match if skill category contains any context keyword
+            category_lower = category.lower()
+            if not any(kw.lower() in category_lower or kw.lower() in did.lower() for kw in context):
+                continue
+        skills.append({
+            "device_type": did,
+            "name": skill.get("name", did),
+            "category": category,
+        })
+    return skills
+
+
+def get_packet_analysis_protocol(protocol: str) -> dict[str, Any]:
+    """
+    Get a packet analysis protocol definition.
+
+    Args:
+        protocol: The protocol key (e.g., "ospf", "bgp", "icmp")
+
+    Returns:
+        Protocol definition dictionary with available_fields, base_filter, etc.
+        Returns error dict if protocol not found.
+    """
+    protocol_data = PACKET_ANALYSIS_REGISTRY.get(protocol)
+
+    if not protocol_data:
+        # Try case-insensitive match
+        for key, data in PACKET_ANALYSIS_REGISTRY.items():
+            if key.lower() == protocol.lower():
+                protocol_data = data
+                protocol = key
+                break
+
+    if not protocol_data:
+        return {
+            "error": f"Unknown protocol: {protocol}",
+            "available_protocols": list(PACKET_ANALYSIS_REGISTRY.keys()),
+        }
+
+    return protocol_data
+
+
+def list_available_packet_analysis_protocols() -> list[dict[str, str]]:
+    """
+    List all available packet analysis protocols.
+
+    Returns:
+        List of protocol info dicts with protocol, name, and description.
+    """
+    protocols = []
+    for key, data in PACKET_ANALYSIS_REGISTRY.items():
+        protocols.append({
+            "protocol": key,
+            "name": data.get("name", key),
+            "description": data.get("description", ""),
+        })
+    return protocols
+
+
+class DeviceSkillsTool(BaseTool):
+    """
+    LangChain tool for querying device/feature skills.
+
+    Use this tool to get device command knowledge, topology planning skills, etc.
+    For fault injection skills, use InjectionSkillsTool instead.
+    """
+
+    name: str = "device_skills"
+    description: str = """
+    Get or list device and feature specific skills.
+
+    Provides access to device command knowledge (VPCS), topology planning, etc.
+    For fault injection skills, use the injection_skills tool.
+
+    INPUT FORMAT (JSON string):
+    {
+        "action": "get",  # "get" (default) or "list"
+        "device_type": "gns3_vpcs_telnet",  # Required for action="get"
+        "detail": "full"  # "full" (default) for complete skill information
+    }
+
+    For action="list":
+    {"action": "list"}  # Lists all available device/feature skills
+    """
+
+    def _run(
+        self,
+        tool_input: str | dict[str, Any],
+        run_manager: CallbackManagerForToolRun | None = None,
+        **kwargs: Any,
+    ) -> str:
+        """Execute the device skills lookup."""
+        logger.debug("DeviceSkillsTool invoked with input: %s", tool_input)
+
+        if isinstance(tool_input, str):
+            try:
+                params = json.loads(tool_input)
+            except json.JSONDecodeError as e:
+                return json.dumps({
+                    "error": f"Invalid JSON input: {e}",
+                    "hint": 'Expected format: {"device_type": "xxx"} or {"action": "list"}'
+                }, ensure_ascii=False, indent=2)
+        else:
+            params = tool_input
+
+        action = params.get("action", "get")
+
+        if action == "list":
+            skills = list_available_skills()
+            return json.dumps({
+                "count": len(skills),
+                "skills": skills
+            }, ensure_ascii=False, indent=2)
+
+        device_type = params.get("device_type")
+        if not device_type:
+            return json.dumps({
+                "error": "Missing required field: device_type",
+                "available_device_types": list(SKILLS_REGISTRY.keys()),
+                "hint": 'Use {"action": "list"} to see all available device types'
+            }, ensure_ascii=False, indent=2)
+
+        category = params.get("category")
+        detail = params.get("detail", "full")
+        issue = params.get("issue")
+
+        skill = get_skill(device_type, category, detail=detail, issue=issue)
+
+        return json.dumps(skill, ensure_ascii=False, indent=2)
+
+
+class InjectionSkillsTool(BaseTool):
+    """
+    LangChain tool for querying fault injection skills.
+
+    Use this tool to list available injection fault types and get fault details.
+    """
+
+    name: str = "injection_skills"
+    description: str = """
+    Get or list network fault injection skills for troubleshooting practice.
+
+    REQUIRED: When action="list", you MUST always pass "context" with the
+    protocols/services found in your topology analysis.
+    Example: {"action": "list", "context": ["ospf", "bgp", "mpls", "vlan", "stp"]}
+
+    TOKEN-EFFICIENT USAGE:
+    1. List faults for YOUR topology protocols (REQUIRED):
+       {"action": "list", "context": ["ospf", "bgp"]}
+    2. Get specific fault details:
+       {"device_type": "injection_ospf", "issue": "ospf_hello_dead_mismatch"}
+       {"device_type": "injection_ospf", "detail": "index"}
+
+    PARAMETERS:
+    - action: "list" or "get"
+    - context: [str] - REQUIRED for action="list". Protocols from your topology.
+    - device_type: Required for action="get" (e.g., "injection_ospf")
+    - detail: "index" | "summary" | "full"
+    - issue: Get single fault detail by key
+    """
+
+    def _run(
+        self,
+        tool_input: str | dict[str, Any],
+        run_manager: CallbackManagerForToolRun | None = None,
+        **kwargs: Any,
+    ) -> str:
+        """Execute the injection skills lookup."""
+        logger.debug("InjectionSkillsTool invoked with input: %s", tool_input)
+
+        if isinstance(tool_input, str):
+            try:
+                params = json.loads(tool_input)
+            except json.JSONDecodeError as e:
+                return json.dumps({
+                    "error": f"Invalid JSON input: {e}",
+                    "hint": 'Expected format: {"device_type": "xxx"} or {"action": "list"}'
+                }, ensure_ascii=False, indent=2)
+        else:
+            params = tool_input
+
+        action = params.get("action", "get")
+
+        if action == "list":
+            context = params.get("context")
+            if not context or not isinstance(context, list) or len(context) == 0:
+                return json.dumps({
+                    "error": "context parameter is required when action='list'",
+                    "hint": "Analyze the topology and device configurations first, "
+                            "then pass the protocols/services you found as context. "
+                            'Example: {"action": "list", "context": ["ospf", "bgp", "vlan"]}',
+                    "available_categories": sorted(set(
+                        skill.get("category", "")
+                        for skill in INJECTION_SKILLS_REGISTRY.values()
+                    ))
+                }, ensure_ascii=False, indent=2)
+
+            skills = list_available_injection_skills(context=context)
+            logger.debug(f"Injection skills filtered by context={context}: {len(skills)} matching")
+            return json.dumps({
+                "count": len(skills),
+                "total_available": len(INJECTION_SKILLS_REGISTRY),
+                "context": context,
+                "fault_types": skills
+            }, ensure_ascii=False, indent=2)
+
+        device_type = params.get("device_type")
+        if not device_type:
+            return json.dumps({
+                "error": "Missing required field: device_type",
+                "available_fault_types": list(INJECTION_SKILLS_REGISTRY.keys()),
+                "hint": 'Use {"action": "list"} to see all available fault types'
+            }, ensure_ascii=False, indent=2)
+
+        detail = params.get("detail", "full")
+        issue = params.get("issue")
+
+        skill = get_injection_skill(device_type, detail=detail, issue=issue)
+
+        return json.dumps(skill, ensure_ascii=False, indent=2)
+
+
+class PacketAnalysisSkillsTool(BaseTool):
+    """
+    LangChain tool for querying packet analysis protocol definitions.
+
+    Use this tool to list available protocols and get protocol-specific
+    tshark fields, display filters, and check rules.
+    """
+
+    name: str = "packet_analysis_skills"
+    description: str = """
+    Get or list packet analysis protocol definitions.
+
+    Before calling packet_analysis tool, use this to query the protocol's
+    available tshark fields, display filters, and check rules.
+
+    USAGE:
+    - List available protocols:
+      {"action": "list"}
+
+    - Get protocol definition with fields:
+      {"action": "get", "protocol": "ospf"}
+
+    PARAMETERS:
+    - action: "list" or "get" (required)
+    - protocol: Protocol key for action="get" (e.g., "ospf", "bgp", "arp", "icmp")
+    """
+
+    def _run(
+        self,
+        tool_input: str | dict[str, Any],
+        run_manager: CallbackManagerForToolRun | None = None,
+        **kwargs: Any,
+    ) -> str:
+        """Execute the packet analysis skills lookup."""
+        logger.debug("PacketAnalysisSkillsTool invoked with input: %s", tool_input)
+
+        if isinstance(tool_input, str):
+            try:
+                params = json.loads(tool_input)
+            except json.JSONDecodeError as e:
+                return json.dumps({
+                    "error": f"Invalid JSON input: {e}",
+                    "hint": 'Expected format: {"action": "get", "protocol": "ospf"}'
+                }, ensure_ascii=False, indent=2)
+        else:
+            params = tool_input
+
+        action = params.get("action", "get")
+
+        if action == "list":
+            protocols = list_available_packet_analysis_protocols()
+            return json.dumps({
+                "count": len(protocols),
+                "protocols": protocols
+            }, ensure_ascii=False, indent=2)
+
+        protocol = params.get("protocol")
+        if not protocol:
+            return json.dumps({
+                "error": "Missing required field: protocol",
+                "available_protocols": list(PACKET_ANALYSIS_REGISTRY.keys()),
+            }, ensure_ascii=False, indent=2)
+
+        result = get_packet_analysis_protocol(protocol)
+        return json.dumps(result, ensure_ascii=False, indent=2)

gns3server/agent/gns3_copilot/tools_v2/__init__.py

@@ -0,0 +1,96 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# GNS3-Copilot - AI-powered Network Lab Assistant for GNS3
+#
+# This file is part of GNS3-Copilot project.
+#
+# GNS3-Copilot is free software: you can redistribute it and/or modify it
+# under the terms of the GNU General Public License as published by the
+# Free Software Foundation, either version 3 of the License, or (at your
+# option) any later version.
+#
+# GNS3-Copilot is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+# or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+# for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with GNS3-Copilot. If not, see <https://www.gnu.org/licenses/>.
+#
+# Copyright (C) 2025 Yue Guobin (岳国宾)
+# Author: Yue Guobin (岳国宾)
+#
+# Project Home: https://github.com/yueguobin/gns3-copilot
+#
+"""
+
+GNS3-Copilot Tools Package
+
+This package provides various tools for interacting with GNS3 network simulator:
+- Device configuration command execution
+- Display command execution
+- Multiple device command execution using Nornir
+- VPCS device configuration using Netmiko
+- Node and link management
+- Packet filter management
+
+Main modules:
+- config_tools_nornir: Multiple device configuration command execution tool using Nornir
+- display_tools_nornir: Multiple device command execution tool using Nornir
+- vpcs_tools_netmiko: VPCS device configuration tool using Netmiko
+- gns3_create_node: GNS3 node creation tool
+- gns3_create_link: GNS3 link creation tool
+- gns3_start_node: GNS3 node startup tool
+- gns3_get_node_temp: GNS3 template retrieval tool
+- gns3_update_node_name: GNS3 node name update tool
+- gns3_packet_filter: GNS3 packet filter management tool
+
+Note: GNS3TopologyTool is now available from gns3_client package
+
+Author: Yue Guobin (岳国宾)
+"""
+
+# Import main tool classes
+from .config_tools_nornir import ExecuteMultipleDeviceConfigCommands
+from .display_tools_nornir import ExecuteMultipleDeviceCommands
+from .gns3_create_link import GNS3LinkTool
+from .gns3_create_node import GNS3CreateNodeTool
+from .gns3_get_node_temp import GNS3TemplateTool
+from .gns3_packet_filter import GNS3PacketFilterTool
+from .gns3_start_node import GNS3StartNodeQuickTool
+from .gns3_start_node import GNS3StartNodeTool
+from .gns3_stop_node import GNS3StopNodeTool
+from .gns3_suspend_node import GNS3SuspendNodeTool
+from .gns3_update_node_name import GNS3UpdateNodeNameTool
+from .packet_analysis_tool import PacketAnalysisTool
+
+# Dynamic version management
+try:
+    from importlib.metadata import version
+
+    __version__ = version("gns3-copilot")
+except Exception:
+    __version__ = "unknown"
+
+__author__ = "Yue Guobin (岳国宾)"
+__description__ = "AI-powered network automation assistant for GNS3"
+__url__ = "https://github.com/yueguobin/gns3-copilot"
+
+# Export main tool classes
+__all__ = [
+    "ExecuteMultipleDeviceConfigCommands",
+    "ExecuteMultipleDeviceCommands",
+    "GNS3CreateNodeTool",
+    "GNS3LinkTool",
+    "GNS3PacketFilterTool",
+    "GNS3StartNodeTool",
+    "GNS3StartNodeQuickTool",
+    "GNS3StopNodeTool",
+    "GNS3SuspendNodeTool",
+    "GNS3UpdateNodeNameTool",
+    "GNS3TemplateTool",
+    "PacketAnalysisTool",
+]
+
+# Package initialization message
+# print(f"GNS3-Copilot Tools package loaded (version {__version__})")

gns3server/agent/gns3_copilot/tools_v2/config_tools_nornir.py

@@ -0,0 +1,789 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# GNS3-Copilot - AI-powered Network Lab Assistant for GNS3
+#
+# This file is part of GNS3-Copilot project.
+#
+# GNS3-Copilot is free software: you can redistribute it and/or modify it
+# under the terms of the GNU General Public License as published by the
+# Free Software Foundation, either version 3 of the License, or (at your
+# option) any later version.
+#
+# GNS3-Copilot is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+# or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+# for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with GNS3-Copilot. If not, see <https://www.gnu.org/licenses/>.
+#
+# Copyright (C) 2025 Yue Guobin (岳国宾)
+# Author: Yue Guobin (岳国宾)
+#
+# Project Home: https://github.com/yueguobin/gns3-copilot
+#
+"""
+
+This module provides a tool to execute configuration commands on multiple
+ devices in a GNS3 topology using Nornir.
+
+⚠️ WARNING: This module is shared with the MCP (Model Context Protocol) service.
+ExecuteMultipleDeviceConfigCommands._run() is called by the MCP device_config_send handler.
+The jwt_token/url parameters were added for MCP compatibility.
+Modifications must be tested with BOTH gns3-copilot AND MCP.
+"""
+
+import json
+import logging
+import re
+from typing import Any
+
+from langchain.tools import BaseTool
+from langchain_core.callbacks import CallbackManagerForToolRun
+from netmiko.exceptions import ReadTimeout
+from nornir import InitNornir
+from nornir.core import Nornir
+from nornir.core.task import AggregatedResult
+from nornir.core.task import Result
+from nornir.core.task import Task
+from nornir_netmiko.tasks import netmiko_send_config
+
+from gns3server.agent.gns3_copilot.gns3_client import get_gns3_server_host
+from gns3server.agent.gns3_copilot.utils import get_device_ports_from_topology
+from gns3server.agent.gns3_copilot.utils.command_filter import (
+    filter_forbidden_commands,
+)
+
+# Import custom Netmiko device types for GNS3 emulation
+# This registers gns3_huawei_telnet_ce and other custom device types
+# NOTE: Must be imported BEFORE any Nornir operations to ensure device types are registered
+from gns3server.agent.gns3_copilot.utils import custom_netmiko  # noqa: F401
+
+# Explicitly register custom device types to ensure they are available
+# This is a safety measure in case the auto-registration on import doesn't work
+try:
+    from gns3server.agent.gns3_copilot.utils.custom_netmiko import huawei_ce
+    from gns3server.agent.gns3_copilot.utils.custom_netmiko.ruijie_telnet import (
+        register_custom_device_type as register_ruijie_device_type,
+    )
+
+    # Re-register to ensure device types are available
+    huawei_ce.register_custom_device_type()
+    register_ruijie_device_type()
+
+    # CRITICAL: Update netmiko.ssh_dispatcher platforms lists
+    # The platforms variable is calculated at module import time in ssh_dispatcher
+    # We need to update it after registering custom device types.
+    # NOTE: netmiko.ssh_dispatcher is aliased to ConnectHandler function,
+    # so we use importlib to get the actual module
+    import importlib
+
+    sd = importlib.import_module("netmiko.ssh_dispatcher")
+
+    # Recalculate platforms lists to include custom device types
+    sd.platforms = list(sd.CLASS_MAPPER.keys())
+    sd.platforms.sort()
+
+    sd.platforms_base = list(sd.CLASS_MAPPER_BASE.keys())
+    sd.platforms_base.sort()
+
+    sd.telnet_platforms = [x for x in sd.platforms if "telnet" in x]
+
+    # Update platform strings used in error messages
+    sd.platforms_str = "\n" + "\n".join(sd.platforms_base)
+    sd.telnet_platforms_str = "\n" + "\n".join(sd.telnet_platforms)
+except Exception:
+    # Fail silently - the import-time registration should have worked
+    pass
+
+# config log
+logger = logging.getLogger(__name__)
+
+# Suppress nornir INFO logs in console (reduce verbosity)
+# The logging={"enabled": False} in InitNornir only disables plugin
+# internal logs, but nornir.core still logs task execution at INFO level.
+# Set to WARNING to suppress these.
+logging.getLogger("nornir.core").setLevel(logging.WARNING)
+logging.getLogger("nornir").setLevel(logging.WARNING)
+
+
+# Local Nornir configuration functions for network devices
+def _get_nornir_defaults() -> dict[str, Any]:
+    """Get Nornir default configuration."""
+    return {"data": {"location": "gns3"}}
+
+
+class ExecuteMultipleDeviceConfigCommands(BaseTool):
+    """
+    A tool to execute configuration commands on multiple devices in a GNS3
+    topology using Nornir.
+    This class uses Nornir to manage connections and execute configuration
+    commands on multiple devices concurrently.
+
+    IMPORTANT SAFETY NOTE:
+    This tool is intended for configuration changes only. Use extreme caution
+    when executing configuration commands.
+    """
+
+    name: str = "execute_multiple_device_config_commands"
+    description: str = """
+    Executes CONFIGURATION commands on multiple devices in the current GNS3
+    topology.
+    Use this tool ONLY for changing device settings (e.g., 'configure',
+    'interface', 'ip address', 'router ospf').
+    For viewing information, use the 'execute_multiple_device_commands' tool.
+    Input should be a JSON object containing project_id and device configs.
+    Example input:
+        {
+            "project_id": "<PROJECT_UUID>",
+            "device_configs": [
+                {
+                    "device_name": "R-1",
+                    "config_commands": [
+                        "interface Loopback0",
+                        "ip address 1.1.1.1 255.255.255.255",
+                        "description CONFIG_BY_TOOL"
+                    ]
+                },
+                {
+                    "device_name": "R-2",
+                    "config_commands": [
+                        "interface Loopback0",
+                        "ip address 2.2.2.2 255.255.255.255",
+                        "description CONFIG_BY_TOOL"
+                    ]
+                }
+            ]
+        }
+    Returns a list of dicts with device name and config results.
+
+    IMPORTANT SAFETY WARNING:
+    Do NOT use this tool for dangerous operations that could reboot, erase,
+    or factory-reset devices.
+    Forbidden operations include but are not limited to:
+    - reload / reboot commands
+    - write erase / erase startup-config
+    - format / erase nvram / delete flash:
+    - boot system commands
+    - factory-reset commands
+    - any commands that require user confirmation prompts
+    - NEVER use 'exit' command - this disconnects the session and breaks subsequent commands
+    """
+
+    def _run(
+        self,
+        tool_input: str,  # or Union[str, List[Any], Dict[str, Any]]
+        run_manager: CallbackManagerForToolRun | None = None,
+        jwt_token: str | None = None,
+        url: str | None = None,
+        **kwargs: Any,
+    ) -> list[dict[str, Any]]:
+        """
+        Executes configuration commands on multiple devices in GNS3 topology.
+
+        Args:
+            tool_input (str): A JSON string containing project_id and device
+             configuration commands to execute.
+            jwt_token: JWT token for GNS3 API auth (MCP handlers).
+            url: GNS3 server URL (MCP handlers).
+
+        Returns:
+            List[Dict[str, Any]]: A list of dicts containing device names and
+             configuration results.
+        """
+        # Log received input
+        logger.debug("Received input: %s", tool_input)
+
+        # Validate input
+        device_configs_list, project_id = self._validate_tool_input(tool_input)
+        if (
+            isinstance(device_configs_list, list)
+            and len(device_configs_list) > 0
+            and "error" in device_configs_list[0]
+        ):
+            return device_configs_list
+
+        # Filter forbidden commands and store blocked commands info
+        device_configs_list, blocked_commands_map = (
+            self._filter_forbidden_commands_from_device_configs(
+                device_configs_list
+            )
+        )
+
+        # Expand multiline commands (e.g., banner commands with embedded newlines)
+        # This converts commands like "banner motd #\nline1\nline2\n#" into
+        # separate commands: ["banner motd #", "line1", "line2", "#"]
+        device_configs_list = self._expand_multiline_commands(
+            device_configs_list
+        )
+
+        # Create a mapping of device names to their configuration commands
+        device_configs_map = self._configs_map(device_configs_list)
+
+        # Prepare device hosts data
+        try:
+            hosts_data = self._prepare_device_hosts_data(
+                device_configs_list, project_id, jwt_token=jwt_token, url=url
+            )
+        except ValueError as e:
+            logger.error("Failed to prepare device hosts data: %s", e)
+            return [{"error": str(e)}]
+
+        # Check if any devices have errors (e.g., missing device_type tag)
+        error_devices = {
+            name: data
+            for name, data in hosts_data.items()
+            if "error" in data
+        }
+        if error_devices:
+            logger.error(
+                "Devices with configuration errors: %s",
+                list(error_devices.keys())
+            )
+            return [
+                {
+                    "device_name": name,
+                    "status": "failed",
+                    "error": data["error"]
+                }
+                for name, data in error_devices.items()
+            ]
+
+        # Initialize Nornir
+        try:
+            dynamic_nr = self._initialize_nornir(hosts_data)
+        except ValueError as e:
+            logger.error("Failed to initialize Nornir: %s", e)
+            return [{"error": str(e)}]
+
+        results = []
+
+        # Execute all devices concurrently in a single run
+        try:
+            task_result = dynamic_nr.run(
+                task=self._run_all_device_configs_with_single_retry,
+                device_configs_map=device_configs_map,
+            )
+
+            # Process results for all devices
+            results = self._process_task_results(
+                device_configs_list,
+                hosts_data,
+                task_result,
+                blocked_commands_map,
+            )
+
+        except Exception as e:
+            # Overall execution failed
+            logger.error(
+                "Error executing configurations on all devices: %s", e
+            )
+            return [{"error": f"Execution error: {str(e)}"}]
+
+        logger.info(
+            "Multiple device configuration execution completed. Results: %s",
+            json.dumps(results, indent=2, ensure_ascii=False),
+        )
+
+        return results
+
+    def _run_all_device_configs_with_single_retry(
+        self, task: Task, device_configs_map: dict[str, list[str]]
+    ) -> Result:
+        """Execute configuration commands with single retry mechanism."""
+        device_name = task.host.name
+        config_commands = device_configs_map.get(device_name, [])
+
+        if not config_commands:
+            return Result(
+                host=task.host, result="No configuration commands to execute"
+            )
+
+        try:
+            _result = task.run(
+                task=netmiko_send_config, config_commands=config_commands
+            )
+            return Result(host=task.host, result=_result.result)
+
+        except ReadTimeout as e:
+            # Log ReadTimeout exception with full details
+            logger.error(
+                "ReadTimeout occurred for device %s: %s",
+                device_name,
+                str(e),
+            )
+            return Result(
+                host=task.host,
+                result=f"Configuration failed (ReadTimeout): {str(e)}",
+                failed=True,
+            )
+
+        except Exception as e:
+            # Handle Cisco IOSv L2 where '#' prompt char may be delayed,
+            # causing Netmiko failures. Implements retry logic.
+            if "netmiko_send_config (failed)" in str(e):
+                _result = task.run(
+                    task=netmiko_send_config, config_commands=config_commands
+                )
+                return Result(host=task.host, result=_result.result)
+
+            # Log any other exceptions with full details
+            logger.error(
+                "Configuration failed for device %s: %s (Exception type: %s)",
+                device_name,
+                str(e),
+                type(e).__name__,
+            )
+            return Result(
+                host=task.host,
+                result=f"Configuration failed (Unhandled Exception): {str(e)}",
+                failed=True,
+            )
+
+    def _validate_tool_input(
+        self, tool_input: str | bytes | list[Any] | dict[str, Any]
+    ) -> tuple[list[dict[str, Any]], str | None]:
+        """
+        Validate device config command input, handling new and legacy formats.
+        Supports new format with project_id and device_configs.
+
+        Args:
+            tool_input: Input from the LangChain/LangGraph tool call.
+
+        Returns:
+            Tuple of (device_configs_list, project_id) or (error_list, None)
+        """
+
+        parsed_input = None
+
+        # Compatibility Check and Parsing ---
+        # Check if the input is a string (or bytes) which needs to be parsed.
+        if isinstance(tool_input, (str, bytes, bytearray)):
+            # Handle models (like DeepSeek) that return a raw JSON string.
+            try:
+                parsed_input = json.loads(tool_input)
+                logger.debug("Successfully parsed tool input from JSON string.")
+            except json.JSONDecodeError as e:
+                logger.error(
+                    "Invalid JSON string received as tool input: %s", e
+                )
+                return (
+                    [{"error": f"Invalid JSON string input from model: {e}"}],
+                    None,
+                )
+        else:
+            # Handle standard models (like GPT/OpenAI) where the framework
+            # has already parsed the JSON into a Python object (dict or list).
+            parsed_input = tool_input
+            logger.info(
+                "Using tool input directly as type: %s",
+                type(parsed_input).__name__,
+            )
+
+        # Handle new format: {"project_id": "...", "device_configs": [...]}
+        if isinstance(parsed_input, dict):
+            project_id = parsed_input.get("project_id")
+            device_configs = parsed_input.get("device_configs")
+
+            # Validate project_id
+            if not project_id:
+                error_msg = "Missing required 'project_id' field in input"
+                logger.error(error_msg)
+                return ([{"error": error_msg}], None)
+
+            if not self._validate_project_id(project_id):
+                error_msg = (
+                    f"Invalid project_id format: {project_id}. "
+                    "Expected UUID format."
+                )
+                logger.error(error_msg)
+                return ([{"error": error_msg}], None)
+
+            # Validate device_configs
+            if not isinstance(device_configs, list):
+                error_msg = "'device_configs' must be an array"
+                logger.error(error_msg)
+                return ([{"error": error_msg}], None)
+
+            if not device_configs:
+                logger.warning("Device configs list is empty.")
+                return [], project_id
+
+            return device_configs, project_id
+
+        # Handle legacy format: [...]
+        elif isinstance(parsed_input, list):
+            logger.warning(
+                "Using legacy format without project_id. "
+                "Please use new format with project_id."
+            )
+            return parsed_input, None
+
+        else:
+            error_msg = (
+                "Tool input must be a JSON object with 'project_id' and "
+                f"'device_configs' fields, or a legacy JSON array, but got "
+                f"{type(parsed_input).__name__}"
+            )
+            logger.error(error_msg)
+            return ([{"error": error_msg}], None)
+
+    def _validate_project_id(self, project_id: str) -> bool:
+        """
+        Validate project_id format (UUID).
+
+        Args:
+            project_id: The project ID to validate
+
+        Returns:
+            True if valid UUID format, False otherwise
+        """
+        uuid_pattern = (
+            r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
+        )
+        return bool(re.match(uuid_pattern, project_id, re.IGNORECASE))
+
+    def _filter_forbidden_commands_from_device_configs(
+        self, device_configs_list: list[dict[str, Any]]
+    ) -> tuple[list[dict[str, Any]], dict[str, dict[str, str]]]:
+        """
+        Filter out forbidden commands from device configurations.
+
+        Args:
+            device_configs_list: List of device configs with config_commands.
+
+        Returns:
+            Tuple of (filtered_configs, blocked_map):
+            - filtered_configs: Device configs with forbidden removed.
+            - blocked_map: Dict mapping device names to blocked info.
+        """
+        filtered_list = []
+        blocked_commands_map: dict[str, dict[str, str]] = {}
+
+        for device_config in device_configs_list:
+            device_name = device_config["device_name"]
+            commands = device_config["config_commands"]
+
+            # Filter commands
+            allowed_commands, blocked_info = filter_forbidden_commands(
+                commands
+            )
+
+            # Update device config with allowed commands only
+            filtered_config = device_config.copy()
+            filtered_config["config_commands"] = allowed_commands
+            filtered_list.append(filtered_config)
+
+            # Store blocked commands info if any
+            if blocked_info:
+                blocked_commands_map[device_name] = blocked_info
+                logger.info(
+                    "Device %s: %d command(s) blocked: %s",
+                    device_name,
+                    len(blocked_info),
+                    list(blocked_info.keys()),
+                )
+
+        return filtered_list, blocked_commands_map
+
+    def _expand_multiline_commands(
+        self, device_configs_list: list[dict[str, Any]]
+    ) -> list[dict[str, Any]]:
+        """
+        Expand commands that contain embedded newline characters.
+
+        Some commands (like banner) are passed as single strings with embedded
+        newlines. This method splits them into separate commands for proper
+        execution by netmiko_send_config.
+
+        Note: netmiko_send_config automatically handles entering config mode,
+        so any config mode entry commands (configure terminal, system-view, etc.)
+        are left as-is and will be safely ignored by the device.
+
+        Example:
+            Input:  ["banner motd #\nline1\nline2\n#", "exit"]
+            Output: ["banner motd #", "line1", "line2", "#", "exit"]
+
+        Args:
+            device_configs_list: List of device configs with config_commands.
+
+        Returns:
+            List of device configs with multiline commands expanded.
+        """
+        expanded_list = []
+
+        for device_config in device_configs_list:
+            device_name = device_config["device_name"]
+            config_commands = device_config["config_commands"]
+
+            expanded_commands = []
+            for cmd in config_commands:
+                # Check if command contains embedded newlines
+                if "\n" in cmd:
+                    # Split by newline and expand
+                    lines = cmd.split("\n")
+                    # Filter out empty lines but keep all content lines
+                    expanded_commands.extend([line for line in lines if line.strip()])
+                    logger.info(
+                        "Device %s: Expanded multiline command (%d lines)",
+                        device_name,
+                        len(lines),
+                    )
+                else:
+                    # Keep single-line commands as-is
+                    expanded_commands.append(cmd)
+
+            # Create updated device config
+            expanded_config = device_config.copy()
+            expanded_config["config_commands"] = expanded_commands
+            expanded_list.append(expanded_config)
+
+        return expanded_list
+
+    def _configs_map(
+        self, device_config_list: list[dict[str, Any]]
+    ) -> dict[str, list[str]]:
+        """Create a mapping of device names to their configuration commands."""
+        device_configs_map = {}
+        for device_config in device_config_list:
+            device_name = device_config["device_name"]
+            config_commands = device_config["config_commands"]
+            device_configs_map[device_name] = config_commands
+
+        return device_configs_map
+
+    def _prepare_device_hosts_data(
+        self,
+        device_config_list: list[dict[str, Any]],
+        project_id: str | None = None,
+        jwt_token: str | None = None,
+        url: str | None = None,
+    ) -> dict[str, dict[str, Any]]:
+        """Prepare device hosts data from topology information."""
+        # Extract device names list
+        device_names = [
+            device_config["device_name"]
+            for device_config in device_config_list
+        ]
+
+        # Get device port information with project_id
+        hosts_data = get_device_ports_from_topology(
+            device_names, project_id, jwt_token=jwt_token, url=url
+        )
+
+        if not hosts_data:
+            error_msg = (
+                "Failed to get device info from topology or no valid devices. "
+                f"Project ID: {project_id}, Devices: {device_names}"
+            )
+            raise ValueError(error_msg)
+
+        # Check for missing devices
+        missing_devices = set(device_names) - set(hosts_data.keys())
+        if missing_devices:
+            logger.warning(
+                "Some devices not found in topology (Project ID: %s): %s",
+                project_id or "default",
+                missing_devices,
+            )
+
+        return hosts_data
+
+    def _initialize_nornir(
+        self, hosts_data: dict[str, dict[str, Any]]
+    ) -> Nornir:
+        """
+        Initialize Nornir with the provided hosts data.
+
+        Each host now has its own connection_options (device_type), so we only
+        need a single generic group for shared configuration (hostname, timeout, etc.).
+        This is the Nornir best practice for multi-vendor environments.
+        """
+        try:
+            defaults = _get_nornir_defaults()
+            gns3_host = get_gns3_server_host()
+
+            # Create a single generic group for shared configuration
+            # Individual device types are handled at host level via connection_options
+            groups_data = {
+                "network_devices": {
+                    "hostname": gns3_host,
+                    "timeout": 120,
+                    "username": "",
+                    "password": "",
+                }
+            }
+
+            # Log device types being configured
+            device_types = [
+                host["connection_options"]["netmiko"]["extras"]["device_type"]
+                for host in hosts_data.values()
+            ]
+            logger.info(
+                "Initializing Nornir: host=%s, device_types=%s, hosts=%d",
+                gns3_host,
+                list(set(device_types)),
+                len(hosts_data),
+            )
+
+            return InitNornir(
+                inventory={
+                    "plugin": "DictInventory",
+                    "options": {
+                        "hosts": hosts_data,
+                        "groups": groups_data,
+                        "defaults": defaults,
+                    },
+                },
+                runner={
+                    "plugin": "threaded",
+                    "options": {"num_workers": 10},
+                },
+                logging={"enabled": False},
+            )
+        except Exception as e:
+            logger.error("Failed to initialize Nornir: %s", e)
+            raise ValueError(f"Failed to initialize Nornir: {e}") from e
+
+    def _process_task_results(
+        self,
+        device_configs_list: list[dict[str, Any]],
+        hosts_data: dict[str, dict[str, Any]],
+        task_result: AggregatedResult,
+        blocked_commands_map: dict[str, dict[str, str]],
+    ) -> list[dict[str, Any]]:
+        """Process the task results and format them for return."""
+        results = []
+
+        for device_config in device_configs_list:
+            device_name = device_config["device_name"]
+            config_commands = device_config["config_commands"]
+            blocked_commands_info = blocked_commands_map.get(device_name, {})
+
+            # Check if device is in topology
+            if device_name not in hosts_data:
+                device_result = {
+                    "device_name": device_name,
+                    "status": "failed",
+                    "error": (
+                        f"Device '{device_name}' not found in topology or "
+                        "missing console_port"
+                    ),
+                }
+                # Add blocked commands info if any
+                if blocked_commands_info:
+                    device_result["blocked_commands"] = list(
+                        blocked_commands_info.keys()
+                    )
+                    device_result["blocked_info"] = blocked_commands_info
+                results.append(device_result)
+                continue
+
+            # Check if device has execution results
+            if device_name not in task_result:
+                device_result = {
+                    "device_name": device_name,
+                    "status": "failed",
+                    "error": (
+                        f"Device '{device_name}' not found in task results"
+                    ),
+                }
+                # Add blocked commands info if any
+                if blocked_commands_info:
+                    device_result["blocked_commands"] = list(
+                        blocked_commands_info.keys()
+                    )
+                    device_result["blocked_info"] = blocked_commands_info
+                results.append(device_result)
+                continue
+
+            # Process execution results
+            multi_result = task_result[device_name]
+            device_result = {"device_name": device_name}
+
+            if multi_result[0].failed:
+                # Execution failed
+                device_result["status"] = "failed"
+                device_result["error"] = (
+                    f"Configuration execution failed: {multi_result[0].result}"
+                )
+                device_result["output"] = multi_result[0].result
+            else:
+                # Execution successful
+                device_result["status"] = "success"
+                device_result["output"] = multi_result[0].result
+                device_result["config_commands"] = config_commands
+
+            # Add blocked commands info if any
+            if blocked_commands_info:
+                device_result["blocked_commands"] = list(
+                    blocked_commands_info.keys()
+                )
+                device_result["blocked_info"] = blocked_commands_info
+                # Update status if some commands were blocked but succeeded
+                if device_result["status"] == "success":
+                    device_result["status"] = "partial_success"
+
+            results.append(device_result)
+
+        return results
+
+
+if __name__ == "__main__":
+    # Example usage with new format
+    # example tool_input with project_id
+    input_paras = json.dumps(
+        {
+            "project_id": "<PROJECT_UUID>",
+            "device_configs": [
+                {
+                    "device_name": "R-1",
+                    "config_commands": [
+                        "interface Loopback1110",
+                        "ip address 201.201.201.201 255.255.255.255",
+                        "description CONFIG_BY_TOOL",
+                    ],
+                },
+                {
+                    "device_name": "R-2",
+                    "config_commands": [
+                        "interface Loopback1110",
+                        "ip address 202.202.202.202 255.255.255.255",
+                        "description CONFIG_BY_TOOL",
+                    ],
+                },
+                {
+                    "device_name": "SW-2",
+                    "config_commands": [
+                        "interface Loopback1110",
+                        "ip address 202.202.202.202 255.255.255.255",
+                        "description CONFIG_BY_TOOL",
+                    ],
+                },
+                {
+                    "device_name": "SW-1",
+                    "config_commands": [
+                        "interface Loopback1110",
+                        "ip address 202.202.202.202 255.255.255.255",
+                        "description CONFIG_BY_TOOL",
+                    ],
+                },
+            ],
+        }
+    )
+
+    exe_config = ExecuteMultipleDeviceConfigCommands()
+
+    failed_count = 0
+
+    for _i in range(0, 5):
+        exe_results = exe_config._run(tool_input=input_paras)
+        for result in exe_results:
+            for result in exe_results:
+                if result.get("status") == "failed":
+                    failed_count += 1
+
+    print(f"Failed Count: {failed_count}")
+
+    # print("Execution results:")
+    # print(json.dumps(result, indent=2, ensure_ascii=False))

gns3server/agent/gns3_copilot/tools_v2/display_tools_nornir.py

@@ -0,0 +1,715 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# GNS3-Copilot - AI-powered Network Lab Assistant for GNS3
+#
+# This file is part of GNS3-Copilot project.
+#
+# GNS3-Copilot is free software: you can redistribute it and/or modify it
+# under the terms of the GNU General Public License as published by the
+# Free Software Foundation, either version 3 of the License, or (at your
+# option) any later version.
+#
+# GNS3-Copilot is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+# or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+# for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with GNS3-Copilot. If not, see <https://www.gnu.org/licenses/>.
+#
+# Copyright (C) 2025 Yue Guobin (岳国宾)
+# Author: Yue Guobin (岳国宾)
+#
+# Project Home: https://github.com/yueguobin/gns3-copilot
+#
+"""
+
+This module provides a tool to execute display commands on multiple devices
+ in a GNS3 topology using Nornir.
+
+⚠️ WARNING: This module is shared with the MCP (Model Context Protocol) service.
+ExecuteMultipleDeviceCommands._run() is called by the MCP device_command_run handler.
+The jwt_token/url parameters were added for MCP compatibility.
+Modifications must be tested with BOTH gns3-copilot AND MCP.
+"""
+
+import json
+import logging
+import re
+from typing import Any
+
+from langchain.tools import BaseTool
+from langchain_core.callbacks import CallbackManagerForToolRun
+from netmiko.exceptions import ReadTimeout
+from nornir import InitNornir
+from nornir.core import Nornir
+from nornir.core.task import AggregatedResult
+from nornir.core.task import Result
+from nornir.core.task import Task
+from nornir_netmiko.tasks import netmiko_multiline
+
+from gns3server.agent.gns3_copilot.gns3_client import get_gns3_server_host
+from gns3server.agent.gns3_copilot.utils import get_device_ports_from_topology
+from gns3server.agent.gns3_copilot.utils.command_filter import (
+    filter_forbidden_commands,
+)
+
+# Import custom Netmiko device types for GNS3 emulation
+# This registers gns3_huawei_telnet_ce and other custom device types
+# NOTE: Must be imported BEFORE any Nornir operations to ensure device types are registered
+from gns3server.agent.gns3_copilot.utils import custom_netmiko  # noqa: F401
+
+# Explicitly register custom device types to ensure they are available
+# This is a safety measure in case the auto-registration on import doesn't work
+try:
+    from gns3server.agent.gns3_copilot.utils.custom_netmiko import huawei_ce
+    from gns3server.agent.gns3_copilot.utils.custom_netmiko.ruijie_telnet import (
+        register_custom_device_type as register_ruijie_device_type,
+    )
+
+    # Re-register to ensure device types are available
+    huawei_ce.register_custom_device_type()
+    register_ruijie_device_type()
+
+    # CRITICAL: Update netmiko.ssh_dispatcher platforms lists
+    # The platforms variable is calculated at module import time in ssh_dispatcher
+    # We need to update it after registering custom device types.
+    # NOTE: netmiko.ssh_dispatcher is aliased to ConnectHandler function,
+    # so we use importlib to get the actual module
+    import importlib
+
+    sd = importlib.import_module("netmiko.ssh_dispatcher")
+
+    # Recalculate platforms lists to include custom device types
+    sd.platforms = list(sd.CLASS_MAPPER.keys())
+    sd.platforms.sort()
+
+    sd.platforms_base = list(sd.CLASS_MAPPER_BASE.keys())
+    sd.platforms_base.sort()
+
+    sd.telnet_platforms = [x for x in sd.platforms if "telnet" in x]
+
+    # Update platform strings used in error messages
+    sd.platforms_str = "\n" + "\n".join(sd.platforms_base)
+    sd.telnet_platforms_str = "\n" + "\n".join(sd.telnet_platforms)
+except Exception:
+    # Fail silently - the import-time registration should have worked
+    pass
+
+# config log
+logger = logging.getLogger(__name__)
+
+# Suppress nornir INFO logs in console (reduce verbosity)
+# The logging={"enabled": False} in InitNornir only disables plugin
+# internal logs, but nornir.core still logs task execution at INFO level.
+# Set to WARNING to suppress these.
+logging.getLogger("nornir.core").setLevel(logging.WARNING)
+logging.getLogger("nornir").setLevel(logging.WARNING)
+
+
+# Local Nornir configuration functions for network devices
+def _get_nornir_defaults() -> dict[str, Any]:
+    """Get Nornir default configuration."""
+    return {"data": {"location": "gns3"}}
+
+
+class ExecuteMultipleDeviceCommands(BaseTool):
+    """
+    A READ-ONLY diagnostic tool for viewing network device configurations.
+
+    **CRITICAL: DIAGNOSIS ONLY - NO CONFIGURATION PERMISSIONS**
+
+    This tool is exclusively designed for read-only operations to inspect and
+    diagnose network devices. It CANNOT and MUST NOT be used for configuration.
+
+    **Allowed Command Types:**
+    - Display commands: show, display (Cisco/Huawei)
+    - Debug commands: debug ip routing, debug ospf events
+    - Verification commands: ping, traceroute, telnet
+    - Status commands: show version, show running-config, show ip route
+
+    **Strictly Prohibited:**
+    - Configuration mode: configure terminal, config t
+    - Interface configuration: interface, ip address
+    - Protocol configuration: router ospf, router bgp
+    - Any command that modifies device state
+    """
+
+    name: str = "execute_multiple_device_commands"
+    description: str = """
+    **READ-ONLY DIAGNOSTIC TOOL** - View network device configurations.
+
+    Use this tool to inspect device information without making any changes.
+
+    **PERMITTED USE CASES:**
+    - View device status: show version, show running-config
+    - Check routing: show ip route, show ip ospf neighbor, show bgp summary
+    - Interface status: show ip interface brief, show interfaces
+    - Protocol diagnostics: show ospf database, show bgp routes, debug commands
+    - Connectivity testing: ping, traceroute
+
+    **STRICTLY FORBIDDEN:**
+    - NO configuration commands (configure terminal, interface, router, etc.)
+    - NO commands that modify device state
+    - NEVER use 'exit' command - this disconnects the session and breaks subsequent commands
+    - If you need to configure, provide guidance to the student instead
+
+    **Input Format:**
+        {
+            "project_id": "<PROJECT_UUID>",
+            "device_configs": [
+                {
+                    "device_name": "R-1",
+                    "commands": ["show version", "show ip interface brief"]
+                },
+                {
+                    "device_name": "R-2",
+                    "commands": ["show version", "show ip ospf neighbor"]
+                }
+            ]
+        }
+
+    **Returns:** List of device outputs for diagnostic analysis.
+    """
+
+    def _run(
+        self,
+        tool_input: str | bytes | list[Any] | dict[str, Any],
+        run_manager: CallbackManagerForToolRun | None = None,
+        jwt_token: str | None = None,
+        url: str | None = None,
+        **kwargs: Any,
+    ) -> list[dict[str, Any]]:
+        """
+        Executes READ-ONLY diagnostic commands on multiple devices in GNS3.
+
+        This method only permits display/show commands and does not allow
+        configuration changes to network devices.
+
+        Args:
+            tool_input: JSON string with project_id and diagnostic commands.
+            jwt_token: JWT token for GNS3 API auth (MCP handlers).
+            url: GNS3 server URL (MCP handlers).
+
+        Returns:
+            List[Dict]: A list of dicts with device names and outputs.
+        """
+        # Log received input
+        logger.debug("Received input: %s", tool_input)
+
+        # Validate input
+        device_configs_list, project_id = self._validate_tool_input(tool_input)
+        if (
+            isinstance(device_configs_list, list)
+            and len(device_configs_list) > 0
+            and "error" in device_configs_list[0]
+        ):
+            return device_configs_list
+
+        # Filter forbidden commands and store blocked commands info
+        device_configs_list, blocked_commands_map = (
+            self._filter_forbidden_commands_from_device_configs(
+                device_configs_list
+            )
+        )
+
+        # Create a mapping of device names to their display commands
+        device_configs_map = self._configs_map(device_configs_list)
+
+        # Prepare device hosts data
+        try:
+            hosts_data = self._prepare_device_hosts_data(
+                device_configs_list, project_id, jwt_token=jwt_token, url=url
+            )
+        except ValueError as e:
+            logger.error("Failed to prepare device hosts data: %s", e)
+            return [{"error": str(e)}]
+
+        # Check if any devices have errors (e.g., missing device_type tag)
+        error_devices = {
+            name: data
+            for name, data in hosts_data.items()
+            if "error" in data
+        }
+        if error_devices:
+            logger.error(
+                "Devices with configuration errors: %s",
+                list(error_devices.keys())
+            )
+            return [
+                {
+                    "device_name": name,
+                    "status": "failed",
+                    "error": data["error"]
+                }
+                for name, data in error_devices.items()
+            ]
+
+        # Initialize Nornir
+        try:
+            dynamic_nr = self._initialize_nornir(hosts_data)
+        except ValueError as e:
+            logger.error("Failed to initialize Nornir: %s", e)
+            return [{"error": str(e)}]
+
+        results = []
+
+        # Execute all devices concurrently in a single run
+        try:
+            task_result = dynamic_nr.run(
+                task=self._run_all_device_configs_with_single_retry,
+                device_configs_map=device_configs_map,
+            )
+
+            # Process results for all devices
+            results = self._process_task_results(
+                device_configs_list,
+                hosts_data,
+                task_result,
+                blocked_commands_map,
+            )
+
+        except Exception as e:
+            # Overall execution failed
+            logger.error("Error executing display on all devices: %s", e)
+            return [{"error": f"Execution error: {str(e)}"}]
+
+        logger.debug(
+            "Multiple device display execution completed. Results: %s",
+            json.dumps(results, indent=2, ensure_ascii=False),
+        )
+
+        return results
+
+    def _run_all_device_configs_with_single_retry(
+        self, task: Task, device_configs_map: dict[str, list[str]]
+    ) -> Result:
+        """Execute READ-ONLY diagnostic commands with single retry."""
+        device_name = task.host.name
+        diagnostic_commands = device_configs_map.get(device_name, [])
+
+        if not diagnostic_commands:
+            return Result(
+                host=task.host, result="No diagnostic commands to execute"
+            )
+
+        try:
+            _result = task.run(
+                task=netmiko_multiline,
+                commands=diagnostic_commands,
+                enable=True,
+                read_timeout=60,
+            )
+            return Result(host=task.host, result=_result.result)
+
+        except ReadTimeout as e:
+            # Log ReadTimeout exception with full details
+            logger.error(
+                "ReadTimeout occurred for device %s: %s",
+                device_name,
+                str(e),
+            )
+            return Result(
+                host=task.host,
+                result=f"diagnostic command failed (ReadTimeout): {str(e)}",
+                failed=True,
+            )
+
+        except Exception as e:
+            # Handle Cisco IOSv L2 where '#' prompt char may be delayed,
+            # causing Netmiko failures. Implements retry logic.
+            if "netmiko_multiline (failed)" in str(e):
+                _result = task.run(
+                    task=netmiko_multiline,
+                    commands=diagnostic_commands,
+                    enable=True,
+                    read_timeout=60,
+                )
+                return Result(host=task.host, result=_result.result)
+
+            # Log any other exceptions with full details
+            logger.error(
+                "diagnostic command failed for device %s: %s (Exception: %s)",
+                device_name,
+                str(e),
+                type(e).__name__,
+            )
+            return Result(
+                host=task.host,
+                result=f"diagnostic command failed (Unhandled): {str(e)}",
+                failed=True,
+            )
+
+    def _validate_tool_input(
+        self, tool_input: str | bytes | list[Any] | dict[str, Any]
+    ) -> tuple[list[dict[str, Any]], str | None]:
+        """
+        Validate diagnostic command input for read-only device inspection.
+
+        Handles both new and legacy input formats. Supports new format with
+        project_id and device_configs, as well as legacy array format.
+
+        Args:
+            tool_input: Input from LangChain/LangGraph tool call.
+
+        Returns:
+            Tuple of (device_configs_list, project_id) or (error_list, None)
+        """
+
+        parsed_input = None
+
+        # Compatibility Check and Parsing ---
+        # Check if the input is a string (or bytes) which needs to be parsed.
+        if isinstance(tool_input, (str, bytes, bytearray)):
+            # Handle models (like DeepSeek) that return a raw JSON string.
+            try:
+                parsed_input = json.loads(tool_input)
+                logger.info("Successfully parsed tool input from JSON string.")
+            except json.JSONDecodeError as e:
+                logger.error(
+                    "Invalid JSON string received as tool input: %s", e
+                )
+                return (
+                    [{"error": f"Invalid JSON string input from model: {e}"}],
+                    None,
+                )
+        else:
+            # Handle standard models (like GPT/OpenAI) where the framework
+            # has already parsed the JSON into a Python object (dict or list).
+            parsed_input = tool_input
+            logger.info(
+                "Using tool input directly as type: %s",
+                type(parsed_input).__name__,
+            )
+
+        # Handle new format: {"project_id": "...", "device_configs": [...]}
+        if isinstance(parsed_input, dict):
+            project_id = parsed_input.get("project_id")
+            device_configs = parsed_input.get("device_configs")
+
+            # Validate project_id
+            if not project_id:
+                error_msg = "Missing required 'project_id' field in input"
+                logger.error(error_msg)
+                return ([{"error": error_msg}], None)
+
+            if not self._validate_project_id(project_id):
+                error_msg = f"Invalid project_id: {project_id}. Expected UUID."
+                logger.error(error_msg)
+                return ([{"error": error_msg}], None)
+
+            # Validate device_configs
+            if not isinstance(device_configs, list):
+                error_msg = "'device_configs' must be an array"
+                logger.error(error_msg)
+                return ([{"error": error_msg}], None)
+
+            if not device_configs:
+                logger.warning("Device configs list is empty.")
+                return [], project_id
+
+            return device_configs, project_id
+
+        # Handle legacy format: [...]
+        elif isinstance(parsed_input, list):
+            logger.warning(
+                "Legacy input format without project_id. Use new format."
+            )
+            return parsed_input, None
+
+        else:
+            error_msg = (
+                "Tool input must be JSON with project_id and device_configs, "
+                f"or legacy JSON array, got {type(parsed_input).__name__}"
+            )
+            logger.error(error_msg)
+            return ([{"error": error_msg}], None)
+
+    def _validate_project_id(self, project_id: str) -> bool:
+        """
+        Validate project_id format (UUID).
+
+        Args:
+            project_id: The project ID to validate
+
+        Returns:
+            True if valid UUID format, False otherwise
+        """
+        uuid_pattern = (
+            r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
+        )
+        return bool(re.match(uuid_pattern, project_id, re.IGNORECASE))
+
+    def _filter_forbidden_commands_from_device_configs(
+        self, device_configs_list: list[dict[str, Any]]
+    ) -> tuple[list[dict[str, Any]], dict[str, dict[str, str]]]:
+        """
+        Filter out forbidden commands from device configurations.
+
+        Args:
+            device_configs_list: List of device configurations with commands.
+
+        Returns:
+            Tuple of (filtered_configs, blocked_map):
+            - filtered_configs: Device configs with forbidden removed.
+            - blocked_map: Dict mapping device names to blocked commands.
+        """
+        filtered_list = []
+        blocked_commands_map: dict[str, dict[str, str]] = {}
+
+        for device_config in device_configs_list:
+            device_name = device_config["device_name"]
+            commands = device_config["commands"]
+
+            # Filter commands
+            allowed_commands, blocked_info = filter_forbidden_commands(
+                commands
+            )
+
+            # Update device config with allowed commands only
+            filtered_config = device_config.copy()
+            filtered_config["commands"] = allowed_commands
+            filtered_list.append(filtered_config)
+
+            # Store blocked commands info if any
+            if blocked_info:
+                blocked_commands_map[device_name] = blocked_info
+                logger.info(
+                    "Device %s: %d command(s) blocked: %s",
+                    device_name,
+                    len(blocked_info),
+                    list(blocked_info.keys()),
+                )
+
+        return filtered_list, blocked_commands_map
+
+    def _configs_map(
+        self, device_config_list: list[dict[str, Any]]
+    ) -> dict[str, list[str]]:
+        """Create a mapping of device names to their diagnostic commands."""
+        device_diagnostic_map = {}
+        for device_config in device_config_list:
+            device_name = device_config["device_name"]
+            diagnostic_commands = device_config["commands"]
+            device_diagnostic_map[device_name] = diagnostic_commands
+
+        return device_diagnostic_map
+
+    def _prepare_device_hosts_data(
+        self,
+        device_config_list: list[dict[str, Any]],
+        project_id: str | None = None,
+        jwt_token: str | None = None,
+        url: str | None = None,
+    ) -> dict[str, dict[str, Any]]:
+        """Prepare device hosts data from topology information."""
+        # Extract device names list
+        device_names = [
+            device_config["device_name"]
+            for device_config in device_config_list
+        ]
+
+        # Get device port information with project_id
+        hosts_data = get_device_ports_from_topology(
+            device_names, project_id, jwt_token=jwt_token, url=url
+        )
+
+        if not hosts_data:
+            error_msg = (
+                f"Failed to get device info from topology. "
+                f"Project: {project_id}, Devices: {device_names}"
+            )
+            raise ValueError(error_msg)
+
+        # Check for missing devices
+        missing_devices = set(device_names) - set(hosts_data.keys())
+        if missing_devices:
+            logger.warning(
+                "Some devices not found in topology (Project ID: %s): %s",
+                project_id or "default",
+                missing_devices,
+            )
+
+        return hosts_data
+
+    def _initialize_nornir(
+        self, hosts_data: dict[str, dict[str, Any]]
+    ) -> Nornir:
+        """
+        Initialize Nornir with the provided hosts data.
+
+        Each host now has its own connection_options (device_type), so we only
+        need a single generic group for shared configuration (hostname, timeout, etc.).
+        This is the Nornir best practice for multi-vendor environments.
+        """
+        try:
+            defaults = _get_nornir_defaults()
+            gns3_host = get_gns3_server_host()
+
+            # Create a single generic group for shared configuration
+            # Individual device types are handled at host level via connection_options
+            groups_data = {
+                "network_devices": {
+                    "hostname": gns3_host,
+                    "timeout": 120,
+                    "username": "",
+                    "password": "",
+                }
+            }
+
+            # Log device types being configured
+            device_types = [
+                host["connection_options"]["netmiko"]["extras"]["device_type"]
+                for host in hosts_data.values()
+            ]
+            logger.info(
+                "Initializing Nornir: host=%s, device_types=%s, hosts=%d",
+                gns3_host,
+                list(set(device_types)),
+                len(hosts_data),
+            )
+
+            return InitNornir(
+                inventory={
+                    "plugin": "DictInventory",
+                    "options": {
+                        "hosts": hosts_data,
+                        "groups": groups_data,
+                        "defaults": defaults,
+                    },
+                },
+                runner={
+                    "plugin": "threaded",
+                    "options": {"num_workers": 10},
+                },
+                logging={"enabled": False},
+            )
+        except Exception as e:
+            logger.error("Failed to initialize Nornir: %s", e)
+            raise ValueError(f"Failed to initialize Nornir: {e}") from e
+
+    def _process_task_results(
+        self,
+        device_configs_list: list[dict[str, Any]],
+        hosts_data: dict[str, dict[str, Any]],
+        task_result: AggregatedResult,
+        blocked_commands_map: dict[str, dict[str, str]],
+    ) -> list[dict[str, Any]]:
+        """Process the task results and format them for return."""
+        results = []
+
+        for device_config in device_configs_list:
+            device_name = device_config["device_name"]
+            diagnostic_commands = device_config["commands"]
+            blocked_commands_info = blocked_commands_map.get(device_name, {})
+
+            # Check if device is in topology
+            if device_name not in hosts_data:
+                device_result = {
+                    "device_name": device_name,
+                    "status": "failed",
+                    "error": (
+                        f"Device '{device_name}' not found in topology "
+                        "or missing console_port"
+                    ),
+                }
+                # Add blocked commands info if any
+                if blocked_commands_info:
+                    device_result["blocked_commands"] = list(
+                        blocked_commands_info.keys()
+                    )
+                    device_result["blocked_info"] = blocked_commands_info
+                results.append(device_result)
+                continue
+
+            # Check if device has execution results
+            if device_name not in task_result:
+                device_result = {
+                    "device_name": device_name,
+                    "status": "failed",
+                    "error": (
+                        f"Device '{device_name}' not found in task results"
+                    ),
+                }
+                # Add blocked commands info if any
+                if blocked_commands_info:
+                    device_result["blocked_commands"] = list(
+                        blocked_commands_info.keys()
+                    )
+                    device_result["blocked_info"] = blocked_commands_info
+                results.append(device_result)
+                continue
+
+            # Process execution results
+            multi_result = task_result[device_name]
+            device_result = {"device_name": device_name}
+
+            if multi_result[0].failed:
+                # Execution failed
+                device_result["status"] = "failed"
+                device_result["error"] = (
+                    f"Diagnostic command failed: {multi_result[0].result}"
+                )
+                device_result["output"] = multi_result[0].result
+            else:
+                # Execution successful
+                device_result["status"] = "success"
+                device_result["output"] = multi_result[0].result
+                device_result["diagnostic_commands"] = diagnostic_commands
+
+            # Add blocked commands info if any
+            if blocked_commands_info:
+                device_result["blocked_commands"] = list(
+                    blocked_commands_info.keys()
+                )
+                device_result["blocked_info"] = blocked_commands_info
+                # Update status if some commands were blocked but succeeded
+                if device_result["status"] == "success":
+                    device_result["status"] = "partial_success"
+
+            results.append(device_result)
+
+        return results
+
+
+if __name__ == "__main__":
+    # Example usage with new format
+    device_commands = json.dumps(
+        {
+            "project_id": "<PROJECT_UUID>",
+            "device_configs": [
+                {
+                    "device_name": "R-2",
+                    "commands": ["show version", "show ip interface brief"],
+                },
+                {
+                    "device_name": "R-1",
+                    "commands": ["show version", "show ip interface brief"],
+                },
+                {
+                    "device_name": "SW-1",
+                    "commands": ["show version", "show ip interface brief"],
+                },
+                {
+                    "device_name": "SW-2",
+                    "commands": ["show version", "show ip interface brief"],
+                },
+            ],
+        }
+    )
+
+    exe_cmd = ExecuteMultipleDeviceCommands()
+
+    failed_count = 0
+
+    for _i in range(0, 1):
+        exe_results = exe_cmd._run(tool_input=device_commands)
+        for result in exe_results:
+            for result in exe_results:
+                if result.get("status") == "failed":
+                    failed_count += 1
+
+    print(f"Failed Count: {failed_count}")
+
+    # print("Execution results:")
+    # print(json.dumps(result, indent=2, ensure_ascii=False))

gns3server/agent/gns3_copilot/tools_v2/gns3_create_link.py

@@ -0,0 +1,319 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# GNS3-Copilot - AI-powered Network Lab Assistant for GNS3
+#
+# This file is part of GNS3-Copilot project.
+#
+# GNS3-Copilot is free software: you can redistribute it and/or modify it
+# under the terms of the GNU General Public License as published by the
+# Free Software Foundation, either version 3 of the License, or (at your
+# option) any later version.
+#
+# GNS3-Copilot is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+# or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+# for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with GNS3-Copilot. If not, see <https://www.gnu.org/licenses/>.
+#
+# Copyright (C) 2025 Yue Guobin (岳国宾)
+# Author: Yue Guobin (岳国宾)
+#
+# Project Home: https://github.com/yueguobin/gns3-copilot
+#
+"""
+
+GNS3 link creation tool for connecting network nodes.
+
+Provides functionality to create links between nodes in GNS3 projects
+using the GNS3 API connector.
+"""
+
+import json
+import logging
+from pprint import pprint
+from typing import Any
+
+from langchain.tools import BaseTool
+from langchain_core.callbacks import CallbackManagerForToolRun
+
+from gns3server.agent.gns3_copilot.gns3_client import Link
+from gns3server.agent.gns3_copilot.gns3_client import get_gns3_connector
+
+# Configure logging
+logger = logging.getLogger(__name__)
+
+
+class GNS3LinkTool(BaseTool):
+    """
+    Tool for creating network links between GNS3 nodes.
+
+    Creates one or more links between specified nodes in a GNS3 project
+    by connecting their network ports. Supports batch link creation
+    with error handling for individual link failures.
+    """
+
+    name: str = "create_gns3_link"
+    description: str = """
+    Creates one or more links between nodes in a GNS3 project.
+
+    Input: A JSON string with:
+    - `project_id` (str): The UUID of the GNS3 project.
+    - `links` (list): A non-empty array of link definitions, each containing:
+    - `node_id1` (str): UUID of the first node.
+    - `port1` (str): Port name of the first node (e.g., 'Ethernet0/0').
+    - `node_id2` (str): UUID of the second node.
+    - `port2` (str): Port name of the second node (e.g., 'Ethernet0/0').
+    Note: Port names must match those from `gns3_topology_reader` tool.
+
+    Example Input:
+    {
+        "project_id": "uuid-of-project",
+        "links": [
+            {
+                "node_id1": "uuid-of-node1",
+                "port1": "Ethernet0/0",
+                "node_id2": "uuid-of-node2",
+                "port2": "Ethernet0/0"
+            }
+        ]
+    }
+    Output: A list of dicts, each containing:
+    - For successful links: link_id, node_id1, port1, node_id2, port2.
+    - For failed links: error(str) with error message.
+
+    Example Output:
+    [
+        {
+            "link_id": "uuid-of-link",
+            "node_id1": "uuid-of-node1",
+            "port1" : "Ethernet0/0",
+            "node_id2": "uuid-of-node2",
+            "port2": "Ethernet0/0"
+        },
+        {
+            "error": "Port not found in link 1"
+        },
+    ]
+    """
+
+    def _run(
+        self,
+        tool_input: str,
+        run_manager: CallbackManagerForToolRun | None = None,
+    ) -> list[dict[str, Any]]:
+        """
+        Creates one or multiple links between nodes in a GNS3 project.
+
+        Args:
+            tool_input: JSON string with project_id and links array.
+            run_manager: LangChain run manager (unused).
+
+        Returns:
+            list: A list with created link details or error messages.
+        """
+        # Log received input
+        logger.debug("Received input: %s", tool_input)
+
+        try:
+            # Parse input JSON
+            input_data = json.loads(tool_input)
+            project_id = input_data.get("project_id")
+            links_data = input_data.get("links", [])
+
+            # Validate input
+            if not project_id:
+                logger.error("Missing required field: project_id")
+                return [{"error": "Missing required field: project_id"}]
+
+            if not isinstance(links_data, list) or len(links_data) == 0:
+                logger.error("Invalid links data: must be a non-empty array")
+                return [
+                    {"error": "Invalid links data: must be a non-empty array"}
+                ]
+
+            # Initialize Gns3Connector using factory function
+            logger.info("Connecting to GNS3 server...")
+            gns3_server = get_gns3_connector()
+
+            if gns3_server is None:
+                logger.error("Failed to create GNS3 connector")
+                return [
+                    {
+                        "error": (
+                            "Failed to connect to GNS3 server. "
+                            "Please check your configuration."
+                        )
+                    }
+                ]
+
+            created_links = []
+
+            # Process each link definition
+            for i, link_data in enumerate(links_data):
+                try:
+                    logger.info("Creating link %d/%d", i + 1, len(links_data))
+
+                    # Extract link parameters
+                    node_id1 = link_data.get("node_id1")
+                    port1 = link_data.get("port1")
+                    node_id2 = link_data.get("node_id2")
+                    port2 = link_data.get("port2")
+
+                    # Validate link parameters
+                    if not all([node_id1, port1, node_id2, port2]):
+                        error_msg = (
+                            f"Missing required fields in link definition {i}"
+                        )
+                        logger.error(error_msg)
+                        created_links.append({"error": error_msg})
+                        continue
+
+                    # Get node details
+                    node1 = gns3_server.get_node(
+                        project_id=project_id, node_id=node_id1
+                    )
+                    node2 = gns3_server.get_node(
+                        project_id=project_id, node_id=node_id2
+                    )
+                    if not node1 or not node2:
+                        error_msg = f"Node not found in link {i}"
+                        logger.error(error_msg)
+                        created_links.append({"error": error_msg})
+                        continue
+
+                    # Find port information - match by name or short_name
+                    port1_info = next(
+                        (
+                            port
+                            for port in node1.get("ports", [])
+                            if port.get("name") == port1 or port.get("short_name") == port1
+                        ),
+                        None,
+                    )
+                    port2_info = next(
+                        (
+                            port
+                            for port in node2.get("ports", [])
+                            if port.get("name") == port2 or port.get("short_name") == port2
+                        ),
+                        None,
+                    )
+                    if not port1_info or not port2_info:
+                        error_msg = f"Port not found in link {i}"
+                        logger.error(error_msg)
+                        created_links.append({"error": error_msg})
+                        continue
+
+                    # Create the link
+                    link = Link(
+                        project_id=project_id,
+                        connector=gns3_server,
+                        nodes=[
+                            {
+                                "node_id": node_id1,
+                                "adapter_number": port1_info.get(
+                                    "adapter_number", 0
+                                ),
+                                "port_number": port1_info.get(
+                                    "port_number", 0
+                                ),
+                                "label": {"text": port1_info.get("short_name") or port1},
+                            },
+                            {
+                                "node_id": node_id2,
+                                "adapter_number": port2_info.get(
+                                    "adapter_number", 0
+                                ),
+                                "port_number": port2_info.get(
+                                    "port_number", 0
+                                ),
+                                "label": {"text": port2_info.get("short_name") or port2},
+                            },
+                        ],
+                    )
+                    link.create()
+                    link.get()
+
+                    # Collect link details
+                    link_info = {
+                        "link_id": link.link_id,
+                        "node_id1": node_id1,
+                        "port1": port1,
+                        "node_id2": node_id2,
+                        "port2": port2,
+                    }
+                    created_links.append(link_info)
+
+                except Exception as e:
+                    error_msg = f"Failed to create link {i}: {str(e)}"
+                    logger.error(error_msg)
+                    created_links.append({"error": error_msg})
+
+            # Log final results
+            success_count = len(
+                [link for link in created_links if "error" not in link]
+            )
+            logger.info(
+                "Link creation completed: %d successful, %d failed",
+                success_count,
+                len(links_data) - success_count,
+            )
+
+            return created_links
+
+        except json.JSONDecodeError as e:
+            logger.error("Invalid JSON input: %s", e)
+            return [{"error": f"Invalid JSON input: {e}"}]
+        except Exception as e:
+            logger.error("Failed to process link creation: %s", e)
+            return [{"error": f"Failed to process link creation: {str(e)}"}]
+
+
+if __name__ == "__main__":
+    # Test with single link
+    single_link_input = json.dumps(
+        {
+            "project_id": "your-project-uuid",
+            "links": [
+                {
+                    "node_id1": "your-node1-uuid",
+                    "port1": "Ethernet0/0",
+                    "node_id2": "your-node2-uuid",
+                    "port2": "Ethernet0/0",
+                }
+            ],
+        }
+    )
+
+    # Test with multiple links
+    multiple_links_input = json.dumps(
+        {
+            "project_id": "your-project-uuid",
+            "links": [
+                {
+                    "node_id1": "your-node1-uuid",
+                    "port1": "Ethernet0/0",
+                    "node_id2": "your-node2-uuid",
+                    "port2": "Ethernet0/0",
+                },
+                {
+                    "node_id1": "your-node1-uuid",
+                    "port1": "Ethernet0/1",
+                    "node_id2": "your-node3-uuid",
+                    "port2": "Ethernet0/0",
+                },
+            ],
+        }
+    )
+
+    tool = GNS3LinkTool()
+
+    print("=== Testing Single Link Creation ===")
+    result = tool._run(single_link_input)
+    pprint(result)
+
+    print("\n=== Testing Multiple Links Creation ===")
+    result = tool._run(multiple_links_input)
+    pprint(result)

gns3server/agent/gns3_copilot/tools_v2/gns3_create_node.py

@@ -0,0 +1,325 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# GNS3-Copilot - AI-powered Network Lab Assistant for GNS3
+#
+# This file is part of GNS3-Copilot project.
+#
+# GNS3-Copilot is free software: you can redistribute it and/or modify it
+# under the terms of the GNU General Public License as published by the
+# Free Software Foundation, either version 3 of the License, or (at your
+# option) any later version.
+#
+# GNS3-Copilot is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+# or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+# for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with GNS3-Copilot. If not, see <https://www.gnu.org/licenses/>.
+#
+# Copyright (C) 2025 Yue Guobin (岳国宾)
+# Author: Yue Guobin (岳国宾)
+#
+# Project Home: https://github.com/yueguobin/gns3-copilot
+#
+"""
+
+GNS3 node creation tool for network topology building.
+
+Provides functionality to create multiple nodes in GNS3 projects
+using specified templates and coordinates through the GNS3 API.
+"""
+
+import json
+import logging
+from pprint import pprint
+from typing import Any
+
+from langchain.tools import BaseTool
+from langchain_core.callbacks import CallbackManagerForToolRun
+
+from gns3server.agent.gns3_copilot.gns3_client import Node
+from gns3server.agent.gns3_copilot.gns3_client import get_gns3_connector
+
+# Configure logging
+logger = logging.getLogger(__name__)
+
+
+class GNS3CreateNodeTool(BaseTool):
+    """
+    A LangChain tool to create multiple nodes in a GNS3 project
+    using specified templates and coordinates.
+
+    **Input:**
+    A JSON object with project_id and array of nodes with template_id,
+    x, y coordinates, and optional name.
+
+    Example input:
+        {
+            "project_id": "uuid-of-project",
+            "nodes": [
+                {
+                    "template_id": "uuid-of-template",
+                    "x": 100,
+                    "y": -200,
+                    "name": "R1"
+                },
+                {
+                    "template_id": "uuid-of-template2",
+                    "x": -200,
+                    "y": 300,
+                    "name": "R2"
+                }
+            ]
+        }
+
+    **Output:**
+    A dictionary containing the creation results for all nodes.
+    Example output:
+        {
+            "project_id": "uuid-of-project",
+            "created_nodes": [
+                {
+                    "node_id": "uuid-of-node1",
+                    "name": "R1",
+                    "status": "success"
+                },
+                {
+                    "node_id": "uuid-of-node2",
+                    "name": "R2",
+                    "status": "success"
+                }
+            ],
+            "total_nodes": 2,
+            "successful_nodes": 2,
+            "failed_nodes": 0
+        }
+    If error occurs during validation, returns dict with error message.
+    """
+
+    name: str = "create_gns3_node"
+    description: str = """
+    Creates multiple nodes in a GNS3 project using templates and coordinates.
+    Input is a JSON object with project_id and array of nodes.
+    Each node requires: template_id, x, y. Optional: name (to set node name directly).
+    Example input:
+        {
+            "project_id": "uuid-of-project",
+            "nodes": [
+                {
+                    "template_id": "uuid-of-template",
+                    "x": 100,
+                    "y": -200,
+                    "name": "R1"
+                },
+                {
+                    "template_id": "uuid-of-template2",
+                    "x": -200,
+                    "y": 300,
+                    "name": "R2"
+                }
+            ]
+        }
+    IMPORTANT: Ensure distance between any two nodes is greater than 250 px.
+    This spacing is necessary to display interface numbers clearly for better
+    topology visualization.
+    Returns a dictionary with creation results for all nodes, including
+    success/failure status.
+    If the operation fails during input validation, returns a dictionary with
+    an error message.
+    """
+
+    def _run(
+        self,
+        tool_input: str,
+        run_manager: CallbackManagerForToolRun | None = None,
+        **kwargs: Any,
+    ) -> dict[str, Any]:
+        """
+        Creates nodes in a GNS3 project with templates and coordinates.
+
+        Args:
+            tool_input: A JSON string with project_id and an array of nodes.
+            run_manager: LangChain run manager (unused).
+
+        Returns:
+            dict: A dictionary with creation results for all nodes or an error
+                message.
+        """
+        # Log received input
+        logger.info("Received input: %s", tool_input)
+
+        try:
+            # Parse input JSON
+            input_data = json.loads(tool_input)
+            project_id = input_data.get("project_id")
+            nodes = input_data.get("nodes", [])
+
+            # Validate input
+            if not project_id:
+                logger.error("Invalid input: Missing project_id.")
+                return {"error": "Missing project_id."}
+
+            if not isinstance(nodes, list) or len(nodes) == 0:
+                logger.error("Invalid input: nodes must be a non-empty array.")
+                return {"error": "nodes must be a non-empty array."}
+
+            # Validate each node in the array
+            for i, node_data in enumerate(nodes):
+                if not isinstance(node_data, dict):
+                    logger.error(
+                        "Invalid input: Node %d must be a dictionary.", i + 1
+                    )
+                    return {"error": f"Node {i + 1} must be a dictionary."}
+
+                template_id = node_data.get("template_id")
+                x = node_data.get("x")
+                y = node_data.get("y")
+                name = node_data.get("name")
+
+                if not all(
+                    [
+                        template_id,
+                        isinstance(x, (int, float)),
+                        isinstance(y, (int, float)),
+                    ]
+                ):
+                    logger.error(
+                        "Invalid input: Node %d missing or invalid "
+                        "template_id, x, or y.",
+                        i + 1,
+                    )
+                    return {
+                        "error": f"Node {i + 1} missing or invalid "
+                        f"template_id, x, or y."
+                    }
+
+            # Initialize Gns3Connector using factory function
+            logger.info("Connecting to GNS3 server...")
+            gns3_server = get_gns3_connector()
+
+            if gns3_server is None:
+                logger.error("Failed to create GNS3 connector")
+                return {
+                    "error": "Failed to connect to GNS3 server. "
+                    "Please check your configuration."
+                }
+
+            # Create nodes
+            logger.info(
+                "Creating %d nodes in project %s...", len(nodes), project_id
+            )
+            results: list[dict[str, Any]] = []
+
+            for i, node_data in enumerate(nodes):
+                try:
+                    template_id = node_data.get("template_id")
+                    x = node_data.get("x")
+                    y = node_data.get("y")
+                    name = node_data.get("name")
+
+                    logger.info(
+                        "Creating node %d/%d with template %s at (%s, %s), name=%s...",
+                        i + 1,
+                        len(nodes),
+                        template_id,
+                        x,
+                        y,
+                        name,
+                    )
+
+                    # Create node
+                    node = Node(
+                        project_id=project_id,
+                        template_id=template_id,
+                        x=x,
+                        y=y,
+                        name=name,
+                        connector=gns3_server,
+                    )
+                    node.create()
+
+                    # Retrieve node details
+                    node.get()
+                    node_info = {
+                        "node_id": node.node_id,
+                        "name": node.name,
+                        "status": "success",
+                    }
+
+                    results.append(node_info)
+
+                except Exception as e:
+                    error_info = {
+                        "error": f"Node {i + 1} creation failed: {str(e)}",
+                        "status": "failed",
+                    }
+                    results.append(error_info)
+                    logger.error("Failed to create node %d: %s", i + 1, e)
+                    # Continue with next node even if one fails
+
+            # Calculate summary statistics
+            successful_nodes = len(
+                [r for r in results if r.get("status") == "success"]
+            )
+            failed_nodes = len(
+                [r for r in results if r.get("status") == "failed"]
+            )
+
+            # Prepare final result
+            final_result = {
+                "project_id": project_id,
+                "created_nodes": results,
+                "total_nodes": len(nodes),
+                "successful_nodes": successful_nodes,
+                "failed_nodes": failed_nodes,
+            }
+
+            # Log the final result
+            logger.info(
+                "Node creation completed: %d successful, %d failed, %d total.",
+                successful_nodes,
+                failed_nodes,
+                len(nodes),
+            )
+
+            # Return JSON-formatted result
+            return final_result
+
+        except json.JSONDecodeError as e:
+            logger.error("Invalid JSON input: %s", e)
+            return {"error": f"Invalid JSON input: {e}"}
+        except Exception as e:
+            logger.error("Failed to process node creation request: %s", e)
+            return {
+                "error": f"Failed to process node creation request: {str(e)}"
+            }
+
+
+if __name__ == "__main__":
+    # Test the tool locally with multiple nodes
+    test_input = json.dumps(
+        {
+            # TODO: Replace with actual project UUID
+            "project_id": "d7fc094c-685e-4db1-ac11-5e33a1b2e066",
+            "nodes": [
+                {
+                    # TODO: Replace with actual template UUID
+                    "template_id": "b923a635-b7cc-4cb5-9a86-9357e04c02f7",
+                    "x": 100,
+                    "y": -200,
+                    "name": "R1",
+                },
+                {
+                    # TODO: Replace with actual template UUID
+                    "template_id": "b923a635-b7cc-4cb5-9a86-9357e04c02f7",
+                    "x": 200,
+                    "y": -300,
+                    "name": "R2",
+                },
+            ],
+        }
+    )
+    tool = GNS3CreateNodeTool()
+    result = tool._run(test_input)
+    pprint(result)

gns3server/agent/gns3_copilot/tools_v2/gns3_get_node_temp.py

@@ -0,0 +1,183 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# GNS3-Copilot - AI-powered Network Lab Assistant for GNS3
+#
+# This file is part of GNS3-Copilot project.
+#
+# GNS3-Copilot is free software: you can redistribute it and/or modify it
+# under the terms of the GNU General Public License as published by the
+# Free Software Foundation, either version 3 of the License, or (at your
+# option) any later version.
+#
+# GNS3-Copilot is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+# or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+# for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with GNS3-Copilot. If not, see <https://www.gnu.org/licenses/>.
+#
+# Copyright (C) 2025 Yue Guobin (岳国宾)
+# Author: Yue Guobin (岳国宾)
+#
+# Project Home: https://github.com/yueguobin/gns3-copilot
+#
+"""
+
+GNS3 template retrieval tool for device discovery.
+
+Provides functionality to retrieve all available device templates
+from a GNS3 server, including template names, IDs, and types.
+Filters out built-in utility templates that are not useful for network labs.
+"""
+
+import json
+import logging
+from pprint import pprint
+from typing import Any
+
+from langchain.tools import BaseTool
+from langchain_core.callbacks import CallbackManagerForToolRun
+
+from gns3server.agent.gns3_copilot.gns3_client import get_gns3_connector
+
+# Configure logging
+logger = logging.getLogger(__name__)
+
+# Built-in templates to filter out (utility templates, not actual network devices)
+FILTERED_TEMPLATES = {
+    "atm_switch",          # ATM switch
+    "cloud",               # Cloud
+    "ethernet_hub",        # Ethernet hub
+    "ethernet_switch",     # Ethernet switch (built-in)
+    "frame_relay_switch",  # Frame Relay switch
+    "nat",                 # NAT device
+}
+
+
+def should_filter_template(template: dict[str, Any]) -> bool:
+    """
+    Determine whether a template should be filtered out.
+
+    Filter condition:
+    1. Template type is in the filter list (exact match)
+
+    Args:
+        template: Template dictionary
+
+    Returns:
+        True if template should be filtered, False if it should be kept
+    """
+    template_type = template.get("template_type", "")
+
+    # Check if template_type is in filter list
+    # This is the most reliable way to identify built-in utility templates
+    return template_type in FILTERED_TEMPLATES
+
+
+class GNS3TemplateTool(BaseTool):
+    """
+    LangChain tool to retrieve available device templates from GNS3 server.
+    Connects to GNS3 server and extracts name, template_id, and template_type.
+    Filters out built-in utility templates that are not useful for network labs.
+
+    **Input:**
+    No input required. Connects to GNS3 server at default URL.
+
+    **Output:**
+    Dict with list of dicts (name, template_id, template_type).
+    If error, returns dict with error message.
+
+    **Filtered Templates:**
+    The following built-in utility templates are excluded:
+    - ATM switch
+    - Cloud
+    - Ethernet hub
+    - Ethernet switch (built-in)
+    - Frame Relay switch
+    - NAT
+    """
+
+    name: str = "get_gns3_templates"
+    description: str = """
+    Retrieves available device templates from GNS3 server for network labs.
+    Returns dict with list of dicts (name, template_id, template_type).
+    Filters out built-in utility templates (ATM switch, Cloud, Ethernet hub,
+    Ethernet switch, Frame Relay switch, NAT) as they are not useful for
+    network device configuration.
+    No input required.
+    If connection fails, returns dict with error message.
+    """
+
+    def _run(
+        self,
+        tool_input: str = "",
+        run_manager: CallbackManagerForToolRun | None = None,
+    ) -> dict[str, Any]:
+        """
+        Connects to GNS3 server and retrieves available device templates.
+
+        Args:
+            tool_input: Optional input (not used).
+            run_manager: LangChain run manager (unused).
+
+        Returns:
+            dict: Dict with templates list or error message.
+        """
+        try:
+            # Initialize Gns3Connector using factory function
+            logger.info("Connecting to GNS3 server...")
+            gns3_server = get_gns3_connector()
+
+            if gns3_server is None:
+                logger.error("Failed to create GNS3 connector")
+                return {
+                    "error": (
+                        "Failed to connect to GNS3 server. "
+                        "Please check your configuration."
+                    )
+                }
+
+            # Retrieve all available templates
+            templates = gns3_server.get_templates()
+
+            # Filter out utility templates and extract relevant info
+            template_info = []
+            filtered_count = 0
+            for template in templates:
+                # Check if template should be filtered
+                if should_filter_template(template):
+                    filtered_count += 1
+                    logger.debug("Filtered out template: %s", template.get("name"))
+                    continue
+
+                # Extract name, template_id, and template_type
+                template_info.append({
+                    "name": template.get("name", "N/A"),
+                    "template_id": template.get("template_id", "N/A"),
+                    "template_type": template.get("template_type", "N/A"),
+                })
+
+            # Return JSON-formatted result with full logging
+            result = {"templates": template_info}
+            logger.info(
+                "Template retrieval completed. Total: %d, Filtered: %d, Remaining: %d",
+                len(templates),
+                filtered_count,
+                len(template_info),
+            )
+            logger.debug("Result: %s", json.dumps(result, indent=2, ensure_ascii=False))
+            return result
+
+        except Exception as e:
+            logger.error(
+                "Failed to connect to GNS3 server or retrieve templates: %s", e
+            )
+            return {"error": f"Failed to retrieve templates: {str(e)}"}
+
+
+if __name__ == "__main__":
+    # Test's tool locally
+    tool = GNS3TemplateTool()
+    result = tool._run("")
+    pprint(result)