Routing rules

Routing rules tell the Aluvia client how to route each request based on hostname rules that you (or your agent) set. Rules can be updated at runtime without restarting the agent.

Traffic can be sent either:

• directly (using the agent's datacenter/cloud IP), or
• through Aluvia's mobile proxy IPs

Benefits

Cost savings

Selectively routing traffic to mobile proxies reduces proxy costs.

Reduced latency

Proxied connections inherently add latency. Selectively proxying some requests while sending others direct reduces the overall latency of a session.

Dynamic unblocking

With routing rules, your agent can unblock itself. When a request fails with a 403 or 429, your agent adds that hostname to its routing rules and retries. The update takes effect immediately—no restart, no redeployment, no lost state.

---

Set routing rules with Aluvia client

Rules can be updated during runtime, allowing agents to work around website blocks on the fly.

await client.updateRules(['blocked-site.com']);    // Add a hostname to proxy rules

Example:

import { AluviaClient } from '@aluvia/aluvia-node';

const client = new AluviaClient({ token: process.env.ALV_USER_TOKEN! });
const session = await client.start();

await client.updateRules(['*', '-example.com']);

// Your tool points at session.url / session.getUrl().
// The local proxy will now proxy everything except example.com.

await session.close();

Supported patterns

• *: match any hostname
• example.com: exact match
• *.example.com: match subdomains (e.g., foo.example.com, a.b.example.com; does not match example.com)
• google.*: match TLD variations (e.g., google.com, google.co.uk)

Negative rules (exclusions)

Prefix a pattern with - to exclude it:

• ['*', '-example.com'] proxies everything except example.com

Negative rules always win: if a hostname matches any exclusion, it will be routed direct.

Practical rule sets (examples)

• ['example.com'] proxies only example.com
• ['*.example.com'] proxies subdomains like api.example.com, but not example.com
• ['*'] proxies everything
• ['*', '-example.com'] proxies everything except example.com

Rule precedence

Rules are evaluated in order. Later rules can override earlier ones:

1. Start with a base rule (*, AUTO, or specific domains)
2. Add exclusions with - prefix

Example evaluation for ["*", "-example.com"]:

Request to	Rule matched	Result
api.stripe.com	*	Proxied
example.com	-example.com	Direct
sub.example.com	-example.com	Direct

---