Pulsar — distributed fetch proxy

Pulsar is a generic HTTP web_fetch API on sgapps.io. Externaltools call sgapps.io, which forwards the request to a device from thecaller's own android-bridge fleet, and returns the first agent's answer.

sgapps.io is orchestrator, not fetcher. Every HTTP request leaves the Internet from one of the caller's Android devices, not from sgapps.io. This is what makes Pulsar an over-NAT proxy mesh with billing-per-request semantics.

Why it exists

• MCP servers, scripts, and other tools often need uncached HTTP fetches from arbitrary network locations. Pulsar lets them hit sgapps.io instead of orchestrating their own fleet.
• Dev / technical teams get an over-NAT proxy mesh for free — each Android device in their account becomes a request-executing agent.
• Range requests, custom headers, HTTPS cert override — all supported. Response cropped at 2 MiB (configurable up to 16 MiB).

Shape at a glance

┌─────────────┐  POST /pulsar/api/fetch       ┌───────────────────┐
│  Any HTTP   │ ─────────────────────────────▶│ sgapps.io         │
│  client     │ ◀─── {jobId, retryAfterMs}────│  services/pulsar  │
└─────────────┘                               └─────────┬─────────┘
                                                        │ enqueue
                                                        ▼
                      androidBridge.pulsarJobs
                                                        ▲
┌───────────────────────────────────────────────────────┴─────────┐
│ Agent carrier (one of):                                         │
│   - Android device · AB Desktop · preset "pulsar/web-fetch"     │
│   - Android device · AB Desktop · homepage = /pulsar/agent/ui   │
│   - Operator PC · standalone browser (Chrome/Chromium/Firefox)  │
│                                                                 │
│   - loads /pulsar/agent/ui (constant URL — no token)            │
│   - identifies itself by `bid` (AB buildIdentifier or           │
│     `browser-<hex>` from localStorage.pulsar.identity)          │
│   - polls /pulsar/agent/api/claim                               │
│   - executes fetch() with the agreed timeouts + headers         │
│   - POSTs /pulsar/agent/api/callback                            │
└─────────────────────────────────────────────────────────────────┘

Core guarantees

• First-response wins. sgapps.io may hand the same job to up to 2 agents concurrently (passive re-dispatch after a dispatch timeout). The first callback that lands wins; the later one is discarded.
• No cached fetches. sgapps.io does not cache. Every request reaches an agent that actually opens the connection.
• Per-user isolation. A job owned by user X is dispatched ONLY to devices that have X in their owners[] array (android-bridge model). No cross-tenant leakage by construction.
• Hard size limits.
• Request body: ≤ 1 MiB (reject with 413 above).
• Response body: ≤ 2 MiB default; cropped at the agent and re- cropped defensively on the server with result.cropped: true.
• Usage counters. Every settled job increments androidBridge.accountStats under the owner's _id (pulsarJobsTotal, pulsarBytesInTotal, pulsarBytesOutTotal, …) and (M8.c) pulsarUsageDaily per {userId, date}. Soney charges against the wallet are emitted by a separate biller (M10/M11) that reads these counters — pulsar itself touches no money state.

Next steps

• Getting started — step-by-step: get an agent running, approve it, issue your first fetch request.
• HTTP API reference — all three consumer endpoints with request/response shapes.
• Agent protocol — what the device-side webapp sees (useful for people porting the agent to a native runtime).
• Security model — SSRF classification, HTTPS cert override policy, allowlist lifecycle.
• Operator guide — monitoring, usage readouts, troubleshooting.