# App SpaceRouter Onion is a desktop application that routes your internet traffic through a decentralized mesh network. Once installed, it acts as a local SOCKS5 proxy, sending your traffic through a multi-hop circuit of network nodes so that no single point in the network can see both who you are and what you are doing. The app downloads the `proxy` binary, registers it as a background service, and provides a graphical interface for the proxy: starting and stopping it, viewing the active circuit, and browsing nodes on the network. This page walks through the one-time setup wizard, the main interface, and all available settings. *** ### Supported platforms | Platform | Architecture | Service mechanism | Binary | | -------- | ------------------------------------------------------------------------------------------------ | ------------------------------------ | ----------- | | macOS | [arm64](https://asset-api.spacerouter.org/api/assets/app/download/darwin-arm64?env=staging) | launchd (`com.spacerouter.proxy`) | `proxy` | | macOS | [x64](https://asset-api.spacerouter.org/api/assets/app/download/darwin-x64?env=staging) | launchd (`com.spacerouter.proxy`) | `proxy` | | Windows | [x64](https://asset-api.spacerouter.org/api/assets/app/download/windows-x64?env=staging) | Windows Service (`SpaceRouterProxy`) | `proxy.exe` | | Linux | x64 ([deb](https://asset-api.spacerouter.org/api/assets/app/download/linux-x64-deb?env=staging)) | systemd user unit (`proxy`) | `proxy` | | Linux | x64 ([rpm](https://asset-api.spacerouter.org/api/assets/app/download/linux-x64-rpm?env=staging)) | systemd user unit (`proxy`) | `proxy` | The screenshots in this page are from macOS. The Windows and Linux experiences follow the same flow with native installer prompts and elevation dialogs in place of the macOS password prompts (Linux installs the systemd user unit without elevation). *** ### Installation Download the installer for your platform from the [supported platforms](#supported-platforms). Run the installer and follow the standard OS prompts (drag to Applications on macOS, run the `.exe` installer on Windows, install the `.deb` or `.rpm` on Linux). On first launch, the app opens the setup wizard. *** ### Setup wizard The first time you launch SpaceRouter Onion, a setup wizard guides you through the installation. You only need to complete this once. If a previous proxy installation is detected, the wizard handles the upgrade automatically. #### Step 1: Welcome
The welcome screen introduces SpaceRouter Onion and explains what it does. If a previous proxy installation is detected, a notice appears (for example: *Existing proxy detected. It will be uninstalled before proceeding.*). Click **Get Started** to begin. #### Step 2: Choose your client
Select which proxy binary to install: * **SpaceRouter Onion — Go**: the Go-based implementation * **SpaceRouter Onion — Rust**: the Rust-based implementation Both implementations connect to the same network and provide the same privacy guarantees. Click your preferred option; the card highlights to confirm selection and the wizard advances automatically. #### Step 3: Download Binary
The wizard shows the version that will be downloaded for your chosen implementation. Click **Download** to begin. A progress bar tracks the download. Once complete, the wizard advances to the next step automatically. #### Step 4: Install Service
SpaceRouter Onion installs itself as a background system service so it starts automatically: * **macOS:** installs a `launchd` user agent (`com.spacerouter.proxy`) * **Windows:** installs a Windows service (`SpaceRouterProxy`, requires administrator privileges) * **Linux:** installs a `systemd --user` unit (`proxy`, no elevation required) Click **Install Service** to proceed. You may be prompted to enter your macOS password (or accept a Windows UAC dialog) to authorize the installation. This is expected; installing a system service requires administrator privileges. Linux user units install without elevation. #### Step 5: Select Network
Choose which network this proxy will connect to. The dropdown is populated from the discovery backend. 1. Click the **Network** dropdown. 2. Select your network. 3. Click **Save & Continue**. If no networks appear yet, the proxy may still be initializing. Wait a few seconds and the list will populate. You can also click **Skip** and configure the network later from Settings. #### Step 6: Done
Setup is complete. SpaceRouter Onion is installed and running. The summary confirms your configuration: * **Implementation:** Go or Rust * **Version:** the installed `proxy` version * **Discovery:** the configured backend * **Network:** the selected network ID Click **Open SpaceRouter Onion** to launch the main interface. *** ### Proxy tab The **Proxy** tab is the home screen of the app. #### Proxy off
When the proxy is inactive, the status reads **"No active circuit"**. The **Chrome Extension Required** notice is shown; the SpaceRouter Onion Chrome Extension is required to configure your browser proxy and control the connection. See [SpaceRouter Onion extension](/spacerouter-onion/browser-extension.md). To start the proxy, click the **Start** link in the status bar at the bottom of the window. #### Proxy on
When the proxy is running, the status reads **"Active Circuit"** in teal. Your traffic is now being routed through the mesh. The active circuit is displayed: * **Circuit · 3 hops.** Traffic passes through three nodes before reaching the internet. * **Protocol:** the transport protocol in use (for example, `quic`). Each hop shows its role, country flag, IP address, port, and a truncated public key fingerprint: | Role | Description | | --------- | ----------------------------------------------------------- | | **Guard** | First hop. Your traffic enters the network here. | | **Mid** | Intermediate relay node. | | **Exit** | Last hop. Traffic leaves the mesh and reaches the internet. | The flow is: **Extension → Guard → Mid → Exit → Internet** To stop the proxy, click the **Stop** link in the status bar. #### Selection modes Selection mode controls how circuit nodes are picked. Set it from the Proxy tab or from Settings. | Mode | Behavior | | ---------------- | ---------------------------------------------------------------- | | Random (default) | Selects nodes at random from the discovery list | | Fast | Prefers geographically nearby nodes as a proxy for lower latency | | Maximize privacy | Maximizes geographic diversity across hops | Changing the selection mode takes effect on the next circuit build. *** ### Nodes tab
The **Nodes** tab lists all known nodes in the connected SpaceRouter Onion network. Use it to understand the network topology and verify which nodes are in your circuit. | Column | Description | | -------------- | -------------------------------------------------------------------- | | **Country** | Geographic location (flag icon) | | **IP** | Node IP address | | **TCP** | TCP port | | **QUIC** | QUIC port | | **Exit** | Marked if the node can serve as an exit | | **Public key** | Truncated key fingerprint | | **In circuit** | Role in your active circuit (Guard, Mid, Exit). Blank if not in use. | A toggle filter at the top of the table restricts the view to nodes participating in the current active circuit. *** ### Console tab
The **Console** tab streams output from the `proxy` process. Useful for troubleshooting. | Control | Function | | ------------ | --------------------------------------- | | Level filter | Show All, Info, Warn, or Error messages | | Auto-scroll | Pin the view to the latest log line | | Refresh | Reload the log stream | | Clear | Empty the log buffer in the viewer | *** ### Settings tab The **Settings** tab is scrollable and divided into sections.
#### Binary and service This panel is read-only and reflects the current installation state. | Field | Description | | -------------- | --------------------------------------------------------------------------------------------------- | | Implementation | Go or Rust | | Version | Installed `proxy` version | | Install path | Binary location on disk | | Service status | Running, Stopped, Not installed, or Unknown | | Service name | `com.spacerouter.proxy` (macOS), `SpaceRouterProxy` (Windows), or `proxy` (Linux systemd user unit) | Click **Refresh** to re-check the service status. #### Discovery and network | Field | Requires service restart | Description | | ---------- | ------------------------ | ---------------------------------------------- | | Network ID | No (applied via API) | Network to connect to | | Hops | No (applied via API) | Number of hops per circuit (default 3) | | SOCKS port | No (applied via API) | Local port the proxy listens on (default 1080) | Discovery itself is configured during installation and only re-exposed in developer mode. Fields marked "via API" are applied through the proxy's HTTP control API without restarting the service. #### Actions | Action | Description | | --------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | Restart Service | Stop and restart the background service | | Reset to Setup Wizard | Re-run the wizard without removing the binary or service; the wizard detects the existing installation and skips completed steps | | Uninstall Proxy | Remove the binary and service registration, then return to the setup wizard | *** ### Status bar A persistent bar at the bottom of every screen shows the state of both status layers at a glance. * **Service indicator (left side):** the OS-level service process. Click **Stop** to stop it, or **Start** when it is stopped. * **Proxy indicator (right side):** the SOCKS5 proxy itself, toggled through the HTTP API. Click **Stop** to disable, or **Start** to enable. Both indicators must be green for traffic to route through SpaceRouter Onion. A running service with a stopped proxy (or vice versa) does not forward traffic. | Indicator | Meaning | | --------------- | ------------------------------------------------------------------------------------ | | Service running | Background service is active. Click **Stop** to stop it. | | Service stopped | Background service is not running. The proxy cannot function without it. | | Proxy on | Traffic is actively routed through the mesh. Click **Stop** to disable. | | Proxy off | Proxy is inactive. Traffic goes directly to the internet. Click **Start** to enable. | The version line shows the installed binary version, the implementation (Go or Rust), and the discovery method. The *service* and the *proxy* are two separate things. The service is the background process that keeps the proxy available. The proxy is the active routing circuit. Both must be running for **Privacy enabled** to appear. *** ### Chrome Extension The **Chrome Extension Required** notice on the Proxy tab is expected. The SpaceRouter Onion Chrome Extension is needed to configure your browser to route traffic through the local SOCKS proxy and to control the proxy connection from your browser. Install it from the [Chrome Web Store](https://chromewebstore.google.com/detail/spacerouter-onion-extensi/dmofgbiaagkmblmpmjponfkinnnajfng) to activate the full privacy workflow. See SpaceRouter Onion extension for the full reference. *** ### Appendix A: Service management The app manages the `proxy` binary as a background service so the proxy can run independently of the desktop window. The service starts on user login and survives app restarts. #### macOS The app writes a launchd property list to: ``` ~/Library/LaunchAgents/com.spacerouter.proxy.plist ``` The service label is `com.spacerouter.proxy`. The app uses `launchctl` to load, start, stop, and unload the service. Service status is checked with `launchctl list`. Installing and uninstalling the service triggers a macOS password prompt because `launchctl bootstrap` and `launchctl bootout` require authorization. #### Windows The app registers a Windows Service named `SpaceRouterProxy` using `sc.exe`. Service status is checked with `sc query SpaceRouterProxy`. Installing and uninstalling the service triggers a UAC elevation prompt. #### Linux The app installs a `systemd --user` unit named `proxy`. Service status is checked with `systemctl --user status proxy`. Installing and uninstalling the unit do not require elevation because the unit is scoped to the current user. All other operations (starting and stopping the proxy, changing preferences, downloading binaries, checking status) run without elevation on every platform. *** ### Appendix B: Binary install paths | Platform | Install path | | -------- | ----------------------------------------------------- | | macOS | `~/Library/Application Support/SpaceRouter/bin/proxy` | | Windows | `%APPDATA%\SpaceRouter\bin\proxy.exe` | | Linux | `~/.local/share/SpaceRouter/bin/proxy` | The setup wizard downloads the binary to these paths. The service configuration references the binary at its install path. Moving or renaming the binary breaks the service; use **Uninstall Proxy** in settings and re-run the wizard instead. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.spacecoin.org/spacerouter-onion/app.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.