CLI reference

The bobby binary (Cargo package bobby-browser) is the primary way to run the runtime locally.

cargo build -p bobby-browser --release
./target/release/bobby --help
./target/release/bobby --version

With no subcommand, bobby defaults to serve.

Commands

bobby init

Generate a loopback bootstrap credential (dotenv file, mode 0600 where supported).

Prints the plaintext bearer once. Map it to AUTOMATION_RUNTIME_TOKEN for SDK clients. Never commit the bearer or put it in config.toml.

bobby serve

Start the authenticated HTTP broker (and MCP HTTP mount).

On loopback, if no bootstrap credential exists, serve may generate one and print the bearer once. Non-loopback binds require credentials up front.

Optional: AUTOMATION_RUNTIME_BROWSER_SELECTION (JSON) overrides engine selection. Without it, the selection persisted by bobby enroll-firefox-profile is used; default engine preference is Firefox. The same resolution order applies to the MCP gateway and bobby doctor — see Configuration.

Health: GET http://<host>:<port>/healthz.

bobby doctor

Local setup checks (config load, browser selection, engine satisfiability, bootstrap presence, storage dirs, Firefox/Chromium on PATH, optional /healthz).

Exit code 1 if any fail checks; warnings alone exit 0.

In an interactive terminal, ok, warn, and fail are green, yellow, and red. Repair results use cyan, green, yellow, or red according to outcome. Piped output and NO_COLOR=1 bobby doctor remain plain and keep the same text labels, so color is never required to understand a result.

--fix is conservative and idempotent. It can heal an existing unrestricted bootstrap capability set, normalize the selected provider into Bobby's canonical vision node, and readiness-test that selected provider. It does not choose a provider/model, overwrite a custom endpoint, persist secrets, install system packages, or leave a daemon running. A missing MLX cache remains an action item unless --download-model gives explicit consent for the download.

bobby jobs

HTTP client for the broker job API (/v1/jobs). The scheduler runs in-process inside `bobby serve` — the CLI does not start a second scheduler.

Bootstrap credentials need job:submit, job:read, and job:cancel. New bobby init / loopback serve credentials include these by default. Existing bootstrap.env files are not migrated; run bobby init --force (or enroll a principal with job:*) before using these commands.

bobby jobs submit --name echo --payload '{"message":"hi"}'
bobby jobs submit --name echo --payload-file ./job.json --priority high \
  --idempotency-key run-1
bobby jobs status <job_id>
bobby jobs cancel <job_id>

Shared flags on all jobs subcommands:

submit flags: --name (required), --payload (JSON string, default {}), --payload-file, --priority (low|normal|high|critical, default normal), --max-retries, --timeout-ms, --idempotency-key.

bobby vision

Vision provider setup. connect writes a provider profile into config.toml, login establishes or verifies the configured ACP harness login, and collect gathers training data from gauntlet runs.

bobby vision connect --yes --provider mlx
bobby vision connect --yes --provider mlx --activate --download-model
bobby vision connect --yes --backend acp --provider codex \
  --command codex --arg acp --auth advertised
bobby vision login

bobby install also offers vision configuration during onboarding. Field reference: Configuration.

An explicitly selected provider is persisted before a bounded readiness test. For MLX, Bobby loads the exact selected model through the same managed command used at runtime and stops the setup-time child after the probe. Ollama and LM Studio remain externally managed; onboarding reports how to start/load them when their configured endpoint is unavailable.

vision connect remains configuration-only by default. Add --activate to load/readiness-test the selection immediately. For MLX, add --download-model only when Bobby may download the selected model if its cache is missing; that flag requires --activate.

bobby vision status / bobby vision start

bobby vision status reports the configured provider/model and whether the local vision service is running. Bobby starts that service on demand during normal agent use. bobby vision start runs it in the foreground for manual inspection and debugging.

The former top-level vision-proxy command remains a hidden compatibility alias for scripts. New user workflows should use the bobby vision commands.

bobby vision detect / bobby vision solve

detect classifies a captcha or human-verification challenge on a page without acting on it; solve drives the vision solve loop against one until it clears or the budget runs out. Both take a --purpose and target either a fresh session (--url) or an existing one (--session with --page).

bobby vision detect --purpose "check for a captcha blocking signup" --url https://example.com
bobby vision solve --purpose "solve the reCAPTCHA challenge" --session <id> --page <id>

detect is read-only and defaults to a 15s budget (--timeout-ms); solve mutates the page and defaults to 120s. Add --zigzagzig to solve for humanized input timing and fingerprint spoofing. --node selects the vision node the session escalates to (default vision). Both require the session to hold vision:assist.

bobby openshell

NVIDIA OpenShell host: write the pack, and mint or revoke one agent-scoped principal per sandbox.

bobby install --host openshell writes the same pack, bobby init --emit openshell prints the MCP fragment, and bobby doctor reports openshell-pack and the related checks when a pack is present. See OpenShell.

Firefox companion

bobby firefox-native-host --descriptor /abs/path/descriptor.json
bobby install-firefox-native-host \
  --wrapper /abs/wrapper \
  --manifest /abs/manifest.json \
  --cli /abs/bobby \
  --descriptor /abs/descriptor.json
bobby enroll-firefox-profile \
  --descriptor /abs/descriptor.json \
  --bidi-url ws://127.0.0.1:9224/session \
  --profile-dir /abs/profile

See Firefox companion.

Environment

Next

• Run the server
• Configuration
• First browser session