framework-shells

cross-control. * *Control surfaces*: CLI + optional FastAPI/WS UI for listing, logs, and lifecycle actions. * Optional *hooks* for host integration (external registries/telemetry). ### CLI quickstart ```bash # list shells fws list # run a one-off shell (no spec) fws run --backend pty --label demo -- bash -l -i # apply a YAML shellspec (recommended) fws up shells.yaml # terminate shells fws down # attach to a dtach-backed shell fws attach <shell_id> # show managed shells + procfs descendants fws tree --depth 4 ``` ### Shellspec example ```yaml version: "1" shells: worker: backend: proc cwd: ${ctx:PROJECT_ROOT} subgroups: ["worker", "project:${ctx:APP_ID}"] command: ["python", "-m", "your_module.worker", "--port", "${free_port}"] ``` ### Isolation + security model (simple by default) * `FRAMEWORK_SHELLS_SECRET` derives the `runtime_id` (namespace) and API tokens. * If the secret is set, mutating API endpoints require: * `Authorization: Bearer <token>` (or `X-Framework-Key`). * If the secret is unset, auth is disabled (dev mode). Hard limit: if two runtimes share the same OS user/UID, the OS may still allow signaling each other’s processes. The guarantee is: no cross-count/adopt/control *through the library’s control plane*. ### Real-world usage I use this as the substrate of a full dev environment where “apps are shells” (terminals, IDE + LSP, agent/MCP, aria2 RPC, file explorer, llama.cpp runner, etc.). Repo: ```text https://github.com/mrsurge/termux-extensions-2 ``` ### Feedback I want * Does the secret/fingerprint/runtime isolation contract feel right? * Any obvious foot-guns in the default API/CLI? * Expectations vs systemd/supervisord/tmux/dtach: where would you use this? github.com/mrsurge/framework-shells pip install "framework-shells @ git+https://github.com/mrsurge/framework-shells@main" ```bash fws --help ```