Problem Statement
UAM currently runs as a single application on one machine. All provider sessions execute locally, sharing the same CPU and memory. On machines with limited resources, running many provider instances simultaneously can become constrained. Offloading provider workloads to other machines on the local network would remove this per-machine bottleneck while keeping the primary device as the management interface.
This is an architectural idea worth exploring in the future when time and resources allow. It is not currently a pressing issue.
Proposed Architecture
Three Component Roles
| Role |
Description |
| Management Node |
Central brain: owns chat state, settings, session registry, and sync. Runs one embedded processing node for local work. |
| Processing Node |
Stateless worker: runs provider CLIs, streams I/O back via WebSocket, and discovers itself on the LAN. |
| Frontend |
React UI (desktop or mobile). Connects to a Management Node, displays chats, and sends prompts. |
Deployment Modes
Packaged (default, current behavior): Single binary containing Management Node, Processing Node, and Frontend, all running locally. Works exactly as today with zero configuration changes.
Split: Components run separately across machines on the local network:
- Primary device: Frontend + Management Node (with embedded local processing node)
- Other machines: Processing Nodes deployed via Docker Compose
- Mobile device: Mobile Frontend connecting to the Management Node over LAN
How It Would Work
Processing Nodes advertise their presence on the local network. The Management Node discovers them and can route provider sessions to any available node. The Frontend remains unaware of where sessions run — it simply displays chats and sends prompts as usual.
A mobile-optimized Frontend would use the same React codebase with a simplified single-column layout, chat list menu, and full compose functionality, connecting to the Management Node over the local network.
Incremental Path
Phase 1 — Thread pool (single machine improvement):
Move session polling to background threads. Improves concurrency on a single machine without any distribution complexity. No API changes, transparent to the user.
Phase 2 — Process launcher abstraction:
Abstract how provider processes are launched, enabling both local and remote implementations. The Processing Node becomes a standalone binary deployable on any machine.
Phase 3 — Management Node + network discovery:
Extract the Management Node, add network-based peer discovery, and enable session routing to remote Processing Nodes. The Frontend becomes a thin client connecting to the Management Node.
Phase 4 — Mobile Frontend:
Mobile-optimized React UI connecting to the Management Node on the local network.
Pros
- Removes per-machine resource limits: Offloading to other machines eliminates individual hardware constraints
- Leverages existing hardware: Uses machines already available on the network
- Incremental: Each phase ships independently and improves the experience
- Backward compatible: Packaged mode preserves current behavior with no configuration changes
- Mobile access is a natural extension: Same Management Node, different Frontend skin
- Proven patterns exist: Zero-config LAN discovery and mTLS are mature, well-tested technologies
Cons / Risks
- Significant architectural rewrite: The current monolithic design would need fundamental restructuring
- Network reliability: LAN drops and firewall issues could break the mesh; graceful degradation would be needed
- Security surface: Any networked service introduces attack vectors, though mTLS mitigates this
- Debugging complexity: Distributed sessions across machines are harder to debug than local ones
- Development time: This is a version 5 scope requiring substantial time and resources
Open Questions
- If a Processing Node disconnects mid-session, does the session pause, fail, or migrate?
- Should certain providers always run on specific OS types, or be user-configurable?
- Providers needing filesystem access — does the Processing Node need project files synced?
- What authentication model between Frontend and Management Node on the LAN?
- Docker support for Processing Nodes? Platform-specific images for Windows vs Linux?
- Mobile tech choice: React PWA, Capacitor wrapper, or separate React Native app?
Status
This is an architectural idea and enhancement to explore in the future when there is more time and resources available. It is not currently a blocking issue. The current packaged architecture works well; this would extend it for users who benefit from distributed compute across multiple machines.
Problem Statement
UAM currently runs as a single application on one machine. All provider sessions execute locally, sharing the same CPU and memory. On machines with limited resources, running many provider instances simultaneously can become constrained. Offloading provider workloads to other machines on the local network would remove this per-machine bottleneck while keeping the primary device as the management interface.
This is an architectural idea worth exploring in the future when time and resources allow. It is not currently a pressing issue.
Proposed Architecture
Three Component Roles
Deployment Modes
Packaged (default, current behavior): Single binary containing Management Node, Processing Node, and Frontend, all running locally. Works exactly as today with zero configuration changes.
Split: Components run separately across machines on the local network:
How It Would Work
Processing Nodes advertise their presence on the local network. The Management Node discovers them and can route provider sessions to any available node. The Frontend remains unaware of where sessions run — it simply displays chats and sends prompts as usual.
A mobile-optimized Frontend would use the same React codebase with a simplified single-column layout, chat list menu, and full compose functionality, connecting to the Management Node over the local network.
Incremental Path
Phase 1 — Thread pool (single machine improvement):
Move session polling to background threads. Improves concurrency on a single machine without any distribution complexity. No API changes, transparent to the user.
Phase 2 — Process launcher abstraction:
Abstract how provider processes are launched, enabling both local and remote implementations. The Processing Node becomes a standalone binary deployable on any machine.
Phase 3 — Management Node + network discovery:
Extract the Management Node, add network-based peer discovery, and enable session routing to remote Processing Nodes. The Frontend becomes a thin client connecting to the Management Node.
Phase 4 — Mobile Frontend:
Mobile-optimized React UI connecting to the Management Node on the local network.
Pros
Cons / Risks
Open Questions
Status
This is an architectural idea and enhancement to explore in the future when there is more time and resources available. It is not currently a blocking issue. The current packaged architecture works well; this would extend it for users who benefit from distributed compute across multiple machines.