README.md

---
title: GBridge PhoneGPU
emoji: 📱
colorFrom: indigo
colorTo: blue
sdk: docker
app_port: 7860
pinned: false
license: mit
---

# GBridge PhoneGPU + M5 API Gateway

**The Hugging Face Space that turns an iPhone into a private ML server, provides a WebOllama-style local compute gateway, and turns Windsurf into the build agent for the bridge itself.**

The Space is the public endpoint. The iPhone is the private model worker. Windsurf is the engineering agent. gbridge is the connective tissue. M5 provides OpenAI-compatible access to local Ollama compute. Every job produces a signed receipt.

## What this is

GBridge is a **capability-to-endpoint connectivity layer**.

A live node (iPhone, browser, Windsurf agent) advertises a capability, leases it to the Space, and the Space binds it to an HTTP/WebSocket endpoint. Jobs route to the node. Results return with signed receipts.

## Pages

- `/` — Landing / Manifest
- `/phone` — iPhone compute bridge with QR pairing
- `/gbridge` — Protocol explorer with capability lease table
- `/windsurf` — Build packet generator and MCP manifest export
- `/receipts` — Proof console for signed compute receipts
- `/dashboard` — 2050 real-time control plane
- `/m5` — M5 API Gateway (WebOllama-style local compute interface)

## Core API

- `POST /api/gbridge/session` — create compute session
- `GET /api/gbridge/session/{id}` — session status
- `POST /cap/{capability_name}` — invoke leased capability
- `GET /api/windsurf/packet` — Windsurf build packet
- `GET /api/windsurf/mcp` — MCP server manifest
- `POST /api/windsurf/ingest` — ingest agent build report
- `GET /api/receipts` — list receipts
- `POST /api/receipts/{id}/verify` — verify receipt

## M5 API Gateway (OpenAI-Compatible)

M5 provides a Groq/OpenRouter-style API gateway for local Ollama compute.

### Account API

- `POST /api/accounts/register` — Create account
- `POST /api/accounts/login` — Login and get API key
- `GET /api/accounts/me` — Get account details
- `POST /api/accounts/api-keys` — Create API key
- `DELETE /api/accounts/api-keys/{key_id}` — Revoke API key
- `POST /api/accounts/chats` — Create chat session
- `GET /api/accounts/chats` — List chat sessions
- `GET /api/accounts/chats/{session_id}` — Get chat history

### OpenAI-Compatible API

- `POST /v1/chat/completions` — Chat completions (supports streaming)
- `GET /v1/models` — List available Ollama models

### Usage Example

```bash
# Register
curl -X POST https://your-space.hf.space/api/accounts/register \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"pass123","name":"User"}'

# Login to get API key
curl -X POST https://your-space.hf.space/api/accounts/login \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"pass123"}'

# Use OpenAI-compatible endpoint
curl -X POST https://your-space.hf.space/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "X-API-Key: m5_xxxx" \
  -d '{"model":"llama3.2","messages":[{"role":"user","content":"Hello"}],"ollama_url":"http://localhost:11434"}'
```

## gbridge primitive

```python
route_capability_call(capability_name, payload)
```

1. Find active lease for capability
2. Verify lease is not expired
3. Check payload policy
4. Create job
5. Route to correct node
6. Return async job id
7. Verify receipt
8. Return output + receipt

## Architecture

```
Hugging Face Space
  ├── gbridge router
  ├── phone relay (WebSocket)
  ├── receipt verifier
  ├── Windsurf packet generator
  └── MCP manifest exporter

iPhone Worker (PWA)
  ├── local runtime detector
  ├── local ML / redaction / embeddings
  ├── device keypair
  └── signed receipt emitter

Windsurf / Cascade
  ├── consumes generated build packet
  ├── optionally connects through MCP/gbridge manifest
  ├── patches repo
  └── sends build report back as receipt
```

## What this is

PhoneGPU Space creates a new topology:
- **Public Space** = control plane, API, marketplace, verifier, dashboard
- **iPhone** = private edge inference node (Neural Engine / GPU / CPU)
- **Receipt** = proof of local execution

This is not cloud inference from a phone. This is **device-leased inference**: a public Hugging Face Space temporarily binds a private iPhone as its backend ML worker through a revocable, receipt-producing compute session.

## How it works

1. Open the Space and create a session
2. Scan the QR code with your iPhone
3. The iPhone registers as a worker and advertises its capabilities
4. Submit an inference job through the Space UI or API
5. The iPhone receives the job, runs it locally with Core ML / Web ML
6. The iPhone returns the result plus a signed receipt
7. The Space verifies and stores the receipt

## Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `SPACE_PUBLIC_URL` | Public URL of this Space | Auto-detected |
| `SESSION_TTL_SECONDS` | Session lifetime | 3600 |
| `JOB_TTL_SECONDS` | Job timeout | 300 |
| `MAX_PAYLOAD_BYTES` | Max request payload | 10485760 |
| `REQUIRE_DEVICE_SIGNATURES` | Require signed receipts | false |
| `RECEIPT_STORAGE_PATH` | Where to store receipts | ./data/receipts.jsonl |

## API Endpoints

- `POST /api/session` — Create a new compute session
- `GET /api/session/{id}` — Get session status
- `POST /api/session/{id}/job` — Submit inference job
- `GET /api/job/{id}` — Get job result
- `GET /api/receipt/{id}` — Get signed receipt
- `POST /api/receipt/{id}/verify` — Verify receipt
- `GET /worker` — iPhone worker page (with QR scan)
- `WS /ws/worker/{session_id}/{worker_id}` — Worker WebSocket

## Capabilities (v1)

- `iphone.text.embedding.private` — Local text embedding
- `iphone.image.classify.local` — Local image classification
- `iphone.privacy.redact.local` — Local privacy redaction

## Architecture

```
User → HF Space UI/API → Session → Job Queue → iPhone Worker → Core ML/ONNX/WebML → Signed Result → Receipt
```

## Security

- Outbound-only connections from iPhone (no inbound ports needed)
- Worker join tokens with expiry
- Ed25519 receipt signatures where supported
- Input/output hashing for verification
- Privacy modes: raw, hash-only, local-only

## Development

```bash
pip install -r requirements.txt
python -m uvicorn app.main:app --host 0.0.0.0 --port 7860
```

## License

Proprietary — Membra Technologies