Skip to content

workers.dev

Last updated View as MarkdownAgent setup

Cloudflare Workers accounts come with a workers.dev subdomain that is configurable in the Cloudflare dashboard. Your workers.dev subdomain allows you getting started quickly by deploying Workers without first onboarding your custom domain to Cloudflare.

It's recommended to run production Workers on a Workers route or custom domain, rather than on your workers.dev subdomain. Your workers.dev subdomain is treated as a Free website ↗︎ and is intended for personal or hobby projects that aren't business-critical.

Configure workers.dev

workers.dev subdomains take the format: <YOUR_ACCOUNT_SUBDOMAIN>.workers.dev. To change your workers.dev subdomain:

  1. In the Cloudflare dashboard, go to the Workers & Pages page.

    Go to Workers & Pages ↗
  2. Select Change next to Your subdomain.

All Workers are assigned a workers.dev route when they are created or renamed following the syntax <YOUR_WORKER_NAME>.<YOUR_SUBDOMAIN>.workers.dev. The name field in your Worker configuration is used as the subdomain for the deployed Worker.

Manage access to workers.dev

When enabled, your workers.dev URL is available publicly. You can use Cloudflare Access to require visitors to authenticate before accessing Version URLs, Preview URLs, and Deployment URLs. You can limit access to yourself, your teammates, your organization, or anyone else you specify in your access policy.

Access can protect one Worker's production workers.dev URL, preview URLs, or both. You can also protect all Workers or all Worker previews in an account.

To use details about the signed-in user in your Worker, use ctx.access. You can also read the user's identity from the validated JWT or the /cdn-cgi/access/get-identity endpoint.

Browser Integrity Check on workers.dev

All requests to a workers.dev hostname are evaluated by Browser Integrity Check (BIC) on the Cloudflare-managed workers.dev zone. This includes Preview URLs and Version URLs.

  • You cannot turn off this check for a workers.dev hostname.
  • Turning off BIC in your own zone, or adding a custom rule or configuration rule that skips or turns off BIC, only affects your zone. It does not affect the check on the workers.dev zone.
  • Automated clients that send some default library User-Agent headers (for example, the default Python urllib user agent) receive error 1010 before your Worker runs. These requests do not appear in your Worker logs.

To allow automated clients to reach your Worker:

  1. Recommended: Configure the client to send a descriptive User-Agent header that identifies your application. The client does not need to send a browser user agent. For example, in Python:

    import urllib.request
    
    req = urllib.request.Request(
        "https://example.com/data.json",
        headers={"User-Agent": "my-app/1.0 (+https://example.com)"},
    )
    urllib.request.urlopen(req)
  2. Serve your Worker on a Custom Domain or route in a zone you own. You can then create a configuration rule that turns off Browser Integrity Check, or a custom rule that skips it, for only the paths that need it.

Disabling workers.dev

Disabling workers.dev in the dashboard

To disable the workers.dev route for a Worker:

  1. In the Cloudflare dashboard, go to the Workers & Pages page.

    Go to Workers & Pages ↗
  2. In Overview, select your Worker.

  3. Go to Settings > Domains & Routes.

  4. On workers.dev click "Disable".

  5. Confirm you want to disable.

Disabling workers.dev in the Wrangler configuration file

To disable the workers.dev route for a Worker, include the following in your Worker's Wrangler configuration file:

{
	"workers_dev": false
}
workers_dev = false

When you redeploy your Worker with this change, the workers.dev route will be disabled. Disabling your workers.dev route does not disable Version URLs, Preview URLs, or Deployment URLs.

If you do not specify workers_dev = false but add a routes component to your Wrangler configuration file, the value of workers_dev will be inferred as false on the next deploy.

Limitations

When deploying a Worker with a workers.dev subdomain enabled, your Worker name must meet the following requirements:

  • Must be 63 characters or less
  • Must contain only alphanumeric characters (a-z, A-Z, 0-9) and dashes (-)
  • Cannot start or end with a dash (-)

These restrictions apply because the Worker name is used as a DNS label in your workers.dev URL. DNS labels have a maximum length of 63 characters and cannot begin or end with a dash.

Was this helpful?