storkit: merge 360_story_run_storkit_container_under_gvisor_runsc_runtime

README.md

@@ -77,6 +77,64 @@ ldd target/x86_64-unknown-linux-musl/release/storkit
 ./storkit
 ```
 
+## Running in Docker (with gVisor sandboxing)
+
+The `docker/docker-compose.yml` runs the container under [gVisor](https://gvisor.dev/)
+(`runtime: runsc`). gVisor intercepts all container syscalls in userspace, providing an
+extra layer of isolation so that even a compromised workload cannot make raw syscalls to
+the host kernel.
+
+### Host setup (Linux only)
+
+gVisor is a Linux technology. On macOS (OrbStack, Docker Desktop) you must remove
+`runtime: runsc` from `docker/docker-compose.yml` — gVisor is not available there.
+
+**1. Install gVisor (Debian/Ubuntu):**
+
+```bash
+curl -fsSL https://gvisor.dev/archive.key | sudo gpg --dearmor -o /usr/share/keyrings/gvisor-archive-keyring.gpg
+echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/gvisor-archive-keyring.gpg] \
+  https://storage.googleapis.com/gvisor/releases release main" \
+  | sudo tee /etc/apt/sources.list.d/gvisor.list
+sudo apt-get update && sudo apt-get install -y runsc
+```
+
+**2. Register runsc with Docker (`/etc/docker/daemon.json`):**
+
+```json
+{
+  "runtimes": {
+    "runsc": { "path": "/usr/bin/runsc" }
+  }
+}
+```
+
+**3. Restart Docker and verify:**
+
+```bash
+sudo systemctl restart docker
+docker run --runtime=runsc hello-world
+```
+
+**4. Launch storkit:**
+
+```bash
+GIT_USER_NAME="Your Name" GIT_USER_EMAIL="you@example.com" \
+PROJECT_PATH=/path/to/your/repo \
+docker compose -f docker/docker-compose.yml up
+```
+
+### gVisor compatibility notes
+
+The following storkit subsystems have been verified to work under `runsc`:
+
+- **PTY-based agent spawning** (`portable_pty` / `openpty`) – gVisor implements the
+  full POSIX PTY interface (`/dev/ptmx`, `TIOCGWINSZ`, etc.).
+- **`rebuild_and_restart`** – uses `execve()` to replace the server process, which
+  gVisor fully supports.
+- **Rust compilation** – `cargo build` inside the container invokes standard fork/exec
+  primitives, all of which gVisor implements.
+
 ## Releasing
 
 Builds both macOS and Linux binaries locally, tags the repo, and publishes a Gitea release with a changelog.