A local-first communication and orchestration bridge for connecting multiple AI agents through a shared coordination layer.
Ths README gonna be huge sorry for that..
NavOS - Universal AI Bridge is an experimental multi-agent orchestration system designed to allow different AI agents, models, IDE assistants, and AI clients to communicate through a centralized local bridge.
The project was created around a simple idea:
Let different AI agents work together on the same project without requiring the user to manually copy information between them.
NavOS provides the coordination layer while the connected AI agents remain responsible for their own reasoning, tools, files, terminals, IDEs, and development environments.
Experimental / Research Project
NavOS is currently a research and experimentation project.
The current implementation demonstrates:
- AI agent registration
- Persistent logical agent identities
- Native and web agent classification
- Project registration
- Commander / Worker roles
- Multi-phase project workflows
- Agent-to-agent message routing
- Phase reports
- Project state tracking
- Persistent SQLite state
- MCP-based communication
- Autonomous worker wake-up experiments
- Stateless and stateful MCP session handling
- Agent lifecycle management
- Role-based project access
- Local-first operation
- Secure MCP tunneling for remote AI clients
However, the project is not currently presented as a finished production-ready agent-to-agent protocol.
One of the major findings during development was that MCP itself is primarily designed around AI clients communicating with MCP servers and tools. True general-purpose agent-to-agent interoperability is a broader problem.
Because of that, the future architecture of NavOS may evolve toward an MCP + A2A-style hybrid or another dedicated agent communication mechanism.
Development is currently paused while the correct long-term multi-agent communication architecture is being evaluated.
- What is NavOS?
- The Problem
- The Idea
- Architecture
- Core Concepts
- Agent Types
- Agent Identity
- Commander and Worker
- Project System
- Phase-Based Workflow
- Autonomous Workflow
- MCP Communication
- Why MCP Was Used
- Important MCP Limitation
- Session and Identity Design
- Database
- Dashboard
- Security
- Privacy
- Testing
- Project Structure
- Requirements
- Installation
- Configuration
- Running NavOS
- Connecting an Agent
- Registering a Project
- Commander / Worker Workflow
- Remote Access
- Development
- Testing Commands
- Design Decisions
- What NavOS Does Not Do
- Known Limitations
- Future Direction
- Roadmap
- Contributing
- License
- Credits
NavOS is a local-first AI coordination bridge.
It is designed to sit between multiple AI agents and provide a shared place where they can:
- identify themselves
- discover other connected agents
- register projects
- determine their assigned role
- create project phases
- execute phases
- report results
- communicate with other agents
- track project progress
- coordinate work without constantly requiring the human to copy/paste information
The important design principle is:
NavOS coordinates the agents. It does not replace their native working environments.
For example:
- Gemini can continue working inside Antigravity IDE.
- Codex can continue working inside its own environment.
- ChatGPT can act as a web-based Commander.
- Each native agent can continue using its own filesystem, terminal, editor, compiler, Git tools, and other capabilities.
NavOS provides the shared coordination layer between them.
Modern AI development tools are becoming increasingly capable, but different AI systems often operate independently.
A typical workflow might look like this:
Human
│
├── Ask ChatGPT for a plan
│
├── Copy plan
│
├── Paste into Gemini
│
├── Gemini modifies files
│
├── Copy Gemini's result
│
├── Paste into ChatGPT
│
├── ChatGPT reviews
│
└── Repeat
The human becomes the communication bus.
This creates several problems:
- repetitive copy/paste
- loss of context
- duplicated explanations
- difficulty coordinating multiple agents
- no shared project state
- no persistent agent identity
- no structured task progression
- difficult autonomous workflows
NavOS experiments with another model:
┌─────────────────┐
│ Human │
└────────┬────────┘
│
▼
┌─────────────────┐
│ NavOS │
│ AI Bridge │
└───────┬─────────┘
│
┌──────────────┼──────────────┐
│ │ │
▼ ▼ ▼
┌─────────┐ ┌──────────┐ ┌─────────┐
│ ChatGPT │ │ Gemini │ │ Codex │
│ Web │ │Antigravity│ │ Desktop │
└─────────┘ └──────────┘ └─────────┘
The goal is to allow the agents to coordinate through NavOS rather than forcing the human to manually relay every message.
NavOS separates the system into three major layers.
The actual AI systems perform reasoning and work.
Examples:
- ChatGPT
- Gemini
- Codex
- IDE-integrated AI agents
- Other MCP-compatible AI clients
NavOS provides:
- agent identity
- agent registration
- project membership
- role assignment
- phase management
- communication
- state tracking
- coordination
Native agents retain control over their own environment.
For example:
Antigravity / Gemini
│
├── Files
├── Terminal
├── Git
├── IDE
├── Compiler
└── Tests
NavOS does not need to directly edit those files.
This separation is intentional.
The experimental architecture looks roughly like this:
┌──────────────────────┐
│ Human │
│ │
│ Assigns Commander │
│ Assigns Worker │
└──────────┬───────────┘
│
▼
┌────────────────────────┐
│ NavOS │
│ │
│ Universal AI Bridge │
│ │
│ Agent Identity │
│ Project State │
│ Phase State │
│ Messages │
│ Reports │
│ Role Enforcement │
└───────────┬────────────┘
│
┌────────────────────┼────────────────────┐
│ │ │
▼ ▼ ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ ChatGPT │ │ Gemini │ │ Codex │
│ Web │ │ Antigravity │ │ Desktop │
│ │ │ IDE │ │ │
└─────────────┘ └─────────────┘ └─────────────┘
│ │ │
│ │ │
▼ ▼ ▼
Commander Worker Agent
│
▼
Native Project Files
The exact communication architecture is still under evaluation.
NavOS is built around several concepts.
An AI client connected to NavOS.
Each logical agent has a persistent identity.
A project registered inside NavOS.
A project represents a workspace that agents can coordinate on.
A project is divided into phases.
For example:
Phase 1
Inventory the project
↓
Phase 2
Create README contract
↓
Phase 3
Implement validation
↓
Phase 4
Create tests
↓
Phase 5
Final verification
The AI responsible for coordinating the project.
The Commander decides:
- what should happen
- how the project should be divided
- what phase should run next
- what information the Worker needs
- when a phase is complete
The AI responsible for performing an assigned phase.
The Worker:
- receives the current phase
- works inside its native environment
- modifies files when required
- runs tests
- reports results
- waits for the next phase
NavOS distinguishes between two major types of agents.
A native agent has access to an actual local project directory.
Example:
Gemini
Antigravity IDE
C:\Projects\MyProject
The directory identifies the environment in which the agent is operating.
Native agents can participate as Workers.
A web agent does not have direct filesystem access to the local project.
Example:
ChatGPT Web
directory = nil
A web agent can act as a Commander or coordinator, but cannot directly become a Worker in the local native-workspace model.
One of the most important parts of NavOS is persistent agent identity.
A temporary MCP transport connection is not treated as the permanent identity of an agent.
Instead, NavOS separates:
Transport Session
≠
Logical Agent Identity
This distinction became necessary because some AI clients maintain persistent MCP connections while others may create new HTTP requests or sessions.
Without persistent identity, one logical AI could appear as:
agent-1
agent-2
agent-3
agent-4
agent-5
...
even though it is actually the same AI client.
NavOS therefore treats the logical agent identity as persistent state.
An agent explicitly connects to NavOS through the connection mechanism.
The agent provides three important pieces of identity information:
Example:
GPT-5.6 Luna
or:
Gemini
Example:
ChatGPT Web PC
Antigravity IDE
Codex Desktop
Native agents provide their actual working directory.
Example:
C:\Projects\MyProject
Web agents use:
nil
This distinction allows NavOS to understand the difference between a native workspace agent and a web-based agent.
Role assignment is intentionally controlled by the human.
Agents do not automatically assign themselves as Commander or Worker.
The intended workflow is:
Human
│
├── Connect Agent A
├── Connect Agent B
│
▼
NavOS Dashboard
│
├── Select Commander
└── Select Worker
This prevents an agent from deciding its own authority within a project.
Projects are registered with NavOS.
A project can contain:
- project metadata
- registered agents
- Commander
- Worker
- phases
- reports
- communication
- current state
The actual project files remain in the native agent's workspace.
NavOS stores coordination information rather than becoming the project's filesystem.
The project workflow is based on phases.
A Commander can create phases such as:
Phase 1
Project inventory
Phase 2
Documentation
Phase 3
Implementation
Phase 4
Testing
Phase 5
Final verification
Each phase has a lifecycle.
Conceptually:
Pending
│
▼
Active
│
▼
Completed
The Worker works on the active phase and submits a report when finished.
One of the most important experiments performed with NavOS was an autonomous Commander → Worker workflow.
The intended workflow is:
Human
│
│ Initial instruction
▼
Commander
│
│ Creates phases
▼
NavOS
│
│ Phase 1
▼
Worker
│
│ Performs work
│
│ Submits report
▼
NavOS
│
│ Advances phase
▼
Worker
│
│ Receives next phase
│
│ Performs work
▼
...
The human does not need to manually relay each phase.
A simplified project might look like this:
Complete this project with the Worker.
The Commander examines the project and creates:
Phase 1:
Inventory existing files
Phase 2:
Document configuration requirements
Phase 3:
Implement configuration validation
Phase 4:
Create automated tests
Phase 5:
Perform final verification
The Worker then executes the phases.
Example:
Commander
│
│ Phase 1
▼
Worker
│
│ Inventory complete
▼
Report
│
▼
NavOS
│
│ Phase 2
▼
Worker
│
│ Documentation complete
▼
Report
│
▼
NavOS
│
│ Phase 3
▼
...
Different AI clients behave differently when they are waiting.
During development, NavOS experiments investigated how native AI environments react to background tasks, scheduled execution, MCP notifications, and heartbeat-style execution.
A key discovery was:
An MCP notification alone does not necessarily cause an idle AI model to start a new reasoning turn.
However, some environments can react to completion of a background task.
For example, Antigravity was tested with a background process that waited and then completed.
The completion caused the AI environment to resume.
Codex was found to behave differently, with heartbeat/scheduled execution providing a mechanism for starting a new reasoning turn.
ChatGPT Web was also tested with scheduled execution.
These experiments demonstrated that autonomous multi-agent workflows depend not only on the server protocol but also on the behavior of each AI client.
NavOS currently exposes its coordination functionality through the Model Context Protocol (MCP).
MCP allows compatible AI clients to discover and call tools exposed by NavOS.
Conceptually:
AI Client
│
│ MCP
▼
NavOS MCP Server
│
├── Agent management
├── Project management
├── Phase management
├── Messaging
└── Coordination
MCP was useful because modern AI clients increasingly support MCP servers.
This makes it possible to expose NavOS functionality without building a completely custom integration for every AI client.
Instead of:
ChatGPT integration
Gemini integration
Codex integration
IDE integration
...
the experiment can expose a common MCP interface.
One of the most important findings from the project is that:
MCP is not inherently a complete agent-to-agent communication protocol.
MCP primarily provides a mechanism for an AI client to communicate with a server and use tools/resources exposed by that server.
The desired NavOS architecture is more ambitious:
Agent A
│
│
▼
Agent B
with autonomous agent interoperability.
That raises additional questions around:
- agent identity
- agent discovery
- task delegation
- message delivery
- agent capabilities
- agent lifecycle
- asynchronous communication
- task state
- authentication
- authorization
- agent-to-agent responses
- wake-up behavior
These are broader than simply exposing tools through MCP.
This discovery is one of the reasons the project is currently paused while the long-term architecture is evaluated.
NavOS had to solve a subtle problem:
MCP transport session
and:
logical AI agent
are not necessarily the same thing.
A persistent SSE client may maintain one transport session for a long time.
A stateless HTTP client may create a new transport session for every request.
Therefore:
Transport Session
must be treated as temporary.
While:
Logical Agent
must persist.
The database therefore stores logical agent information independently from temporary transport state.
Stateless clients introduced an additional challenge.
A client may successfully connect once and then make a later request using a new HTTP transport.
NavOS therefore needs to re-establish the logical agent context for subsequent requests.
The architecture was designed around persistent agent_id information rather than assuming that a transport session will always survive.
This was extensively tested during development.
Native agents cannot simply be identified by:
model
+
location
+
directory
and automatically merged.
Two independent AI agents may intentionally operate in the same directory.
For example:
Gemini
Antigravity IDE
C:\Projects\Test
and:
Another Agent
Another Client
C:\Projects\Test
may both legitimately exist.
Therefore, native agent identities remain separate logical entities.
Web agents have no local project directory.
They therefore use:
directory = nil
For the experimental architecture, web agent identity can use model/client-location information for deterministic recovery.
This is intentionally different from native agents because multiple native agents may share a filesystem directory.
NavOS uses SQLite for persistent coordination state.
The database stores information such as:
- agents
- projects
- project membership
- roles
- phases
- reports
- messages
- lifecycle information
The database is a backend implementation detail.
It is not intended to become the user's primary interaction interface.
The dashboard communicates with NavOS rather than requiring direct database interaction.
NavOS includes a web dashboard for human oversight and assignment.
The dashboard is intentionally minimal and focused on orchestration.
The design includes:
Displays:
- NavOS status
- uptime
- connected agent count
- project count
Shows agents that have explicitly connected.
Example:
Connected Agents
GPT-5.6 Luna
ChatGPT Web PC
WEB
Gemini
Antigravity IDE
NATIVE
Codex
Codex Desktop
NATIVE
The human can assign:
Commander → Worker
The dashboard provides explicit Commander and Worker selection.
This is intentionally human-controlled.
Projects are displayed with a compact view of current activity.
The dashboard does not attempt to replace the agents' native development environments.
Security was a major part of the public-release audit.
The project was reviewed for:
- hardcoded secrets
- API keys
- tokens
- passwords
- private keys
- filesystem path leaks
- SQL injection
- command injection
- role bypasses
- unsafe network binding
- sensitive local data
- accidental database commits
The audit found no embedded secrets.
The server defaults to:
127.0.0.1
rather than binding to all network interfaces.
This is important because NavOS is designed as a local-first system.
The server can therefore remain local unless the user intentionally exposes it through another mechanism.
Database operations use parameterized SQL queries rather than constructing SQL statements directly from user-controlled values.
This reduces the risk of SQL injection.
Where external processes are executed, argument arrays are used rather than constructing shell commands from untrusted strings.
The implementation uses process execution with explicit argument separation.
Project roles are enforced server-side.
The client UI is not treated as the security boundary.
For example, simply changing a dashboard selection or sending a crafted request should not grant an agent Commander or Worker permissions.
NavOS checks the authenticated logical agent and its project role.
NavOS is designed to operate locally.
Local runtime information such as:
- database contents
- local agent state
- local project paths
- temporary runtime state
should not be committed to the public repository.
The public-release audit specifically checked for personal filesystem paths and local runtime data.
The project was audited before public release.
The audit checked for:
- personal filesystem paths
- OneDrive paths
- usernames
- API keys
- authentication tokens
- passwords
- private keys
- bearer tokens
- JWTs
- webhook URLs
- local databases
The repository was cleaned so local runtime data and configuration are ignored.
Runtime and local-only data is excluded from the repository.
Examples include:
config/config.json
data/*
scratch/
coverage/
.nyc_output/
.temp/
while appropriate example/configuration files remain available for users.
NavOS has been heavily tested during development.
The final public-release verification included:
74 / 74 JavaScript / TypeScript tests passed
Additional Python project tests passed:
9 / 9
11 / 11
The test suites covered areas including:
- dashboard redesign
- identity lifecycle
- session lifecycle
- reconnect behavior
- stateless clients
- ChatGPT simulation
- Codex simulation
- Antigravity behavior
- role isolation
- native agent separation
- stale session handling
- project filtering
- agent deletion
- lifecycle hardening
A major part of the NavOS development process was testing whether different AI clients could remain in an autonomous Commander → Worker workflow without requiring the human to manually press "Continue" or send every next instruction.
The experiments revealed that different AI clients behave very differently when they are idle.
NavOS itself can track that a new phase is ready, but the AI client must have some mechanism that causes it to start or resume a reasoning turn.
The following clients were tested.
Role tested: Worker
Environment: Antigravity IDE
Result: ✅ Successfully tested
Antigravity was the most successful environment for the autonomous Worker loop.
Antigravity supports background tasks.
A background watcher process was used to wait for changes in NavOS project state.
The general workflow was:
Antigravity Worker
│
│ Wait for next phase
▼
Background Watcher
│
│ Poll NavOS
▼
Phase becomes available
│
▼
Watcher exits
│
▼
Background task completes
│
▼
Antigravity wakes/resumes
│
▼
Gemini continues reasoning
│
▼
Worker executes phase
The important discovery was that completion of a background task can wake/resume Antigravity's AI workflow.
This made it possible to build a practical waiting mechanism around NavOS.
Experiments
A simple delayed background task was tested using a command equivalent to:
Wait 10 seconds → complete task → output wake-up marker
Antigravity resumed automatically when the background task completed.
A longer one-shot delay was also tested.
The same mechanism successfully allowed Antigravity to remain waiting for NavOS and resume when the required condition occurred.
MCP notification behavior
MCP notifications by themselves were also investigated.
Notifications such as:
notifications/message progress resource updates tools/list changes
do not automatically cause an idle Gemini/Antigravity model to begin a new reasoning turn.
Therefore:
MCP notification ≠ AI wake-up
The practical solution was to use a background task whose completion causes the Antigravity environment to resume the model.
Result
Antigravity successfully acted as the NavOS Worker in the full autonomous project test.
Role tested: Commander
Environment: Codex Desktop
Result: ✅ Successfully tested
Codex was successfully used as the Commander in the autonomous multi-phase workflow.
However, Codex behaves differently from Antigravity.
Background process behavior
A detached/local background process can continue running while Codex is idle.
However:
Background process finishes ≠ Codex automatically starts a new reasoning turn
Therefore, simply running a watcher process was not sufficient to wake Codex.
Heartbeat / Scheduled Execution
Codex's heartbeat/scheduled execution mechanism was tested successfully.
The workflow was:
Codex
│
│ Creates/starts workflow
▼
NavOS
│
│ Worker performs phase
▼
NavOS state changes
│
│
▼
Codex heartbeat
│
│ Starts a fresh reasoning turn
▼
Codex checks NavOS
│
▼
Codex continues workflow
A one-time heartbeat test successfully caused Codex to wake and execute a new reasoning turn without a manual user message.
The test produced the expected wake-up output:
NAVOS_CODEX_HEARTBEAT_WAKE_TEST Result
Codex successfully operated as the Commander in the full autonomous test.
Role tested: Commander / Coordinator
Environment: ChatGPT Web
Result: ✅ Wake-up mechanism tested
ChatGPT Web was tested using scheduled/heartbeat-style execution.
The important difference is that a scheduled ChatGPT execution does not necessarily continue inside the exact same conversation turn.
Instead, it can start a new ChatGPT turn/context.
The tested workflow was:
ChatGPT
│
│ Initial turn
▼
NavOS
│
│ Wait
▼
Scheduled execution
│
▼
New ChatGPT turn
│
▼
Reconnect to NavOS
│
▼
Check persistent NavOS state
│
▼
Continue coordination
A heartbeat test successfully woke ChatGPT and caused it to reconnect to NavOS.
The resulting test confirmed:
NavOS Universal AI Bridge: ONLINE Active connections: 3 Registered projects: 1 ChatGPT agent: CONNECTED
This demonstrated that ChatGPT can be used with an external persistent coordination layer even though the scheduled execution may occur in a new chat/turn context.
Important limitation
ChatGPT Web does not behave like a persistent native IDE process.
A scheduled wake-up should therefore be treated as:
New reasoning turn + Persistent external NavOS state
rather than:
Same conversation continuously running
This means NavOS must keep enough persistent state for the AI to reconstruct what is happening when it wakes.
Cross-Client Wake-Up Comparison
The experiments showed three different behaviors.
AI Client Tested Role Wake Mechanism Result Antigravity / Gemini Worker Background task completion ✅ Successful Codex Desktop Commander Heartbeat / scheduled execution ✅ Successful ChatGPT Web Commander / Coordinator Scheduled execution / heartbeat-style wake ✅ Successful
The mechanisms can be summarized as:
┌─────────────────────┬──────────────────────────────┐ │ AI Client │ Wake Mechanism │ ├─────────────────────┼──────────────────────────────┤ │ Antigravity/Gemini │ Background task completion │ │ Codex Desktop │ Heartbeat / scheduled turn │ │ ChatGPT Web │ Scheduled new turn │ └─────────────────────┴──────────────────────────────┘ What Did NOT Work
One of the most important findings was that NavOS cannot assume that sending an MCP notification will wake an idle AI model.
The following general assumption was tested and found to be unreliable:
NavOS
│
│ MCP notification
▼
Idle AI
│
└── Automatically starts thinking
Instead, the observed behavior was:
NavOS
│
│ MCP notification
▼
AI client
│
└── Notification may be received,
but idle model does not necessarily wake
Therefore, the autonomous loop depends on both sides:
NavOS must maintain persistent project/phase state. The AI client must provide some mechanism capable of starting/resuming execution. Full Autonomous 5-Phase Test
The most important end-to-end experiment used:
Commander:
Codex Desktop
Worker:
Gemini / Antigravity IDE
The project was divided into five phases.
Phase 1
Baseline project inventory
↓
Phase 2
README contract
↓
Phase 3
Configuration validation
↓
Phase 4
Automated testing
↓
Phase 5
Final verification
The Worker executed the phases inside its native project environment while the Commander coordinated the workflow.
The test completed all five phases autonomously.
The final test result included:
11 / 11 tests passed
The original project files were preserved during the experiment, including the baseline configuration and test files.
This was the first major proof that the NavOS Commander → Worker concept could operate across two different AI environments without requiring the human to manually relay every phase.
What These Experiments Proved
The experiments demonstrated several important points.
- AI agents can participate in an external persistent workflow
An AI does not need to store the entire project workflow inside its own conversation.
NavOS can maintain:
Agent Project Role Phase Report Message State
outside the AI conversation.
- Different AI clients require different wake strategies
There is no universal "wake the AI" mechanism.
Instead:
Antigravity → background task completion
Codex → heartbeat / scheduled execution
ChatGPT → scheduled new turn 3. Persistent external state is extremely important
Because some clients may start a completely new reasoning turn, NavOS needs to remain the source of truth for project coordination.
Conceptually:
AI memory + NavOS persistent state = Recoverable workflow 4. MCP alone does not solve autonomous execution
MCP can provide the communication interface, but it does not guarantee that an idle AI client will spontaneously begin another reasoning cycle.
This became one of the major architectural discoveries of the project.
Experimental Conclusion
The experiments demonstrated that autonomous multi-agent workflows are technically possible, but the implementation depends heavily on the execution model of each AI client.
The most successful tested combination was:
Codex Desktop │ │ Commander ▼ NavOS │ │ Phase coordination ▼ Antigravity / Gemini │ │ Worker ▼ Native Project
The experiment successfully completed a five-phase development workflow with no manual phase-by-phase message relay.
However, these experiments also revealed that the communication protocol and AI wake-up mechanism are separate problems.
NavOS can know that work is ready.
The remaining question is how the target AI agent should reliably receive that state change and begin its next reasoning cycle.
This distinction is one of the primary reasons the project's next-generation architecture is being evaluated before further development continues.
I'd definitely keep this section in the public README. It's actually one of the strongest parts of the project story.
The really interesting result isn't just "I connected Gemini, Codex and ChatGPT."
It's this:
NavOS State
│
▼
┌──────────────────┐
│ Phase Available │
└────────┬─────────┘
│
┌────────┼─────────┐
▼ ▼ ▼
Agy Codex ChatGPT
│ │ │
Background Heartbeat Scheduled
completion /schedule new turn
│ │ │
▼ ▼ ▼
Wakes Wakes Wakes
Same NavOS state → completely different wake mechanisms depending on the AI client.
---
# Build Verification
The project also passed the build verification step.
npm run build
completed successfully during the public-release audit.
The project is organized roughly around the following areas:
NavOS - Universal Bridge MPC/
│
├── src/
│ ├── db.ts
│ ├── index.ts
│ ├── mcp.ts
│ ├── sessions.ts
│ │
│ └── tools/
│ ├── identity.ts
│ ├── orchestration.ts
│ └── git.ts
│
├── config/
│ └── config.example.json
│
├── data/
│ └── .gitkeep
│
├── test-project/
│
├── tests/
│
├── package.json
├── tsconfig.json
├── .gitignore
└── README.md
The exact file structure may evolve as the architecture changes.
Typical requirements include:
- Windows / compatible development environment
- Node.js
- npm
- SQLite support
- An MCP-compatible AI client
Optional:
- Antigravity IDE
- Codex
- ChatGPT
- Gemini
- Secure MCP Tunnel
Clone the repository:
git clone <repository-url>
cd "NavOS - Universal Bridge MPC"Install dependencies:
npm installCreate a local configuration based on the example configuration.
config/config.example.json
Copy it to:
config/config.json
The local configuration file is intentionally ignored by Git.
Do not commit personal credentials, tokens, private keys, or local environment-specific secrets.
Start the development server using the project's configured npm scripts.
For example:
npm run devThe local dashboard is served by the NavOS server.
The MCP endpoint is available locally according to the configured server settings.
The default local binding is:
127.0.0.1
A compatible AI client connects to NavOS through MCP.
The intended workflow is:
1. Start NavOS
2. Open the AI client
3. Connect the client to NavOS
4. Explicitly call the connection mechanism
5. Provide:
- model
- client location
- directory
6. NavOS establishes the logical agent identity
Only after explicit connection should the agent appear as connected.
A native agent might identify itself as:
Model:
Gemini
Client:
Antigravity IDE
Directory:
C:\Projects\MyProject
NavOS then knows:
Type:
NATIVE
and associates the agent with its workspace.
A web agent might identify itself as:
Model:
GPT-5.6 Luna
Client:
ChatGPT Web PC
Directory:
nil
NavOS recognizes:
Type:
WEB
A native agent can register its project with NavOS.
The project registration associates the logical project with the native workspace.
Conceptually:
Agent
│
│ register_project
▼
NavOS
│
▼
Project
Project membership is tracked separately from the agent's global identity.
Once agents and a project exist:
Human
│
├── Select Commander
│
└── Select Worker
│
▼
NavOS
│
▼
Commander
│
├── Analyze project
├── Create phases
└── Coordinate Worker
│
▼
Worker
│
├── Execute phase
├── Modify files
├── Run tests
└── Submit report
│
▼
NavOS
│
▼
Next phase
NavOS includes communication primitives intended for coordination between agents.
Examples include:
send_agent_message
and project/phase reporting mechanisms.
The exact tool names and schemas may evolve while the long-term communication architecture is being evaluated.
Workers can submit reports after completing phases.
A report can contain information such as:
- work performed
- files changed
- tests executed
- results
- problems encountered
- remaining work
The Commander can use the report to determine what should happen next.
The goal is not to eliminate the human completely.
The intended model is:
Normal work
↓
Agents coordinate autonomously
↓
Human stays out of the loop
But:
Ambiguity
↓
Agent requests clarification
↓
Human responds
↓
Work continues
This makes the human a supervisor rather than a message relay.
NavOS is designed to be local-first.
When a remote AI client needs to access a locally running NavOS instance, a secure tunneling mechanism can be used instead of directly exposing the local server to the public Internet.
During development, OpenAI Secure MCP Tunnel was used to connect ChatGPT Web to the local MCP server.
Conceptually:
ChatGPT Web
│
│ Secure MCP Tunnel
▼
Local NavOS
│
▼
127.0.0.1:3020
The tunnel is external infrastructure and is not the core NavOS architecture.
Clone the repository and install dependencies:
npm installBuild:
npm run buildRun tests:
npm testDevelopment should preserve the following principles:
- Do not move native file operations into NavOS unnecessarily.
- Do not treat MCP transport sessions as permanent agent identities.
- Do not allow agents to self-assign project roles.
- Do not merge independent native agents simply because they share a directory.
- Keep authentication and authorization server-side.
- Keep local runtime data out of Git.
- Avoid unnecessary external dependencies.
The primary JavaScript / TypeScript test suite can be run with:
npm testBuild verification:
npm run buildThe experimental test project also contains Python validation tests.
NavOS was designed around local operation.
The system should not require a cloud backend simply to coordinate agents operating on a local machine.
A temporary network connection is not an agent.
The logical AI identity must survive transport reconnections.
Agents do not decide their own authority.
The human assigns:
Commander
Worker
through the orchestration layer.
A native agent works in its own environment.
NavOS should not become a remote filesystem editor simply to coordinate the agent.
NavOS coordinates work.
The AI agents execute the actual work.
This keeps the bridge lightweight and avoids turning NavOS into another IDE or remote execution framework.
NavOS is not intended to be:
- an AI model
- an LLM
- an IDE
- a replacement for Git
- a remote desktop
- a filesystem management service
- a cloud coding environment
- a model hosting platform
- a general-purpose operating system
- a replacement for MCP
- currently a finalized A2A implementation
The name "NavOS" refers to the project's orchestration/coordination concept rather than an operating system kernel.
The biggest architectural limitation discovered during development is that MCP alone does not fully solve autonomous agent-to-agent interoperability.
Further architecture research is required.
Different AI clients handle:
- MCP sessions
- background tasks
- notifications
- scheduled execution
- heartbeats
- reconnects
- idle states
differently.
Therefore, an autonomous workflow cannot assume identical behavior across all AI clients.
Web-based AI clients may create new transport sessions between turns.
Persistent logical identity therefore requires external state and explicit identity handling.
A server can know that a phase is ready.
That does not automatically mean an idle AI client will wake up.
The client must provide an appropriate mechanism such as:
- background task completion
- heartbeat
- scheduled execution
- persistent active turn
- another supported wake mechanism
The project demonstrated that a multi-agent workflow can be built around the current design, but the long-term protocol and communication architecture remain open questions.
The next stage of NavOS depends heavily on solving the agent-to-agent communication problem correctly.
Possible directions include:
MCP
+
A2A
or another dedicated communication layer.
A potential future architecture could look like:
┌──────────────┐
│ Human │
└──────┬───────┘
│
▼
┌─────────────────┐
│ NavOS │
│ Orchestrator │
└────────┬────────┘
│
┌───────────┴───────────┐
│ │
▼ ▼
┌──────────┐ ┌──────────┐
│ Agent A │◄─────────►│ Agent B │
└──────────┘ └──────────┘
│ │
▼ ▼
Tools Tools
Files IDE
Git Terminal
The exact protocol has intentionally not been finalized.
- Local NavOS server
- SQLite backend
- MCP integration
- Agent registration
- Persistent logical agent identity
- Native/Web agent distinction
- Project registration
- Project membership
- Commander / Worker model
- Phase-based workflow
- Phase reporting
- Agent messaging
- Role enforcement
- Dashboard
- Stateless session handling experiments
- SSE lifecycle handling
- Reconnect handling
- Agent deletion handling
- Autonomous wake-up experiments
- Public-release security audit
- Secret scan
- Privacy scan
- Build verification
- Automated regression testing
- Final autonomous multi-agent protocol
- Long-term agent-to-agent communication architecture
- MCP + A2A integration decision
- Production architecture
- Large-scale multi-agent deployment
Contributions, experiments, architecture discussions, and protocol ideas are welcome.
Because the project is currently in an experimental stage, architectural discussions are especially valuable.
If you want to contribute, consider focusing on:
- agent communication protocols
- MCP interoperability
- A2A interoperability
- asynchronous agent communication
- persistent agent identity
- agent discovery
- autonomous workflow design
- security
- authentication
- authorization
- lifecycle management
Before making major architectural changes, please open an issue or discussion so the design can be evaluated first.
NavOS was built around a simple question:
What happens when AI agents stop working alone and start working together?
The interesting part isn't simply making another AI tool.
The interesting part is creating the infrastructure that allows different AI systems to cooperate while keeping their own capabilities and environments.
The ideal workflow looks something like:
Human
│
│ "Complete this project."
▼
Commander
│
│ Plans
▼
NavOS
│
│ Delegates
▼
Worker
│
│ Builds
▼
NavOS
│
│ Reports
▼
Commander
│
│ Reviews
▼
Worker
│
│ Continues
▼
Completed Project
The human should not have to be the network cable between every AI.
NavOS was developed as an independent experimental project exploring:
- Multi-agent AI systems
- MCP
- AI orchestration
- Autonomous workflows
- Local-first AI infrastructure
- IDE-based AI agents
- Persistent agent identity
- Human-supervised agent collaboration
NavOS is an experimental research project.
It should not be considered production-ready infrastructure for security-critical, safety-critical, financial, or otherwise high-risk workloads without independent security review and appropriate hardening.
AI client behavior may change independently of NavOS.
Protocol support may also change as MCP, A2A, AI clients, and agent frameworks continue to evolve.
See the repository license file for the terms governing use and distribution.
Universal AI Bridge
Connect.
Coordinate.
Collaborate.