Getting Started Guide
Relevant source files
The following files were used as context for generating this wiki page:
Nexus Orchestrator is a local-first, autonomous infrastructure daemon designed to serve as the "nervous system" for AI agent development. It bridges the gap between AI agents and their operating environments by managing connectivity, state, and security through a unified orchestration layer.
The system is built to handle the lifecycle of agent-infrastructure interactions, including environment management, SSH connectivity, and persistent context tracking. By synthesizing the Model Context Protocol (MCP) with workflow management and Zero Trust security, Nexus provides a robust framework for non-human identities to operate safely and efficiently.
Sources: README.md:1-10
System Architecture
The Nexus Orchestrator is structured into four core pillars that handle specific aspects of the autonomous infrastructure.
Core Pillars of Nexus
| Pillar | Focus Area | Technologies |
|---|---|---|
| Connectivity Layer | Agent-Infrastructure communication | MCP (Model Context Protocol) |
| Orchestration Layer | Workflow and environment management | LangGraph |
| Context Layer | Persistent state and registry | AGENTS.md, Context Files |
| Governance Layer | Security and identity | OPA, Zero Trust |
Sources: README.md:12-16
Data and Logic Flow
The following diagram illustrates how an AI agent interacts with the Nexus Orchestrator to access infrastructure resources while passing through governance checks.
The flow shows the progression from an agent request through the security gateway to the execution and state management layers.
Sources: README.md:3-16
Agent Registration and Context
Nexus maintains a persistent record of all AI agents that interact with the system. This registry is crucial for managing "non-human identities" and tracking their trust levels within the ecosystem.
The AGENTS.md Registry
The context/AGENTS.md file serves as the primary ledger for known agents. It tracks the following attributes:
- Agent ID: Unique identifier for the AI entity.
- Description: The role or purpose of the agent.
- Trust Level: The security clearance or reliability rating assigned to the agent.
Sources: context/AGENTS.md:1-7
Governance and Security
Security in Nexus is predicated on Zero Trust principles and Open Policy Agent (OPA) governance. This ensures that every action taken by an AI agent is validated against policy before execution.
Non-Human Identity (NHI) Management
Nexus treats agents as first-class identities. The system manages these identities by:
- Assigning specific trust levels via the context layer.
- Enforcing policies through the Governance Layer.
- Maintaining persistent state to track behavior across sessions.
Sources: README.md:16, context/AGENTS.md:3-7
Key Components
The functionality of Nexus is distributed across several key modules that work in tandem:
- Autonomous Infrastructure Daemon: A background process that manages environments and SSH connectivity without requiring constant human intervention.
- LangGraph-powered Workflows: Manages complex orchestration logic and state transitions during infrastructure tasks.
- MCP Protocol: Provides a standardized interface for agents to communicate with the underlying infrastructure.
Sources: README.md:3-13
Conclusion
Nexus Orchestrator provides the necessary infrastructure for scalable and secure AI agent operations. By combining autonomous environment management with strict governance and persistent context, it enables agents to perform complex tasks while maintaining a high degree of security and auditability.