Proxies
Stairway sends browser traffic through proxy exits. You add a proxy provider once (for example a Mullvad account or a set of WireGuard configs). Each provider makes one or more exits. You then pick an exit, or a circuit of exits, when you start a browser.
Where you manage them
Open Proxies next to Browsers in the header (/proxies). The page has three tabs:
| Tab | What it shows |
|---|---|
| Inventory | Every exit and circuit you can use, from all providers. Filter by search text, tags, provider, type, and country. |
| Providers | The providers you can see. Sync, add configs, edit, share, or delete them. |
| Circuits | Chains of 2–8 exits. Test, edit, share, or delete them. |
Provider types
| Type | What you give Stairway | Exits it makes |
|---|---|---|
| Mullvad account | A 16-digit account number, and optionally an existing device private key. If you leave the key blank, Stairway registers one new device key (Mullvad allows 5 devices). | One exit per active Mullvad WireGuard relay. Stairway syncs the relay list on a schedule. |
| WireGuard configs | Pasted text, .conf files, a folder, or a .zip (up to 500 configs). | One exit per config. Mullvad-style file names such as us-nyc-wg-301.conf set the country and city. |
| SOCKS / HTTP endpoints | One proxy URL per line, for example socks5://user:pass@host:1080. | One exit per line. |
| Residential provider | Account credentials for IPRoyal, Maskify, or IPCola. | One exit per location the vendor offers. Stairway syncs the list on a schedule. |
Passwords, account numbers, and WireGuard private keys are encrypted at rest. They never go into the browser container.
Tags
A provider has tags, for example residential, cellular, datacenter, or vpn. You can also type your own (lowercase letters, numbers, and hyphens, up to 32 characters, 16 per provider). Every exit gets the tags of its provider. A circuit has its own tags plus the tags of every hop's provider.
When you filter the inventory by more than one tag, Stairway shows only rows that have all of those tags.
Who can use a provider
| Visibility | Who can use it | Who can set it |
|---|---|---|
| Just me | The owner, plus people or teams the owner shares with | Anyone |
| Team | Members of the selected team | Team owners and admins |
| Everyone | All signed-in users | System admins |
Circuits use the same visibility and sharing rules.
When the platform has operator credentials (for example MULLVAD_ACCOUNT_NUMBER or IPRoyal keys), Stairway creates Platform … providers with visibility Everyone one time. After that, system admins manage them on the Providers tab like any other provider.
How browsers use an exit
Each browser gets its own stairway-proxy sidecar. When you pick a plain exit, the sidecar connects to that exit directly. When you pick a circuit, the sidecar connects to the circuit's shared proxy container over Docker DNS with listen authentication.
Before a sidecar or proxy container reports ready, it runs a self-test through the exit. A dead exit fails the start with an error instead of a browser with no network.
Test
Click Test on an exit or circuit to start its proxy container (if it is not running) and fetch a test page through it. The result shows the output, or the error and the last lines of the proxy log.
Host port
In an exit's or circuit's settings, enable Publish SOCKS on a host port to publish container 1080/tcp on a host port. Clients authenticate with the listen username and password.
Access WireGuard
Enable Access WireGuard overlay to attach a second interface (wg-access, UDP 51821). Each allowed user mints a peer. Client AllowedIPs is the overlay /24 only — this is not a full-tunnel VPN. After connecting, point SOCKS at the overlay gateway (10.x.y.1:1080) with listen auth. Peers are per user. Revoking a peer and restarting the overlay drops that client.
Circuits
A circuit chains 2–8 exits into a pproxy hop chain (hop1__hop2__…). Create it on the Circuits tab, build one inline on New browser (choose Circuit → New circuit), or click Add to circuit on an inventory row. Then pick it like any exit when you start a browser.
Each hop is reached through the previous hop's egress, so the order matters:
| Hop | Allowed | Why |
|---|---|---|
| 1st | Any exit | It is reached directly. A WireGuard/Mullvad exit runs as its own container, which the circuit reaches over the Docker network. |
| 2nd–last | SOCKS/HTTP endpoints, and residential exits only as the last hop | Later hops are reached through the previous hop's network, so they must be publicly reachable. Residential vendors block onward proxy connections, so a residential hop can only be final. |
The picker marks each hop with its role (Tunnel · first hop, Public, Residential · last hop) and refuses invalid orders. Traffic exits through the last hop.
This is Stairway's hop chain, not an L2 VXLAN mesh.
Locked for the session
Session egress is fixed for the lifetime of the browser. To change the exit or circuit, create a new browser. Proxy containers for circuits keep running until you delete the circuit or its provider.