Understanding MiraBridge's architecture helps you get the most out of the platform.
The Orchestration Model
In MiraBridge, the developer is the orchestrator — not the coder. You give instructions, the AI writes code. You approve tool executions, the AI applies changes.
Gateway — The Central Hub
The Gateway is a NestJS backend that serves as the single connection point for all clients. It handles:
- AI processing — routing requests to Claude, GPT, or Gemini
- Tool execution — dispatching file, terminal, and git operations to VS Code
- Real-time sync — WebSocket-based message delivery between devices
- Authentication — JWT tokens with refresh, OAuth (GitHub/Google)
- Billing — prepaid credits, usage tracking, Stripe integration
Device Registry
The Gateway maintains a device registry tracking all connected clients:
- Desktop App - standalone local runner for workspace tools, terminal commands, git, patch review, and approvals
- VS Code Extension - editor-native local runner for IDE-centered work
- Mobile App - remote control, approval, notification, and monitoring surface
- Codex Bridge - translates between MiraBridge and Codex CLI
Tool Execution Flow
When the AI needs to perform an action:
- AI requests a tool execution (e.g., write a file)
- Gateway routes the request to the runner that owns the session, such as Desktop or VS Code
- The runner shows an approval dialog when approval is required
- You approve or reject
- The runner executes the tool locally and sends the result back through Gateway
Desktop and VS Code do not call each other directly. They share backend contracts, but each runner owns its own workspace context and session lifecycle.
WebSocket Communication
All real-time communication uses WebSocket with a custom message protocol. Messages are typed and versioned, supporting streaming, tool approval, plan mode, and more.
Next Steps
- Your First Session — see these concepts in action
- Desktop Agent Workflows — standalone desktop sessions
- Tools & Commands — explore the 40+ available tools