Drıftstack docs
Docs

Add your proxy and test it

Every Driftstack session goes out through a proxy or VPN that you bring. Driftstack has no connection of its own to run a session on, so a session started without one is refused before anything is created (422, code proxy_required). Add one proxy first, test it, then start your first session.

Driftstack does not sell or recommend a proxy provider. Any provider whose proxy meets the three points below can work.

What kind of proxy works

  • The right type. On the free trial, a SOCKS5 proxy. Paid plans can also use an OpenVPN or WireGuard connection. An HTTP proxy can be saved but cannot run a session (an https:// address cannot either); many providers offer SOCKS5 on another port of the same proxy.
  • A public address. Not localhost or a private-network address such as 10.x.x.x or 192.168.x.x. Sessions run on Driftstack’s servers, not on your computer, so a proxy on your own machine or office network cannot be reached from them.
  • Username and password. A provider that only lets listed IP addresses connect (an IP allowlist) does not work, because sessions do not connect from your IP address. Ask your provider for a username and password instead.

Add it in the desktop app

  1. Open Proxies and press New proxy.
  2. Choose the Type: SOCKS5, or on a paid plan OpenVPN or WireGuard.
  3. For SOCKS5, give it a label and fill in Host, Port and, if your provider gave them, Username and Password. The quick-paste field fills all four from one host:port:user:pass line. For OpenVPN or WireGuard, paste the whole .ovpn or wg0.conf file, or upload it.
  4. Press Add proxy in the form. The proxy is saved to your account, and its password is never shown again.
  5. Choose the proxy for a profile in the profile’s Edit. Launching the profile then sends its session through that proxy.

Step by step, with what each message means: Add and save a SOCKS5 proxy and Add an OpenVPN or WireGuard proxy.

Add it from code

Save the proxy to your account with POST /v1/account/me/proxies. Saving and testing a proxy need a key with the account_owner scope (Full access on the dashboard’s API keys page); a read + write key gets 403:

curl -X POST https://api.driftstack.dev/v1/account/me/proxies \
  -H "Authorization: Bearer $DRIFTSTACK_OWNER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "my proxy",
    "scheme": "socks5",
    "host": "proxy.example.com",
    "port": 1080,
    "username": "user",
    "password": "your-proxy-password"
  }'

The answer (201) is the saved proxy without its password. Keep its id: you pass it as proxy_id when you create an agent session, or you bind it to a profile.

Test it before your first session

A test answers one question: would a session through this proxy work right now?

  • In the desktop app, press Test on the proxy’s row (Check VPN for an OpenVPN or WireGuard proxy). The result that predicts a session is the one measured by Driftstack, not the one measured from your computer.
  • From code, call POST /v1/account/me/proxies/{id}/test. A working proxy answers { "ok": true, "latency_ms": … }. A proxy that fails answers "ok": false with a reason written for a person to read and act on, such as a wrong host or port, or a proxy that connected but could not reach the internet.

If the test passes but a session still cannot connect, or the proxy works from your computer and fails from Driftstack, see Proxy works on my computer but fails from Driftstack. What the quick and the full check measure, and how many you can run, is in Proxy test: quick check vs full check.