HTTP API

Two HTTP servers run alongside Egg. The browser exposes tabs, navigation, screenshots, and CDP. The gateway exposes AI, media processing, fetching, privacy checks, the agent, monitors, credentials, and end-to-end-encrypted sync. Both bind to 127.0.0.1.

Discovery & auth

On startup each server writes a JSON file with its port and bearer token. Anything calling the API reads that file.

# Browser API (egg.exe)
%APPDATA%\com.eggbrowser.desktop\api_info.json
~/Library/Application Support/com.eggbrowser.desktop/api_info.json

# Gateway API (egg-daemon.exe)
%APPDATA%\com.eggbrowser.desktop\daemon_info.json
~/Library/Application Support/com.eggbrowser.desktop/daemon_info.json

# Schema
{
  "port": 19247,
  "token": "a3f8c2e1-...",
  "pid": 12345,
  "started_at": "2026-05-01T08:00:00Z"
}

# Authenticate every request with the token
PORT=$(jq -r .port  ~/Library/Application\ Support/com.eggbrowser.desktop/daemon_info.json)
TOKEN=$(jq -r .token ~/Library/Application\ Support/com.eggbrowser.desktop/daemon_info.json)

curl -s "http://127.0.0.1:$PORT/health" -H "Authorization: Bearer $TOKEN"

• Both servers bind local-only. The token is regenerated on every restart.
• Ports are random by default. Pin them with --port for development.
• The browser API and gateway API have separate tokens and separate discovery files. They’re different processes.

Conventions

The gateway groups its routes into three tiers. Each tier carries different stability guarantees.

• JSON in, JSON out. Streaming endpoints use Server-Sent Events (text/event-stream) with named events: progress, log, done, error for long-running ops; delta, tool, done for chat streams.
• Errors return { "error": { "code": "...", "message": "...", "retry_after"?: 30 } } with the appropriate HTTP status. Tier limits surface as TIER_BLOCKED on 402/429; model-capability mismatches surface as TOOLS_UNSUPPORTED on 422 (when a call passes tools to a model that does not support tool calling).
• The gateway makes all outbound HTTP. Browser clients never reach external APIs directly; everything routes through the gateway, which holds the credentials and applies tier gating where applicable.
• The capability registry (see GET /api/registry/summary) lists every configured model with its capability flags (supports_tools, supports_vision, supports_streaming). Callers can pre-check before issuing a request.

Browser API

Hosted by egg.exe. Drives the running browser: tabs, navigation, JS eval, screenshots, raw CDP.

Lifecycle & status

Tabs & pages

Automation

Data & settings

Gateway API

Hosted by egg-daemon.exe. Owns every external HTTP call Egg makes. Provider credentials live here; tier gating happens here; outbound traffic to AI providers, image hosts, search APIs, and Egg’s cloud relay all originate here.

AI — /api/ai

One endpoint per modality. Provider routing is the gateway’s responsibility: every endpoint accepts either a capability (text_fast, vision, etc.) or an explicit override. Tier gating runs before any cloud call.

Media — /api/media

Server-side media processing: probe, transcode, mux, extract, sample, download. Inputs and outputs are filesystem paths inside the app data dir, system tmp, or the OS download dir; paths outside those roots are rejected. Long-running operations stream SSE progress events.

Fetch — /api/v1/fetch

Generic external HTTP, mediated by the gateway. Every URL is validated against an SSRF allow-list: loopback, RFC1918, link-local, CGNAT, ULA, multicast, and .local are rejected, and DNS is resolved server-side to defeat rebinding.

Privacy — /api/v1/privacy

Agent chat

Autonomy & scheduling

Monitors & alerts

Credentials & queue

Provider credentials (LLM API keys, OAuth tokens, service-account JSON) live in the gateway. Read responses always redact secret material; only the gateway-internal lookup path sees raw keys.

File watches

Cross-device sync

End-to-end-encrypted device pairing. X25519 ECDH, AES-256-GCM. The cloud holds opaque ciphertext only.

Lifecycle

OpenAPI spec

The gateway publishes a machine-readable OpenAPI 3.1 document covering the versioned public surface (/api/v1/*).

curl -s "http://127.0.0.1:$PORT/api/v1/openapi.json" \
  -H "Authorization: Bearer $TOKEN"

The unversioned gateway routes (chat, autonomy, monitors, credentials, sync) are stable in practice but not yet included in the spec; they’ll be folded in as the surface settles into /api/v1/.

Internal endpoints

Routes under the /x/ prefix are Egg-internal contracts used by the browser shell and Egglet runtime. They’re documented for transparency but aren’t part of the public API: shapes change without notice and aren’t covered by version guarantees. See Internal endpoints for the full list.

Example session

# 1. Read gateway discovery
INFO="$HOME/Library/Application Support/com.eggbrowser.desktop/daemon_info.json"
PORT=$(jq -r .port  "$INFO")
TOKEN=$(jq -r .token "$INFO")
HDR="Authorization: Bearer $TOKEN"

# 2. Ask for a one-shot completion via the text_fast capability
curl -s -X POST "http://127.0.0.1:$PORT/api/ai/complete" \
  -H "$HDR" -H 'Content-Type: application/json' \
  -d '{"capability":"text_fast","messages":[{"role":"user","content":"In one sentence: what is Egg?"}]}'

# 3. Probe a video file
curl -s -X POST "http://127.0.0.1:$PORT/api/media/probe" \
  -H "$HDR" -H 'Content-Type: application/json' \
  -d '{"input_path":"/tmp/clip.mp4"}'

# 4. Fetch a page’s title and OG metadata
curl -s -X POST "http://127.0.0.1:$PORT/api/v1/fetch/page" \
  -H "$HDR" -H 'Content-Type: application/json' \
  -d '{"url":"https://eggbrowser.com","include":["title","meta"]}'

# 5. Stream a chat completion
curl -N -X POST "http://127.0.0.1:$PORT/api/ai/stream" \
  -H "$HDR" -H 'Content-Type: application/json' \
  -d '{"capability":"text_fast","messages":[{"role":"user","content":"Say hi."}]}'