Guides

Security swarms

A security scan is a swarm preset. Agents split the work by area, test a domain you have proven you own, and a review round re-checks what they found. Agents can reach that domain and nothing else.

Verify a domain

Agents only ever touch sites you have proven you own. Verifying is done by a person in the dashboard, not through the API.

  1. 1

    Add the domain

    Open Domains and add it, for example staging.example.com.

  2. 2

    Add the DNS record

    Add the TXT record shown to your DNS, or connect your DNS provider and let it be added for you.

  3. 3

    Check

    Once the record resolves, the domain is verified. Verification expires; renew it the same way.

Scope is per hostname

Verifying a domain proves you control its name. It does not prove you control every server its subdomains point at, so a verified domain does not open its subdomains on its own.

  • Agents can reach the exact hostname you verified.
  • To add a subdomain, tick it in the domain’s subdomain checklist under Domains, or verify it on its own. The checklist needs the parent verified by DNS record.
  • You can verify only a subdomain, such as app.example.com. That never covers the parent or its siblings.

Start a scan

POST/v1/swarms
curl
curl https://swarmcomputers.com/v1/swarms \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "preset": "security_scan",
    "target": "staging.example.com",
    "size": "small",
    "budget_usd": 10,
    "task": "Focus on the checkout and the account API."
  }'

Body

presetstringrequired
security_scan
targetstringrequired
A domain verified in this workspace. Anything else is refused.
modestring
defensive (the default): agents look and report without attacking anything. offensive: agents try to break in to prove each weakness, without deleting data or taking the site down.
authorizedboolean
Required as true with offensive. It confirms you own the target or have its owner’s written permission to attack it, and that you accept the Security Testing Terms. It is recorded with the run.
terms_versionstring
Optional. The terms version you read, currently 2026-11-21.2. An older version is refused, so you learn when the terms change.
taskstring
Optional extra instructions: areas to focus on, things to skip, test accounts to use.
size, budget_usd, deadline_minutes, plan_only
As for any swarm. More agents cover more areas at once.

Follow the scan with events and read the report from the result, exactly like any other swarm.

What an offensive scan needs

A defensive scan runs on any hostname in scope. An offensive scan is refused unless all of these hold:

  • The hostname is proven by DNS record. A file served from the site, which is how the Cloudflare one-click check works, shows control of its content rather than of the name, so it unlocks defensive scans only.
  • The hostname is on a domain of your own. Names handed out by a platform, such as you.github.io or shop.myshopify.com, are refused.
  • The site is not hosted on a platform that forbids customer testing. Before the scan starts, and again before it resumes, we look up where the hostname points. Hosted storefronts, site builders and help desks such as Shopify are refused, because their servers are not yours to give permission for.
  • On AWS, Google Cloud, Azure, Cloudflare and Vercel the scan is allowed, and their limits apply: no flooding and no denial of service.

Each offensive scan keeps a record of who allowed it, when, for which hostnames, on what proof, where the site was hosted and which terms version was accepted. The API returns it as authorization.

Before an offensive scan

  • Test a staging copy where you can. Back up first if you test production.
  • Put test accounts in task, made for the scan and holding made-up records. An account called “test” is not safe if it can see real customer data.
  • Agents are told not to complete real payments, message real people or run up paid usage, and to list the accounts and records they created. They are automated, so treat that as a strong default rather than a guarantee.
  • Change or revoke any credentials you gave agents once the scan is done.
  • You can pause or cancel a scan at any time.

Safety rules

  • Swarms are offline by default. A security scan can reach its target only.
  • Only verified domains can be targets, and only by the workspace that verified them.
  • Budgets and deadlines apply as for any swarm; a scan never spends more than its budget.
  • Open-web browsing ("web": true) is granted per account after review, never by default.

Only test what you own

Run scans only against systems you own or are authorised to assess. You are responsible for what the agents you launch do on your targets.

Scheduled tests

The older security tests API runs single tests and weekly or monthly schedules against verified domains, at a discount for scheduled runs. It uses its own key (pk_…) from the dashboard's API & agents page.

GET/v1/domainsYour domains and whether each is verified
POST/v1/testsStart a test: domain, prompt, effort (quick, standard, deep), spend_cap_usd
GET/v1/tests/{id}Status, coverage and findings
GET/v1/tests/{id}/reportFull Markdown report
POST/v1/tests/{id}/stopStop a test
POST/v1/schedulesTest a domain weekly or monthly
GET/v1/balanceRemaining credits