Cloud doctor

foreman cloud doctor asks whether a machine is ready to run Foreman unattended. The container runner runs it first and refuses to start if a check fails; you can run it yourself on a runner, or on your laptop from the Set up tab’s Cloud runner step, which runs the checks that are safe there. This page lists every check, what it looks at and how to fix it. The laptop’s own foreman doctor is on Doctor checks; it gains three checks of its own once a cloud set-up exists, listed at the end.

The checks

The command prints one line per check: ok, warn or FAIL, the check’s name, and a detail. No value is ever printed; the secrets in the environment are blanked out of anything a command says. It exits 1 when any check failed. The checks come in two lists. The runner checks run before the project is cloned, from the environment alone. The project checks run once the project is there (on a runner, the clone under the work folder; on a laptop, the project folder) and depend on its foreman.config.json.

Check	What it looks at	How to fix it
FOREMAN_REPO	The variable is set to the project as owner/name.	Set FOREMAN_REPO in the runner’s environment (.env.runner).
GH_TOKEN	The variable is set.	Set GH_TOKEN to a GitHub token for the project repository.
claude sign-in	Which Claude sign-in the sessions will use, in Claude Code’s own order: a cloud provider (Bedrock, Vertex AI or Foundry), then ANTHROPIC_AUTH_TOKEN, then ANTHROPIC_API_KEY, then CLAUDE_CODE_OAUTH_TOKEN, then the login stored on the machine. A Console API key passes. A subscription token or a claude.ai login passes with a warning, since a subscription is for your own projects only. Nothing set fails.	Set ANTHROPIC_API_KEY (a Console API key) or CLAUDE_CODE_OAUTH_TOKEN (from claude setup-token).
github token	gh api user works with the token, and the token can read FOREMAN_REPO and has push permission on it.	Use a token for this repository with the permissions under Run in the cloud; a fine-grained token needs Contents read and write.
pull request checks	The token can list the repository’s pull requests and read the newest one’s checks exactly as the ci ship step does. A repository with no pull request yet warns that reading was not tried. A fine-grained token that cannot read check runs passes with a note: checks are read through GitHub Actions jobs and commit statuses, so a check another app posts is not seen.	Give a fine-grained token Pull requests, Actions and Commit statuses read, or use a classic token with the repo scope when your CI is an app that posts check runs.
claude answers	claude -p answers one prompt, within 120 seconds, with no error. This spends a few tokens, so the Set up tab skips it on a laptop.	Check the sign-in and the network from the runner; the detail carries what claude said.
plugin	FOREMAN_PLUGIN_DIR points at a Foreman plugin folder whose version is the version of this command.	The image sets it. Outside the image, set it to the plugin folder of the same Foreman release.
work folder	A file can be written in the work folder (FOREMAN_WORK, /work by default).	Mount a volume there that the foreman user can write. On Fly.io the entrypoint gives the volume to that user.
dashboard token	When FOREMAN_DASHBOARD_HOST is beyond the loopback address, as it is in the image, FOREMAN_DASHBOARD_TOKEN is set.	Set FOREMAN_DASHBOARD_TOKEN to something long and random.
docker socket	Only with env.adapter docker or supabase: /var/run/docker.sock exists in the container.	Mount it with -v /var/run/docker.sock:/var/run/docker.sock and give the foreman user access to it.
state branch	Only with state.store: "branch": the branch can be fetched from the config’s remote, and a dry-run push to the remote succeeds.	Check the token can push to the repository; see Run state on a branch.
salesforce tools	Only with "pack": "salesforce": sf with its plugins, at or above the pack’s minimum versions (the Salesforce CLI 2.0.0, sfdx-git-delta 6.0.0, Code Analyzer 5.0.0), and the agent plugin unless salesforce.agentforce is off, which only warns.	Use the -salesforce runner image, or build the image with --build-arg SALESFORCE=1.
python	Only with the Salesforce pack: python3 is on the path at 3.10 or later, for Code Analyzer’s engines.	As above.
java	Only with the Salesforce pack: java is on the path at 11 or later, for Code Analyzer’s engines.	As above.

The Set up tab’s Cloud runner step runs only the checks that are safe on your own machine, with the token you paste as GH_TOKEN: FOREMAN_REPO, GH_TOKEN, github token, pull request checks and dashboard token. Not claude sign-in, which would fall back to your laptop’s login; not claude answers, which spends tokens; and not plugin or work folder, which are the runner’s. Any failure there and the step sets no secret and writes no runner file.

With the Salesforce pack the checks above confirm the tools are present; they do not prove a release. The Salesforce pack is a preview: its release paths pass their own tests, but no story has yet shipped through them on a live org, and the Gearset path has not run against a live Gearset pipeline.

Fixing each one

A failed runner check stops the container at start with “Not starting: fix the checks above.” Fix the setting in .env.runner (or the Fly secret, or the Compose env file), then start the container again; docker run --rm --env-file .env.runner --entrypoint foreman <the runner image> cloud doctor runs the checks without starting a run. A failed project check means the project’s config asks for something the machine lacks: the Docker socket, a pushable remote for the state branch, or the Salesforce tools, which the detail names along with the image that has them.

Three checks join the laptop’s foreman doctor once a cloud set-up exists, each only when its file is there, so a project that runs only on a laptop gets none:

Check	What it looks at	How to fix it
cloud workflow	With .github/workflows/foreman.yml present: the run state is on a branch, which the workflow needs, and the file is exactly what this Foreman writes for this config. Another version’s file, or one changed by hand, warns.	Keep the run state on a branch from Set up › Cloud runner, and rewrite the workflow from the same step (or foreman cloud actions init --force).
cloud secrets	With the workflow present: GitHub has every secret the workflow reads, asked with gh secret list: FOREMAN_GH_TOKEN, one of the two Claude sign-ins, and each name in cloud.envVars. No GitHub remote, or gh unable to list, warns.	Set the secrets from Set up › Cloud runner, which uses your own gh sign-in, each value on stdin.
cloud runner file	With .env.runner present (a link to one too, even dangling): it is a plain file, not a link; git ignores it and does not track it; and only its owner can read it.	Replace a link with a plain file; add .env.runner to .gitignore from Set up › Cloud runner; git rm --cached .env.runner and commit if git tracks it; chmod 600 .env.runner if others can read it.