Bot protection

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, and probes to a running machine would keep resetting its idle timer, so it would never go to sleep at all. Bot protection stops that. Before a request reaches the machine, boxd asks the visitor to pass a quick browser check. A real browser gets through in a second or two. A crawler doesn’t, so it never reaches your app.

Modes

Mode	When visitors are checked
On	Every HTTPS request, whether the machine is running or asleep. Crawlers can neither wake the machine nor keep it awake.
Sleep only	Only a request that would wake the machine from standby or hibernation. While the machine runs, every request goes straight through.
Off	Never. Any request reaches the machine, and wakes it.

Check which mode a machine has with boxd machine config get myapp bot-protection.

What visitors see

A visitor sees a short page with a Cloudflare Turnstile check: “One quick check” on a running machine, “This machine is asleep” on a sleeping one. Most of the time the check passes on its own without the visitor clicking anything. Once it passes, the page reloads and your app answers the request, after waking the machine if it was asleep. A passed check lasts 24 hours in that browser, for every machine on the same domain. Visiting another 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 request is for the machine’s main address, myapp.boxd.sh or www.myapp.boxd.sh. If your org has a wildcard domain, myapp.vms.mysaas.com and www.myapp.vms.mysaas.com are covered too.
The machine’s mode covers its state: On in any state, Sleep only when it is in standby or hibernated.
The browser hasn’t passed the check in the last 24 hours.

These are never checked:

Subdomain proxies such as api.myapp.boxd.sh.
Custom domains pointed at a single machine.
Traffic over your org’s Tailscale or NetBird network. Only that network 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 gets checked receives the check page with a 503 instead of your app. With On that happens on every request to the machine’s main address. With Sleep only it happens only while the machine is asleep, and the machine stays asleep. For a machine that something other than a browser must reach, send that traffic to a subdomain proxy (for example hooks.myapp.boxd.sh), which is never checked. Or choose Sleep only if those clients only need a running machine, or Off.

Set it for a machine

await boxd.machines.setBotProtection("myapp", "sleep_only");   // "on", "sleep_only" or "off"
(await boxd.machines.get("myapp")).botProtectionMode;           // "sleep_only"

boxd.machines.set_bot_protection("myapp", mode="sleep_only")   # "on", "sleep_only" or "off"
boxd.machines.get("myapp").bot_protection_mode                 # "sleep_only"

boxd machine config get myapp bot-protection              # on, sleep_only or off
boxd machine config set myapp bot-protection on           # checked running or asleep
boxd machine config set myapp bot-protection sleep_only   # checked only when a request would wake it
boxd machine config set myapp bot-protection off          # never checked

In the console, it’s the Bot protection menu on the machine’s Settings tab. Inside a machine, the in-machine CLI takes the same machine config set bot-protection <mode> command. The SDKs still accept true and false: true means On and false means Off. botProtection / bot_protection reads true for both On and Sleep only. A fork keeps the setting of its source machine, and a machine created from a snapshot keeps the setting the snapshot was taken with.

Org default

New machines start with your org’s default bot protection, if your org has one, and otherwise with the platform’s setting. Org admins set the default, and any member can read it. Setting the default also changes the existing machines you can manage: your own machines and the org’s shared machines. Machines with bot protection Off stay off, and other members’ private machines are left unchanged. To change only machines created from now on, use --new-only (in the SDKs, new_machines_only / newMachinesOnly).

boxd manage defaults get bot-protection                  # the org's default, or "unset" and the platform's setting
boxd manage defaults set bot-protection on               # new machines, and your existing machines too
boxd manage defaults set bot-protection on --new-only    # only machines created from now on
boxd manage defaults clear bot-protection                # back to the platform's setting; existing machines keep theirs

const r = await boxd.orgs.setBotProtectionDefault("acme", "on");   // { newMachinesOnly: true } to skip existing machines
r.machinesChanged, r.machinesOff, r.machinesSkipped;
const d = await boxd.orgs.getBotProtectionDefault("acme");
d.isSet, d.mode, d.platformMode;
await boxd.orgs.clearBotProtectionDefault("acme");

r = boxd.orgs.set_bot_protection_default("acme", mode="on")   # new_machines_only=True to skip existing machines
r.machines_changed, r.machines_off, r.machines_skipped
d = boxd.orgs.get_bot_protection_default("acme")
d.is_set, d.mode, d.platform_mode
boxd.orgs.clear_bot_protection_default("acme")

The CLI prints what changed, for example changed 3 existing machines; 1 machine with bot protection off was left off. Clearing the default never changes an existing machine. In the console, it’s the Default bot protection section on the Organization page. The menu sets the default for new machines, and Apply to existing machines then applies it to the existing machines you can manage. Platform setting in the menu means the org has no default of its own. A fork or a machine created from a snapshot keeps its source’s setting, whatever the org default.

Getting started

Guides

Integrations and automations

Use cases

References