Getting help

This page is for the moment Foreman does something you did not expect, or will not start at all: what to look at first, what to send with a bug report, and how to report a security problem without making it public. Foreman’s home is https://finefactory.ai/apps/foreman/.

Before you ask

Most problems explain themselves in one of four places. Look there first; a report that quotes them is answered faster.

Run foreman doctor. It finds and explains most set-up problems and says what to do. It runs every check and prints one line each, starting ok, warn or FAIL, then the check’s name and, after a dash, its detail. Under each warn and FAIL goes a fix line: what to do, and the Set up step that fixes it (“dashboard: Set up › Project keys”). It exits 1 when any FAIL is left and 0 on warnings alone, and never prints a key’s value. When it counts stray Foreman processes that tests or manual checks left running, foreman doctor --end-strays ends them. Every check is described on Doctor checks.

Read Waiting on you. The dashboard’s Waiting on you tab lists everything the run needs from you, ranked, in sections: Needs you now, Quick decisions, Your tasks, Later and FYI, with a headline that says why the factory is idle and the one thing to do first. foreman status prints the same list under “Waiting on you:”, after one line per slot, and its first line says when the run is stuck (“running, but stuck: <reason>”), paused, halted, or stopped and by whom. foreman status --json prints the whole snapshot, recent events included. See Waiting on you.

Read the logs. They are in the state folder, .foreman/ unless stateDir says otherwise:

Name	What it holds
.foreman/logs/supervisor.out	The supervisor’s own output: every start, pick, stop and warning. foreman run appends to it, and the background service writes its output and errors there too. foreman run prints its path when it starts.
.foreman/logs/w1-20261015-090000.log	One story session: the slot (w1, w2 and so on), then the start time. It is one JSON event per line, the stream Claude Code prints, with the odd plain warning between. A second session of the same slot in the same second gets -2. The dashboard’s View conversation reads the same file in plain words.

Nothing in the logs is redacted for you: read them yourself, and cut any key or token before you paste a line into an issue.

Read When things go wrong. It covers the cases Foreman handles by itself and tells you about: a story that is slow or stuck, the pause after three misses, rate limits and credits, an expired Claude sign-in, a config that stopped being valid, a crash or reboot, leftover branches, and who stopped the run.

Report a bug

If that does not settle it, or Foreman did something wrong, open an issue. The bug form asks for the version you installed, where Foreman runs, the doctor output and your config with the keys removed. The version is on the plugin fresh line of foreman doctor; foreman config show prints the resolved config, which holds no key, because keys live in .env.foreman and the env file, never in foreman.config.json. Fixes ship in the next release and are named in its changelog.

Report a security problem

For a security problem, keys, the production guard or anything an attacker could use, email hello@finefactory.ai with the subject “Foreman security” instead of opening a public issue.