Update README.md

README.md

@@ -7,4 +7,76 @@ sdk: docker
 pinned: false
 ---
 
+README.md
+
+# Ubuntu Agent over SSE (Hugging Face Spaces)
+
+A minimal Ubuntu sandbox exposing **MCP-style tools** (`shell`, `python`) with **Server-Sent Events** streaming in Hugging Face Docker Spaces.
+
+## Endpoints
+
+- `GET /` — health check
+- `GET /tools` — list available tools (from `tools.json`)
+- `GET /exec?tool=shell&command=ls%20-la` — run a tool and stream results via SSE
+- `GET /exec?tool=python&code=print(%27hi%27)` — run Python and stream results via SSE
+- `POST /run` — JSON body, streams results via SSE  
+  Body: `{"tool":"shell","args":{"command":"ls -la"}}`
+
+**SSE Event types:**
+- `tools` — initial tool manifest
+- `output` — stdout chunk
+- `error` — stderr chunk
+- `done` — `{ code: <exit_code> }`
+- `ping` — keepalive
+
+## Local run
+
+```bash
+npm install
+npm run dev
+# open http://localhost:7860
+
+Example (curl SSE):
+
+curl -N "http://localhost:7860/exec?tool=shell&command=uname%20-a"
+
+POST streaming:
+
+curl -N -H "Content-Type: application/json" \
+  -X POST "http://localhost:7860/run" \
+  -d '{"tool":"python","args":{"code":"import sys; print(sys.version)"}}'
+
+Notes (Hugging Face Spaces)
+
+The app must listen on 0.0.0.0:$PORT — handled in server.js.
+
+No SSH/root console is provided by Spaces; all interaction is via HTTP endpoints.
+
+Filesystem is ephemeral across restarts.
+
+
+Security
+
+Endpoints are open by default (demo). For private Spaces, rely on HF visibility. For public Spaces, add auth (tokens, IP allowlists) if needed.
+
+
+---
+
+## How to deploy to your Space quickly
+
+```bash
+# In a fresh local folder
+git init
+git remote add origin https://huggingface.co/spaces/likhonsheikh/ubuntu
+
+# Add the files above, then:
+git add .
+git commit -m "HF Ubuntu agent: SSE tools + runtime fix"
+git push origin main
+
+Once the Space finishes building, test:
+
+# Replace URL with your Space URL if different
+curl -N "https://likhonsheikh-ubuntu.hf.space/exec?tool=shell&command=ls%20-la"
+
 Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference