Internal endpoints
Not part of the public API. Routes under the /x/ prefix are Egg-internal contracts used by the browser shell and the Egglet runtime. They may change without notice, are not covered by version guarantees, and aren’t intended for third-party consumption. Build against /api/v1/ instead.
Scope & stability
The /x/ namespace exists for one reason: keep the gateway as the single point of external network egress without forcing every Egg-internal call shape into the public contract. These routes do things the public API doesn’t need to do, the same way they’ve always been done. Their shapes evolve with the browser’s internals.
Two safety properties still hold here:
- Same bearer-token auth as the public API.
/x/ isn’t a backdoor; it’s just unversioned.
- Every outbound URL still passes through the gateway’s SSRF guard.
/x/ endpoints don’t bypass network safety.
The shapes below reflect the current implementation. Read the source if precision matters.
Cloud relay — /x/cloud-relay
Generic passthrough to Egg’s cloud relay, used by call sites whose paths don’t fit a typed family. The body is {method, path, body?}; the gateway forwards to $CLOUD_URL/$path with device-id and device-secret headers and returns the response JSON.
| Method | Path | Purpose |
|---|
| POST | /x/cloud-relay | Forward an arbitrary request to the cloud relay. Used for telemetry, embeddings proxy, feedback, and one-off paths. |
Agent calls — /x/agent-calls
Inter-device agent-call coordination via the cloud relay. The receiving daemon polls; the sending daemon posts results.
| Method | Path | Purpose |
|---|
| POST | /x/agent-calls/send | Send an agent call to a paired device. |
| GET | /x/agent-calls/poll | Long-poll for inbound agent calls. |
| POST | /x/agent-calls/ack | Acknowledge a polled command. |
| POST | /x/agent-calls/result | Send a result back for a previously received call. |
| GET | /x/agent-calls/poll-results | Long-poll for inbound results. |
Pairing — /x/pairing
| Method | Path | Purpose |
|---|
| GET | /x/pairing/list | List paired devices known to the cloud relay. |
| POST | /x/pairing/invite | Create an invite. |
| POST | /x/pairing/accept | Accept an invite. |
| DELETE | /x/pairing/{id} | Revoke a pairing. |
Group chat — /x/group-chat
| Method | Path | Purpose |
|---|
| POST | /x/group-chat/broadcast | Broadcast a message to a linked group. |
| POST | /x/group-chat/link | Link to a group. |
| POST | /x/group-chat/unlink | Unlink. |
DM — /x/dm
| Method | Path | Purpose |
|---|
| POST | /x/dm/send | Send a direct message via the cloud relay. |
| GET | /x/dm/poll | Long-poll for inbound DMs. |
Notifications — /x/notifications
| Method | Path | Purpose |
|---|
| GET | /x/notifications/channels | List notification channels. |
| POST | /x/notifications/channels | Save a channel. |
| DELETE | /x/notifications/channels/{id} | Delete a channel. |
| POST | /x/notifications/send | Send a notification. |
| GET | /x/notifications/log | Recent notification history. |
Explorations — /x/explorations
| Method | Path | Purpose |
|---|
| POST | /x/explorations/register | Register an exploration view with the cloud index. |
Streams — /x/streams
WebRTC signaling passthrough for peer-to-peer streams (ICE candidates and SDP offers).
| Method | Path | Purpose |
|---|
| POST | /x/streams/{id}/signal | POST an ICE candidate / offer / answer. |
| GET | /x/streams/{id}/poll/{rid} | Long-poll for signaling from a peer. |
| DELETE | /x/streams/{id} | Close the stream. |
Podcasts — /x/podcasts
| Method | Path | Purpose |
|---|
| GET | /x/podcasts/proxy | Proxy a podcast-feed read through Egg’s cloud. |
YouTube — /x/youtube
| Method | Path | Purpose |
|---|
| GET | /x/youtube/proxy | Proxy a YouTube data-API read. |
Cloud LLM proxies — /x/proxy
Direct cloud-relay proxies for two specific upstream operations that don’t fit the capability-router model.
| Method | Path | Purpose |
|---|
| POST | /x/proxy/gemini-video | Vertex AI video analysis. |
| POST | /x/proxy/imagen-generate | Vertex AI Imagen generation. |
Cloud commands — /x/cloud-commands
The gateway polls Egg’s cloud for inbound commands and queues them locally. The browser drains the queue, executes commands, and posts results back.
| Method | Path | Purpose |
|---|
| GET | /x/cloud-commands/pending | Drain queued commands. |
| POST | /x/cloud-commands/result | Post a command result. The gateway forwards it upstream and acks. |
| POST | /x/cloud-commands/fast-mode | Toggle 5-second fast polling. |
Filter lists — /x/filter-lists
| Method | Path | Purpose |
|---|
| POST | /x/filter-lists/refresh | Force a refresh of EasyList / EasyPrivacy. The gateway also refreshes on a 24-hour interval when aggressive ad-blocking is enabled. |
Raw LLM — /x/llm
Provider-direct LLM routes used by the in-tree egg-llm proxy. These bypass the capability tier gate and are not intended for external callers; use /api/ai/* instead.
| Method | Path | Purpose |
|---|
| POST | /x/llm/chat | Non-streaming chat against a specific provider+model. |
| POST | /x/llm/chat-with-tools | Same, with tool-calling. |
| POST | /x/llm/streaming | SSE-streamed chat. |
| GET | /x/llm/openrouter-models | List OpenRouter models. No auth payload in body; reads the OpenRouter key from the gateway’s credential store. |
Skills — /x/skills
| Method | Path | Purpose |
|---|
| POST | /x/skills/discover | Read a site’s well-known skill manifest. |
| POST | /x/skills/fetch-source | Clone a skill source tree from git into a gateway-managed temp dir. Returns the path. |
| POST | /x/skills/fetch-tarball | Download a skill release tarball or zip. |
Extensions — /x/extensions
| Method | Path | Purpose |
|---|
| POST | /x/extensions/fetch-crx | Download a CRX bundle from the Chrome Web Store. {extension_id, source?}. |
Search — /x/search
| Method | Path | Purpose |
|---|
| POST | /x/search/google-scrape | Scraped Google search. Internal because the response shape depends on Egg’s anti-bot handling and isn’t stable. |
Images — /x/images
| Method | Path | Purpose |
|---|
| POST | /x/images/cache | Prefill the browser image cache for a URL. Returns the cache path. |
Storage — /x/storage
| Method | Path | Purpose |
|---|
| POST | /x/storage/gcs/upload | Upload a local file to Egg’s GCS bucket using the gateway’s service-account credentials. {local_path, bucket, object_key, content_type?}. |
Egglet — /x/egglet
| Method | Path | Purpose |
|---|
| POST | /x/egglet/fetch | Egglet runtime fetch helper. Subject to per-Egglet network policy. |
AI assets — /x/ai/assets
Install / list / uninstall surfaces for local AI assets the Settings UI wires up. Egg-internal lifecycle plumbing; day-to-day, callers use the capability endpoints under /api/ai/* and the gateway resolves the asset.
| Method | Path | Purpose |
|---|
| GET | /x/ai/assets/whisper | List installed Whisper variants. Whisper can back /api/ai/transcribe or /api/ai/speech-recognize depending on capability configuration. |
| POST | /x/ai/assets/whisper | Install a Whisper variant. {model_key}. SSE download progress. |
| DELETE | /x/ai/assets/whisper/{key} | Uninstall. |
| GET | /x/ai/assets/vad | List installed VAD assets. Backs /api/ai/vad. |
| POST | /x/ai/assets/vad | Install a VAD model. {variant: "silero"}. SSE download progress. |
| DELETE | /x/ai/assets/vad/{variant} | Uninstall. |
| GET | /x/ai/assets/rerank | List installed reranker assets. Backs /api/ai/rerank. |
| POST | /x/ai/assets/rerank | Install a reranker. {variant: "ms-marco-minilm-l6-v2"}. SSE download progress (tokenizer + model). |
| DELETE | /x/ai/assets/rerank/{variant} | Uninstall. |
| GET | /x/ai/assets/tts/piper | List installed Piper voices and binary status. Backs /api/ai/tts when run with backend: "local" or when auto-prefer kicks in. |
| POST | /x/ai/assets/tts/piper | Install the Piper binary for this platform. SSE download progress. |
| DELETE | /x/ai/assets/tts/piper | Uninstall the binary and all voices. |
| POST | /x/ai/assets/tts/piper/voices | Install a voice. {voice: "en_US-libritts_r-medium"}. SSE. |
| DELETE | /x/ai/assets/tts/piper/voices/{key} | Uninstall one voice. |
Agent internals — /x/agent
Renderer-facing read and edit surfaces for the agent’s internal state: background thinking sessions, the curiosity queue, reflections, identity, and personality files. The agent harness itself runs inside the daemon and writes to this state through direct function calls; these HTTP routes exist so the UI can display and let the user hand-edit the same state. Shapes mirror the harness and change with it.
| Method | Path | Purpose |
|---|
| GET | /x/agent/background | List background-thinking sessions. |
| POST | /x/agent/background/start | Start a new session. |
| GET | /x/agent/background/{id} | Read a session’s state. |
| POST | /x/agent/background/{id}/continue | Continue a paused session. |
| GET | /x/agent/curiosity | The curiosity queue: questions surfaced by background thinking. |
| GET | /x/agent/reflection | Current reflection state. |
| GET | /x/agent/reflections | List recorded reflections. |
| GET / PUT | /x/agent/identity | Read or update the agent’s self-model. |
| GET / PUT | /x/agent/personality/{file} | Read or update one personality file. |