1# shipote
2
3**Runtime de espacios aislados con flujo tipado** dentro del fractal brahman.
4
5shipote no es un shell POSIX. Es un daemon long-running que:
6
7- Aísla procesos en **Workspaces** (cada uno con su `SomaSpec`: namespaces, cgroup, rlimits).
8- Encadena comandos en **Pipelines** (DAG con fan-out, fan-in, taps, replay buffer).
9- **Discierne contenido** sobre cada flow (detecta `application/json`, `text/markdown`, magic bytes, hasta `brahman:card`).
10- Expone **data plane** real: subscribers externos se conectan a Unix sockets y reciben los bytes del stream.
11- Se integra al ecosistema vía `brahman-sidecar` (anuncia Cards al broker).
12
13```
14                         ┌─────────────┐
15                         │  shipote    │  daemon long-running
16                         │  -daemon    │  $XDG_RUNTIME_DIR/shipote.sock
17                         └──────┬──────┘
18                                │ admin protocol (postcard)
19              ┌─────────────────┼─────────────────┐
20              │                 │                 │
21        ┌─────▼─────┐     ┌─────▼─────┐     ┌─────▼─────┐
22        │ shipote   │     │ shipote-  │     │  HTTP /   │
23        │  (CLI)    │     │  shell    │     │  custom   │
24        │           │     │  (GUI)    │     │  (futuro) │
25        └───────────┘     └───────────┘     └───────────┘
26```
27
28## Quick start
29
30```sh
31# 1. Compilar
32cargo build -p shipote-daemon -p shipote-cli
33
34# 2. Arrancar daemon (en una terminal):
35SHIPOTE_LOG=info ./target/debug/shipote-daemon
36
37# 3. En otra terminal:
38./target/debug/shipote health
39./target/debug/shipote workspace create demo.toml
40./target/debug/shipote run -w <ws-id> /bin/echo -- hola
41```
42
43## Estado actual
44
45- **11 crates** en el monorepo. Ver [ARCHITECTURE.md](docs/ARCHITECTURE.md).
46- **85 tests** pasando.
47- Compatible con cualquier supervisor (`ente-incarnate` es reusable — no requiere ser PID 1).
48
49## Documentación
50
51- [**ARCHITECTURE.md**](docs/ARCHITECTURE.md) — qué crates lo componen, cómo se conectan, decisiones clave.
52- [**CLI.md**](docs/CLI.md) — referencia de comandos del binario `shipote`.
53- [**RECIPES.md**](docs/RECIPES.md) — specs TOML de workspaces y pipelines con casos prácticos.
54- [**DEVELOPMENT.md**](docs/DEVELOPMENT.md) — cómo correr daemon, GUI, tests, snapshot.
55
56## Acoplamiento con el resto del monorepo
57
58| Reusa | Propósito |
59|---|---|
60| `ente-incarnate` (extraído de `ente-soma` en Fase 0) | clone(2) + namespaces + cgroup + rlimits |
61| `brahman-card` | tipos `Card`, `SomaSpec`, `Flow`, `TypeRef` |
62| `brahman-sidecar` + `brahman-handshake` | anuncio al broker |
63| `ente-snapshot` filosofía | persistencia (shipote tiene su propio `ShipoteSnapshot` v4) |
64| `yahweh-launcher` + widgets | GUI `shipote-shell` |
65| `shipote-discern` ← usado por | `yahweh-provider-fs` (mime per archivo) y `nouser-core::cluster::pick_lens` |
66
67## Limitaciones declaradas
68
69- **`mount/pid/net/uts/ipc/cgroup` namespaces** requieren `CAP_SYS_ADMIN` o combo con `CLONE_NEWUSER`.
70- **`user` namespace** puede estar bloqueado por sysctl o LSM (apparmor/selinux).
71- **`cgroup` v2 limits** (memory.max, pids.max) requieren delegation. Sin delegation, accounting funciona pero el kernel no enforce.
72- **Pipeline restart** preserva spec pero **no ULIDs** del pipeline_id (cada relaunch genera uno nuevo).
73- **Replay buffer broadcast**: subscribers tarde reciben el snapshot del replay (cap configurable por bytes o chunks), pero pueden perder chunks intermedios si el ring rota antes de conectarse.