Routing & location selection

By default the gateway picks an exit for you and rotates between matching exits on every new connection. To steer where you come out, append routing tags to your collar tag. Nothing else changes — same host, same port, same pawprint.

The shape of a username

Your collar tag (cat-XXXX-...) is the base. Append tags as -key-value pairs:

cat-J5K2M4Q7X9A3F6H8-country-us-isp-comcast-type-residential
└──── collar ────┘└──────────── routing tags ────────────────┘

The collar authenticates you; the tags select the exit. The pawprint never changes for a given life and scope (derive new ones in settings).

Keys

Valid values come from our live location catalog — browse there or pick them in the endpoint builder.

Picking a set (multiple choices)

Comma-separate values to allow any of them. The gateway rotates across every exit that matches:

# any US or German residential exit
...-country-us,de-type-residential

# Comcast or Verizon, US only
...-country-us-isp-comcast,verizon

A connection matches when every key you specified matches. If nothing matches, the connection is refused (fail closed).

Sticky vs. rotating

• Rotating (default) — each new connection may land on a different matching exit. Good for broad scraping. No session tag.
• Sticky — add session-<id> to pin one exit for as long as you reuse that id. The id is arbitrary; change it to jump to a new exit.
• Lifetime — optional -lifetime-<minutes> on a sticky session. This is how long the pin lasts, not the session id itself.

# rotating: fresh exit each call
curl -x socks5h://COLLAR-country-us:PAWPRINT@socks.cat:1337 https://api.ipify.org

# sticky: same US exit while you reuse "ab12"
curl -x socks5h://COLLAR-country-us-session-ab12:PAWPRINT@socks.cat:1337 https://api.ipify.org

# sticky for up to 30 minutes
curl -x socks5h://COLLAR-country-us-session-ab12-lifetime-30:PAWPRINT@socks.cat:1337 https://api.ipify.org

Replace COLLAR with your collar tag and PAWPRINT with your derived password.

Chain overrides

A chain-<name> tag selects an explicit multi-hop circuit and overrides country/city/isp tags for that connection:

curl -x socks5h://COLLAR-chain-eu-circuit:PAWPRINT@socks.cat:1337 https://api.ipify.org

Built-in dev/prod chains tor and i2p route clearnet exits through Tor or I2P (see Tor & I2P). Hidden-network destinations (.onion / .i2p) auto-prepend the right hop when [router].tor / [router].i2p are enabled.

A stored default

Set a default selection on your account page. It applies whenever your username carries no routing tags — and to IP-authenticated connections, which have no username to encode tags into.

A default of country-us-isp-comcast means a bare collar behaves like COLLAR-country-us-isp-comcast. Tags in the username always win for that connection.

Scoped pawprints

A pawprint can be bound to your builder selection — for example country-us-state-ut-type-residential on the dashboard. That scoped pawprint only verifies when the proxy username matches that route (same country/state/city/type/isp tags on your collar). Use scoped pawprints when handing credentials to a tool that should only reach one region; keep the full pawprint for yourself. Derive either kind in settings.

Cheat sheet

COLLAR                                  → default selection (or worldwide rotate)
COLLAR-country-de                       → any German exit
COLLAR-country-us-type-mobile           → US mobile exit
COLLAR-country-us,gb-session-x9         → sticky US-or-UK exit
COLLAR-isp-comcast-city-nyc             → Comcast in NYC
COLLAR-chain-eu-circuit                 → explicit chain
COLLAR-chain-tor                        → clearnet via Tor
COLLAR-chain-i2p                        → clearnet via I2P

See Residential setup and Mobile setup for endpoint-specific notes.