Skip to main content
Every machine gets a public HTTPS certificate, and public certificates are listed in public logs. Crawlers read those logs and probe every hostname they find. Without protection, each probe would wake a machine that was sleeping just to answer a bot. Bot protection stops that. When a request would wake a sleeping machine, boxd first asks the visitor to pass a quick browser check. A real browser gets through in a second or two and the machine wakes as usual. A crawler doesn’t, and the machine stays asleep. On by default for every machine.

​
What visitors see

A visitor who hits a sleeping machine sees a short “This machine is asleep” page with a Cloudflare Turnstile check. Most of the time the check passes on its own without the visitor clicking anything. Once it passes, the page reloads, the machine wakes, and your app answers the request. A passed check lasts 24 hours in that browser, for every machine on the same domain. Visiting another sleeping machine under boxd.sh in that time doesn’t ask again.

​
When the check applies

The check only runs when all of these are true:
  • The machine is asleep (in standby or hibernated). A running machine is never checked, since there’s nothing to wake.
  • The request is for the machine’s main address, myvm.boxd.sh or www.myvm.boxd.sh. If your org has a wildcard domain, myvm.vms.mysaas.com and www.myvm.vms.mysaas.com are covered too.
  • Bot protection is on for the machine.
These are never checked:
  • Named proxies such as api.myvm.boxd.sh.
  • Custom domains pointed at a single machine.
  • Traffic over your org’s Tailscale network. Only your tailnet can reach it, so bot protection is off there whatever the machine’s setting.
  • SSH. It already requires your key, so it wakes machines as before.
The browser remembers a passed check with a boxd cookie. boxd removes that cookie before the request reaches your app, so your app never sees it.

​
Webhooks and API clients

Only a browser can pass the check. A webhook sender, API client, curl or uptime monitor that hits a sleeping machine gets the check page with a 503 instead of your app, and the machine doesn’t wake. If a machine needs to be woken by something other than a browser, either turn bot protection off for it, or send that traffic to a named proxy (for example hooks.myvm.boxd.sh), which is never checked.

​
Turning it off or on

In the console, it’s the Bot protection switch on the machine’s Settings tab. From inside a machine, the in-VM boxd takes the same machine config set <name> bot-protection off command. Forks keep the setting of the machine they came from, and a machine restored from a snapshot keeps the setting the snapshot was taken with.