> For the complete documentation index, see [llms.txt](https://docs.spacecoin.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.spacecoin.org/spacerouter-onion/browser-extension.md).
# Browser Extension
The SpaceRouter Onion browser extension provides a one-click interface for controlling the SpaceRouter Onion SOCKS5 proxy. It connects to the proxy's HTTP API, starts and stops circuits, displays the active relay path with country flags and IP addresses, and manages preferences such as hop count and node selection mode. The proxy must be running and reachable before the extension can do anything; see Prerequisites.
***
### Installation
Install from the [SpaceRouter Onion Proxy page on the Chrome Web Store](https://chromewebstore.google.com/detail/spacerouter-onion-extensi/dmofgbiaagkmblmpmjponfkinnnajfng). Click "Add to Chrome". The extension works in Chrome, Edge, Brave, Arc, and other Chromium-based browsers.
***
### Prerequisites
The extension controls a running `proxy` instance. The proxy must be running and its HTTP API must be reachable (default: `http://127.0.0.1:2080`). Install the proxy through the [SpaceRouter Onion App](/spacerouter-onion/app.md).
***
### Main view
The main view is the first screen you see when you open the extension popup. It contains a start/stop button, a status indicator showing whether the proxy is connected, a circuit visualization displaying the guard, middle, and exit nodes (each with a country flag and IP address), and a selection mode dropdown.
When you click **Start**, the extension:
1. Sends `POST /api/start` to the proxy.
2. Sets the browser's proxy to SOCKS5 on `127.0.0.1:` (default `1080`).
3. On Chrome, disables non-proxied UDP to prevent WebRTC leaks.
4. Fetches the active circuit from `GET /api/status` and displays it.
When you click **Stop**, the extension:
1. Sends `POST /api/stop` to the proxy.
2. Clears the browser's proxy settings.
3. Restores default WebRTC behavior (Chrome only).
#### Selection modes
| Mode | Behavior |
| ---------------- | ---------------------------------------------------------------- |
| Random (default) | Nodes chosen at random from the network |
| Fast | Prefers geographically nearby nodes as a proxy for lower latency |
| Privacy | Maximises geographic diversity across hops |
You can change the selection mode from the dropdown on the main view or from the configuration view.
***
### Configuration view
Open the configuration view by clicking the gear icon. All settings are listed below.
| Setting | Default | Description |
| -------------- | ----------------------- | ------------------------------------------------ |
| Network | (from discovery) | Network to connect to |
| Proxy API URL | `http://127.0.0.1:2080` | Address of the proxy's HTTP API |
| SOCKS5 port | `1080` | Port the proxy listens on for SOCKS5 connections |
| Hops | `3` | Number of relay hops per circuit (1 to 5) |
| Selection mode | Random | How nodes are selected for circuits |
Changes to network, hops, or selection mode require the proxy to be stopped first. The extension stops the proxy automatically, applies changes via `POST /api/preferences`, then restarts it.
***
### Nodes view
The nodes view lists every node in the selected network. Open it from the navigation bar.
| Column | Description |
| ---------- | ------------------------------------------ |
| Country | Geographic location (flag icon) |
| IP | Node IP address |
| TCP | TCP listen port |
| QUIC | QUIC listen port |
| Exit | Whether the node accepts exit traffic |
| Public key | Truncated Ed25519 identity key fingerprint |
***
### Background behavior
The extension runs a background service worker that polls `GET /api/status` every 30 seconds. If the proxy stops unexpectedly while the browser's SOCKS5 proxy settings are still active, the service worker clears those settings and shows a notification badge on the extension icon. If the proxy is running, the service worker keeps the browser proxy settings pointed at the configured SOCKS5 port.
***
### API endpoints
The extension communicates with the `proxy` binary through these HTTP endpoints:
| Method | Endpoint | Description |
| ------ | ------------------ | ------------------------------------------ |
| GET | `/api/status` | Proxy state and active circuit |
| POST | `/api/start` | Build circuit and start SOCKS5 |
| POST | `/api/stop` | Tear down circuit and stop SOCKS5 |
| GET | `/api/preferences` | Current preferences and available networks |
| POST | `/api/preferences` | Update preferences (proxy must be stopped) |
| GET | `/api/nodes` | Node list for the selected network |
The proxy exposes additional endpoints for advanced tooling (`POST /api/guard` to pin a specific guard node, `POST /api/guard/rotate` to re-select guard/middle/exit). The extension does not use these; node selection is driven entirely through the `selectionMode` preference.
***
### Appendix: browser compatibility
| Browser | SOCKS5 proxy | WebRTC protection | Notes |
| ------- | ------------------------ | ------------------------------ | -------------- |
| Chrome | Yes (`chrome.proxy` API) | Yes (disables non-proxied UDP) | Primary target |
| Edge | Yes (`chrome.proxy` API) | Yes | Same as Chrome |