Obsidian Desktop Integration
Relevant source files
The following files were used as context for generating this wiki page:
Overview
The Obsidian Desktop Integration serves as a central "execution hub" for the AI Network Operations Platform, allowing the AI to read and write project state directly within a local Obsidian vault. For a network engineer, this feature acts like a persistent digital notebook where the AI records its logic, tracks project status, and stores documentation like network inventories or runbooks.
The platform is designed to be a self-hosted AI assistant that helps network teams discover infrastructure, troubleshoot issues (like BGP flaps or OSPF adjacency problems), and manage DDI (DNS, DHCP, and IPAM). It supports a wide range of vendors including Cisco (IOS, NX-OS), Juniper, Arista, Palo Alto, Fortinet, and DDI providers like Infoblox and BlueCat. The key philosophy is "local-first," meaning all data stays on your infrastructure, and every change must be approved by a human before execution.
The platform uses "Agents," which are like specialized team members that handle different tasks:
- Discovery Agent: Scans the network and lists devices.
- Troubleshooting Agent: Diagnoses why a route is missing or a flow is blocked.
- DDI Agent: Manages DNS records and DHCP scopes.
- Documentation Agent: Generates diagrams and inventories.
Sources: tools/obsidian-mcp/scripts/migrate_hub.py, CLAUDE.md:1-50, README.md:1-20
Architecture
The platform is built as a set of interconnected services, often deployed as containers. Think of these as different functional units in a rack:
- frontend: The web console where you chat with the AI and view the network topology.
- api: The primary communication point that manages agent sessions and security.
- worker: The background engine that performs the "heavy lifting," such as running discovery scans, taking config backups, or analyzing packet captures.
- postgres: The main database (system of record) that stores device lists, user accounts, and AI reasoning traces.
- neo4j: A living topology map that tracks how every device, interface, subnet, and application connects to everything else.
- redis: A fast temporary storage used to manage the worker's task queue and caching.
- ollama: An optional service for running AI models locally, ensuring no data leaves your network.
To handle different hardware, the platform uses a vendor plugin system. This acts as a standardized connector; whether you are talking to a Cisco NX-OS switch or a BlueCat Address Manager, the plugin normalizes the vendor-specific output into a consistent format the AI can understand.
Sources: README.md:23-45, deploy/docker/docker-compose.yml:18-150
Obsidian Integration Architecture
The Obsidian integration specifically uses the Model Context Protocol (MCP) to bridge the AI assistant with your local files. It allows the AI to perform actions like read_note, write_note, and append_note within a designated vault.
This diagram shows how a user's request moves through the platform to eventually update project documentation in the Obsidian vault.
Sources: tools/obsidian-mcp/src/obsidian_mcp/server.py:1-50, tools/obsidian-mcp/scripts/migrate_hub.py:100-150
Component Overview and Data Flow
The platform provides two main deployment options. Docker Compose is ideal for a lab or a small team on a single server. Kubernetes/Helm is used for production environments requiring high availability across multiple nodes.
Deployment Options Comparison
| Feature | Docker Compose | Kubernetes (Helm) |
|---|---|---|
| Use Case | Lab, Development, Small Teams | Production, Enterprise Operations |
| Complexity | Low (Single command bring-up) | High (Requires K8s cluster) |
| Resilience | Single server (not HA) | Multi-node (Highly Available) |
| Scalability | Manual | Automatic (HPA/KEDA) |
Sources: deploy/docker/README.md:1-15, deploy/kubernetes/netops/README.md:1-25
Change Approval Workflow
A critical feature is the change approval workflow. The AI never modifies a device directly without human intervention. The process follows a strict lifecycle:
- Draft: An agent (like the DDI Agent) creates a proposed change.
- Pending Approval: The change appears in the console for a human to review.
- Approved: A second human authorizes the change.
- Executing: The Automation Agent applies the change (taking a pre-change backup first).
- Completed/Rolled Back: The platform verifies the change or reverts it if a failure is detected.
This sequence diagram illustrates the steps from an engineer's request to the final execution on a network device, with documentation updates in the Obsidian hub.
Sources: README.md:1-10, tools/obsidian-mcp/scripts/migrate_hub.py:100-115, backend/app/agents/ddi/agent.py:40-60
Network Topology and Knowledge Graph
The platform maintains a "living topology map" in Neo4j. This graph tracks relationships between various network objects, allowing the AI to understand dependencies (e.g., which application breaks if this VLAN is shut down).
Topology Data Model
| Entity | Description | Relationships |
|---|---|---|
| Device | Physical or virtual hardware (Cisco, Juniper, etc.) | CONNECTED_TO (Interface), MEMBER_OF (Site) |
| Interface | Physical port or logical sub-interface | IN_SUBNET (Subnet), HAS_VLAN (VLAN) |
| Subnet | IP network range (e.g., 10.0.1.0/24) | CONTAINS (IP Address) |
| VLAN | Layer 2 broadcast domain | TRUNKED_ON (Interface) |
| DNS Zone | Domain grouping (e.g., corp.internal) | HAS_RECORD (DNS Record) |
| Application | High-level service | DEPENDS_ON (DNS Record, IP Address) |
The diagram represents "what the platform knows about your network" by showing how devices connect up to applications and DNS.
Sources: CLAUDE.md:65-75, backend/app/agents/documentation/agent.py:15-30
Implementation: The Execution Hub
The Obsidian integration transforms the vault into an "Execution Hub." Three primary files are maintained by the AI:
- Status.md: Tracks the current milestone and next steps.
- Iteration Log.md: A historical record of every action the AI has taken.
- Decisions.md: A log of architectural and operational choices made during the build.
Vault Structure Snippet
# Status
Execution hub for the AI Network Operations Platform build.
## Current Milestone
- [x] M0: Scaffold complete
- [ ] M1: Inventory and Credential Vault
## Next Steps
- Finish obsidian-mcp tool
- Resume build: M1 — inventory models, credential vault
Sources: tools/obsidian-mcp/scripts/migrate_hub.py:102-140
Summary
The Obsidian Desktop Integration provides a persistent, human-readable record of the AI's operations. By using the Model Context Protocol, the platform ensures that its reasoning, status, and network documentation are always available to the engineering team in a familiar format. This reinforces the "audit everything" and "human-in-the-loop" design principles essential for secure network operations.