Block domains on an instance

A blocklist names the domains an instance must not reach. Use it to keep an agent that drives the device inside the app under test, for example away from social networks. A blocked domain does not resolve on the device, so Safari, Chrome, WebViews, and apps fail to find the server before any connection opens.

You can set the blocklist when you create an instance and change it while the instance runs. Both need lim 0.53.0 or later, or @limrun/api 0.70.0 or later.

Block domains when you create an instance

Pass each domain with --blocked-domain, or list them in blockedDomains in the create request. This example blocks facebook.com and all of its subdomains:

lim ios create --blocked-domain facebook.com --blocked-domain '*.facebook.com'
lim android create --blocked-domain facebook.com --blocked-domain '*.facebook.com'

import Limrun from '@limrun/api';

const lim = new Limrun({ apiKey: process.env['LIM_API_KEY'] });

const blockedDomains = ['facebook.com', '*.facebook.com'];
const ios = await lim.iosInstances.create({ wait: true, spec: { blockedDomains } });
const android = await lim.androidInstances.create({ wait: true, spec: { blockedDomains } });

curl -X POST "https://api.limrun.com/v1/ios_instances?wait=true" \
  -H "Authorization: Bearer $LIM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "spec": { "blockedDomains": ["facebook.com", "*.facebook.com"] } }'

curl -X POST "https://api.limrun.com/v1/android_instances?wait=true" \
  -H "Authorization: Bearer $LIM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "spec": { "blockedDomains": ["facebook.com", "*.facebook.com"] } }'

The instance becomes ready only after the device enforces the blocklist, so the first page an app or browser opens is already blocked. Opening https://www.facebook.com then fails with "Safari can't open the page because the server can't be found" on iOS, and with DNS_PROBE_FINISHED_NXDOMAIN in Chrome on Android.

The Python and Go SDKs do not expose blockedDomains; send the REST request from those languages. Apple Watch simulators do not support a blocklist, so creating one with blockedDomains fails.

Change the blocklist on a running instance

The CLI changes the blocklist one entry at a time:

# Block more domains
lim ios blocklist add instagram.com '*.instagram.com'

# Unblock one entry; *.instagram.com stays blocked
lim ios blocklist remove instagram.com

# Show the blocklist
lim ios blocklist list

# Unblock everything
lim ios blocklist clear

// Block more domains
const blocked = await client.getBlockedDomains();
await client.setBlockedDomains([...blocked, 'instagram.com', '*.instagram.com']);

// Unblock everything
await client.setBlockedDomains([]);

lim android blocklist takes the same subcommands. Each command acts on the instance you created last; pass --id to change another one.

In TypeScript, setBlockedDomains replaces the whole blocklist, so read the current one with getBlockedDomains before you add to it. client is the instance client from createInstanceClient; see Run a simulator and Run an emulator.

A change applies to new lookups at once. Connections that an app already holds stay open until the app reconnects, so relaunch an app after you block a site it has open. On Android, the device can also keep answering a newly blocked name from its own DNS cache until that answer expires.

Choose what to block

Each entry is a domain name in one of two forms:

• An exact name, such as facebook.com, blocks only that name.
• A *. wildcard, such as *.facebook.com, blocks every subdomain at any depth (www.facebook.com, m.facebook.com) but not facebook.com itself.

To block a whole site, add both facebook.com and *.facebook.com. Quote wildcards on the command line so that your shell does not expand them. Tunnel domain selectors follow the same rules, and when a blocked name is also a tunnel selector, the block wins: the name does not resolve, and the tunnel never carries it.

A blocklist holds at most 256 entries. An entry cannot be a URL, an IP address, a name with a port, or an international name, and the error for each says what to send instead. Blocking works on whole names, so you cannot block one path of a site, such as facebook.com/groups, and leave the rest reachable.

Know the limits of blocking

Blocking acts on name lookups, so it stops browsers and apps that resolve names through the device. These still reach a blocked site:

• Apps that resolve names themselves over HTTPS (DoH) instead of through the device.
• Requests to an IP address, such as a link to https://203.0.113.10/.

Treat the blocklist as a guard for the device's browsers and well-behaved apps, not as a firewall against an app that sets out to avoid it.