Local vs cloud

Understand cloud execution versus running a pentest on your own machine with --local, including requirements, tool execution modes and the doctor/env workflow.

The CLI can run a pentest in two places. Cloud is the default: the Rank backend executes the agents and their tools on its own infrastructure. Local (--local) flips this: the pentest engine runs on your machine, and the Rank backend is used only to authenticate the model calls and record the operations. Local mode exists to remove the main constraint of the cloud flow — you can bring your own tools without waiting for them to be available on the server.

rank pentest run 42            # cloud: tools run on Rank's servers
rank pentest run 42 --local    # local: tools run on your machine

The --cloud flag is the explicit form of the default, and is mutually exclusive with --local.

When to use each

Use cloud when…	Use local when…
You want zero local setup.	You need tools that aren’t in the cloud catalog.
The standard tool catalog covers your needs.	You want full control over the binaries and their versions.
You’re running automatic mode end-to-end.	You’re iterating on custom local tools and MCPs.
You don’t want to install scanners locally.	The target is only reachable from your network.

Requirements for local mode

Local execution only supports guided pentests driven by your own agents. Running --local on an automatic pentest is rejected, with a hint to recreate it in guided mode:

rank pentest create -n "Demo local" -u https://example.com -m guided

Before the run, your agents need locally runnable tools assigned, and the binaries those tools call must be installed. The CLI checks the pentest’s mode before starting a local run and stops early if it isn’t guided.

Tool execution modes

Whether a tool can run locally is determined by its execution_mode:

`execution_mode`	Runs in cloud	Runs locally
`local`	no	yes (your own tools)
`cloud`	yes (official catalog)	no
`both`	yes	yes — when it carries a `command` template

In practice, a tool is locally runnable when its execution_mode is not cloud and it has a non-empty command. You can filter an agent’s tools to just those with rank tools list <agentId> --local. Tools you create with rank tools create are local by default; the example catalog (rank tools example) gives you ready-made templates to start from.

How env and doctor fit in

Two commands support the local flow:

rank env registers the API keys your local tools need (for example SHODAN_API_KEY). They are injected automatically into any tool that declares the key in requires_api_key, so the agent never has to ask for them.
rank doctor verifies that the binaries your local tools invoke (nmap, nuclei, gobuster, …) are installed, and prints the right install command for your OS when they aren’t. Scope it to a pentest with rank doctor --pentest <id> to check only the tools assigned to that pentest.

A complete local run

Create a guided pentest.

rank pentest create -n "ACME local" -u https://acme.test -m guided

Find phase-1 agents and assign them.

rank agents list --type pentest --phase 1
rank pentest assign 2 --agents 12 18 --phase 1

Register any API keys your local tools need.

rank env set SHODAN_API_KEY=abcdef123

Check the required binaries are installed.

rank doctor --pentest 2

Run the pentest on your machine.

rank pentest run 2 --local

For CI or containers without a TTY, add --no-tui to get flat output. To dig into the binary checks, continue to Doctor; for token and key setup, see Authentication & config.