The fleet

graphdom runtime run runs one spider once, on your machine. The fleet runs many spiders, many times, on many accounts, on a cluster you own. Nothing leaves your network: the sites are reached from your workers, secrets come from your vault, and every run is archived in your object storage.

A run in the fleet has no model in it. It runs an approved spider, so the cost of scale is browser time, and two runs with the same inputs on the same site do the same thing.

The parts

You run two processes, both from the same image:

Process	Command	What it does
Control plane	graphdom fleet serve	Holds sites, accounts, spiders and their versions. Queues jobs and decides which job runs next, on which account. Serves the API and /metrics. One process, with its state in its database.
Worker	graphdom fleet worker	Asks the control plane for work, runs each job in its own Chrome, and reports back. Stateless: add workers to run more at once.

The workers use two things you provide:

• A vault, the secrets runs need, such as passwords and TOTP seeds. Today it is a JSON file each worker reads. The control plane only ever holds the secrets’ names.
• Object storage for the archive of every run: the session the run recorded, redacted. An S3-compatible bucket, or a directory on a single machine.

Workers only dial out. They poll the control plane for jobs, and they reach the sites through each site’s proxy when it has one. The one inbound connection is a hand-over: the control plane connects to a worker to show an operator the live browser.

The life of a job

1. A version is added. An admin sends the spider version to the control plane. A version is named by the hash of its spider IR.
2. It is tested. The workers run it in the sandbox against the task’s recorded sessions, with the network cut. The report is attached to the version.
3. It is approved. An approver approves the version. Approval is refused without a passing report.
4. Jobs are queued. Each job names a spider, its inputs and, for a spider that logs in, an account.
5. The scheduler starts it when the site’s limits, time windows and the account allow. A queued job always says why it is waiting.
6. A worker runs it in a fresh Chrome, with secrets read from its vault at the moment a step needs them.
7. The run ends with its outputs, its archived session, and one of four outcomes: ok, drift, error or aborted.

What the fleet does for you

It respects the site. Each site has a maximum of runs at once, a minimum interval between two starts, and time windows. More workers never mean more load than the site’s configuration allows.

It respects the account. A portal often ends your first session when you log in a second time. By default an account has one live session, across every spider that uses it. A site can allow several independent sessions per account, or runs that share one session. See Sites and accounts.

It never sends a submit twice. A run that fails before its first submit step is retried, up to two attempts. A run that may already have submitted is never retried: it ends failed, marked submitted, for a person to check.

It asks a person when it should. The first real run of a new version stops before each submit step until an operator confirms it. A CAPTCHA, new terms of service, or any page the spider has a stop rule for is handed over too. The operator sees the live browser, can type into it, and then resumes or aborts the run. The fleet never solves a CAPTCHA.

It stops when the site changes. A run that meets a page its spider does not know reports drift at the step where it happened, instead of guessing. When two runs of a version report drift at the same step, the fleet opens an incident and holds that spider’s jobs, so no more runs go to a site that changed. Approving a repaired version releases them, and its first successful run closes the incident.

Current limits

The fleet is tested end to end, with several workers, spiders and accounts, a hand-over and a drift incident. Some parts are not built yet:

• There is no console. Studio does not show the fleet yet; you use the API.
• Spider versions arrive through the API only. graphdom fleet publish and loading a spiders/ directory are planned.
• The API is plain HTTP with static bearer tokens, each acting as a user declared in the tokens file or added by an admin. There is no login yet. Put TLS in front of the control plane.
• The vault is a JSON file protected by its file permissions.
• The control plane is one process with a local database, so it runs as a single replica.
• Every run starts with a fresh browser profile. A persistent profile per account is not built.

Next: deploy the fleet, then operate it.