diff --git a/src/servers/sidecar/SIDECAR.md b/src/servers/sidecar/SIDECAR.md index 9efd73c0..891ccb30 100644 --- a/src/servers/sidecar/SIDECAR.md +++ b/src/servers/sidecar/SIDECAR.md @@ -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 | | 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 | + +## 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.