README.md

metadata

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

# 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

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

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

License

Proprietary — Membra Technologies