Proxy Management

Proxies attach per-client. Add / remove from the global pool, then redistribute across spawned clients with distributeProxies(limit). Default kind is SOCKS5 — keys are either "ip:port" (no auth) or "ip:port:user:pass" (with auth).

addProxy("ip:port")                       -- no auth
addProxy("ip:port:user:pass")             -- with auth
removeProxy("ip:port")
getProxies()
distributeProxies(3)                      -- redistribute, max 3 clients per proxy

Proxy shape

getProxies() returns a 1-indexed list of these. Read-only from Lua's perspective; use setProxyEnabled / setProxyMaxBots to mutate.

Field	Type	Notes
key	string	Lookup key. Same shape as the string passed to addProxy() — 4-segment when auth is set, 2-segment otherwise.
info	ProxyInfo	Endpoint half (ip / port / user). Pull info.user to display without exposing the password.
pass	string?	Auth password. nil for unauthenticated proxies. Don't log this — it round-trips through the Lua API in plaintext.
enabled	boolean	Whether the registry will route bots through this proxy.
maxBots	number	Max bots that can claim this proxy at once. 0 = unbounded.
max_bots	number	Snake-case alias of maxBots. Both expose the same value.

ProxyInfo shape

The info field of a Proxy — host/port/user pulled out so they can be inspected without bringing the password along.

Field	Type	Notes
ip	string	Hostname or IPv4 address of the proxy server.
port	number	TCP port. SOCKS5 default is 1080.
user	string?	Auth username. nil for unauthenticated proxies.

Globals

addProxy(key)

Field	Type
Signature	(key: string) → boolean
Returns	true on success
Common errors	raises on a malformed key ("expected 'ip:port' or 'ip:port:user:pass'", "invalid port")
Async	no

Defaults the kind to SOCKS5.

addProxy("1.2.3.4:1080")
addProxy("1.2.3.4:1080:alice:hunter2")

removeProxy(key)

Field	Type
Signature	(key: string) → boolean
Returns	boolean — true if the key matched an existing entry, false otherwise
Common errors	raises on a malformed key
Async	no

removeProxy("1.2.3.4:1080:alice:hunter2")

getProxies()

Field	Type
Signature	() → {Proxy}
Returns	{Proxy} — 1-indexed list of every registered proxy
Async	no

for i, proxy in ipairs(getProxies()) do
    print(proxy.key, proxy.enabled, proxy.maxBots)
    print("  ", proxy.info.ip, proxy.info.port, proxy.info.user)
end

distributeProxies(limit)

Field	Type
Signature	(limit: number) → number
Returns	number — count of bots that got assigned a proxy
Async	yes — yields while reading the bot list and updating per-bot proxy assignments

Round-robins every enabled proxy across the bot list, honoring limit as the per-proxy bot cap (also persisted onto each proxy's maxBots field). Pass 0 to clear every bot's proxy and zero the caps.

local n = distributeProxies(3)
print("assigned", n, "bots")

setProxyEnabled(key, enabled)

Field	Type
Signature	(key: string, enabled: boolean) → boolean
Returns	boolean — true if the key matched an existing entry, false otherwise
Common errors	raises on a malformed key
Async	no

Toggle whether the registry routes bots through key.

setProxyEnabled("1.2.3.4:1080", false)  -- disable without removing

setProxyMaxBots(key, n)

Field	Type
Signature	(key: string, n: number) → boolean
Returns	boolean — true if the key matched an existing entry, false otherwise
Common errors	raises on a malformed key
Async	no

Set the per-proxy bot cap on key.

setProxyMaxBots("1.2.3.4:1080:alice:hunter2", 5)  -- cap to 5 clients on this proxy

Iterate the live pool

for i, proxy in pairs(getProxies()) do
  proxy.key             -- "ip:port" or "ip:port:user:pass"
  proxy.info.ip
  proxy.info.port
  proxy.info.user
  proxy.pass
  proxy.enabled         -- skipped during distribution when false
  proxy.maxBots         -- per-proxy cap (0 = unlimited)
end