Network proxies

Use a network proxy when a subscription account needs a specific outbound route to its provider. Proxies belong to one workspace and are separate from account pools, which control which accounts members may use. An account can have one proxy binding or use the instance's default network route.

Add a proxy

1. As a workspace administrator, open Administration → Network proxies and select Add proxy.
2. Enter a recognizable name and the full proxy URL. For example, http://proxy.example.test:8080 or socks5://user:pass@proxy.test:1080.
3. Save it. The list shows the name, protocol, host, port, and number of bound accounts. It never shows the username or password.

The URL must use http://, https://, or socks5:// and include an explicit host and port. Authentication, when used, needs both a username and password. Percent-encode reserved characters in credentials, such as @ as %40. Paths, queries, and fragments are not accepted. A workspace can hold up to 32 proxies.

Saving a proxy validates its URL but does not contact it. Use an account's Verify connection action after binding to check the actual route to the provider.

Import several proxies

Select Import proxies and paste one entry per line. A line can be a full URL, host:port (treated as HTTP), or Name | URL for a custom name. For example:

http://proxy-a.test:8080
Backup exit | socks5://user:pass@proxy-b.test:1080
proxy-c.test:8081

Without a custom name, SubLane uses the host and port and adds a suffix if needed. Blank lines are ignored. The whole batch is validated against the remaining 32-proxy workspace limit and saved in one transaction. If one entry is invalid or an explicit name is already used, nothing from that batch is imported. Imported credentials receive the same encryption and redaction as individually added proxies.

Test the exit and find its location

Select Test proxy on a proxy row. SubLane makes one bounded HTTPS request through that proxy to IPinfo's public IP endpoint. A successful response records the observed exit IP, country/region/city when supplied, response time, and check time. It is a lookup of the network exit, not the proxy server's physical address; IP geolocation is approximate. Tests run only when an administrator asks for one.

Select Test all proxies to check every saved proxy with one action. Up to four checks run at a time, and a failed check does not stop the remaining checks. The page shows progress and a summary of connected proxies, connection failures, and other errors. This action makes one IPinfo request per proxy, so the public endpoint's shared limit also applies to a batch.

The public IPinfo endpoint has a shared daily limit. A lookup error or rate limit is shown separately from a connection failure and does not change the proxy binding. Editing the proxy URL clears its old check result. A check against IPinfo does not prove the subscription provider is reachable; bind the account and use Verify connection for that.

Bind an account

• New account: Create the proxy first, then choose it under Network proxy in Accounts → Add account before browser authorization or JSON import. Choose Default network route to leave the account unbound.
• Existing account: In Accounts, open the account's actions, choose Network proxy, select a proxy, and save. The card shows the bound proxy's name. Reauthorization keeps the account's current binding.

The binding covers SubLane's server-side OAuth token exchange, credential refresh, model discovery, quota reads where supported, and model traffic. The provider's browser sign-in page opens in your browser and does not use SubLane's proxy. Imported proxy_url fields are ignored; only a proxy configured by a workspace administrator can become a binding.

Each new request uses the account's current binding. Changing a proxy URL or account binding does not move an active stream or replay a request. It also does not change the conversation's selected subscription account. SubLane does not rotate proxies per request or automatically fail over to another proxy. An unbound account continues to use the instance's default outbound transport, including proxy environment variables if the process has them configured.

Change or remove a proxy

In Network proxies, select Edit proxy to rename it or replace its URL. Leave Proxy URL blank while editing to keep the saved address. A changed address takes effect for later requests from every account bound to that proxy and clears the previous exit check. To remove a proxy, first return each bound account to Default network route or bind it elsewhere; a proxy with bound accounts cannot be deleted.

The row's test, edit, and delete actions use icons with descriptive tooltips. Delete failed proxies opens a confirmation and removes unbound proxies whose most recent check reported a connection failure within the last 30 minutes. It does not remove bound, untested, or location-lookup-error proxies. The server applies these conditions again when you confirm, so the number removed can differ from the count displayed before confirmation.

If an account is cooling down after a failed route, open its Scheduling settings, clear the cooldown with Resume account, then run Verify connection. If the account instead says Reauthorization required, reauthorize it; changing the proxy alone does not replace its credentials. For a container deployment, 127.0.0.1 in a proxy URL refers to the container itself, so use an address reachable from the SubLane process.

Security and API

Proxy URLs are encrypted in SQLite with the instance vault key. Back up the database and key together. Management endpoints require an enabled administrator session and same-origin checks for writes. Proxy list responses expose only the endpoint and the latest check result, never credentials. A manual check shares the proxy's public exit IP with IPinfo; no location request runs in the background. Successful changes are audited: individual proxies and account bindings use resource IDs, while batch import and failed-proxy deletion each create one event without item IDs. Raw URLs and passwords are never audit fields. See management audit.

POST /api/accounts/import and POST /api/accounts/oauth also accept an optional proxy_id when creating an account. Invalid URLs or import lines return HTTP 400; missing or cross-workspace proxies return 404; duplicate names, the workspace limit, deletion of a bound proxy, and a check superseded by an edit return 409.

Automated routing checks use synthetic proxies, including an HTTPS CONNECT tunnel. They do not establish that a particular proxy or live provider account works in your deployment; confirm it with Verify connection.