README.md

---
title: Ubuntu
emoji: 📚
colorFrom: gray
colorTo: blue
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://huggingface.co/proxy/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