add future possibilities section to sidecar docs

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
2026-03-05 07:44:36 +00:00
co-authored by Claude Opus 4.6
parent 86c2d6333a
commit 5e86fcff88
+19
View File
@@ -345,3 +345,22 @@ On restart, the sidecar reads the persisted state and checks which PIDs are stil
| Two sidecar instances running | Lockfile with PID liveness check on startup | | Two sidecar instances running | Lockfile with PID liveness check on startup |
| Sidecar needs DB access | Imports DB modules directly (same user, same filesystem) | | Sidecar needs DB access | Imports DB modules directly (same user, same filesystem) |
| Queue handlers need server context | Handlers are self-contained modules imported by the sidecar | | Queue handlers need server context | Handlers are self-contained modules imported by the sidecar |
## Future Possibilities
The current architecture is one API server → one sidecar. But the protocol is sidecar-agnostic and could evolve in the opposite direction: one API server → many sidecars.
```
┌── sidecar-A (machine 1, user X's files)
API server ───┼── sidecar-B (machine 2, heavy compute)
└── sidecar-C (localhost, default)
```
In this model the API server becomes the orchestrator — it decides which sidecar to dispatch to based on the user, the task type, or available capacity. A user's Claude Code session runs on the machine where their project files live. A long-running Pi agent gets dispatched to a box with more resources. Quick jobs stay local.
What would need to change:
- **Sidecar identity**: Each sidecar needs a name/id. The current hardcoded `ws://127.0.0.1:5100` becomes a registry of endpoints (config file or DB table).
- **Connection pool**: `sidecar-client.ts` becomes a pool of connections rather than a singleton.
- **Routing**: The API server needs a session→sidecar mapping so it knows where to forward browser messages.
- **The protocol itself**: Doesn't change. A `pi:spawn` command works the same whether it goes to a local or remote sidecar.