---
title: "Domain blocklist"
description: "Keep the apps and browser on an iOS simulator or Android emulator away from domains you block, from creation or while the instance runs."
canonical_url: "https://docs.limrun.com/docs/networking/domain-blocklist"
markdown_url: "https://docs.limrun.com/docs/networking/domain-blocklist.md"
last_updated: "2026-11-14"
x_farming_labs_generated_preamble: true
---

# Domain blocklist
URL: /docs/networking/domain-blocklist
LLM index: /llms.txt
Description: Keep the apps and browser on an iOS simulator or Android emulator away from domains you block, from creation or while the instance runs.

# 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:

<CodeGroup labels={["CLI","TypeScript","cURL"]}>
```bash
lim ios create --blocked-domain facebook.com --blocked-domain '*.facebook.com'
lim android create --blocked-domain facebook.com --blocked-domain '*.facebook.com'
```

```ts
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 } });
```

```bash
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"] } }'
```
</CodeGroup>

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:

<CodeGroup labels={["CLI","TypeScript"]}>
```bash
# 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
```

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

// Unblock everything
await client.setBlockedDomains([]);
```
</CodeGroup>

`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](/docs/ios/run-simulator) and [Run an emulator](/docs/android/run-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](/docs/networking/private-tunnels#choose-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.

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.
Docs-scoped sitemap: [/docs/sitemap.md](/docs/sitemap.md).
Well-known sitemap: [/.well-known/sitemap.md](/.well-known/sitemap.md).