Troubleshooting & FAQ

This page lists real failure modes with concrete fixes, roughly in the order you are likely to hit them: connecting the CLI, logging in, running agents, and keeping the board live. Commands are covered in detail in the CLI command reference; setup basics are in the Quickstart.

The CLI cannot reach the server

Symptom: forge auth login or forge connect fails to reach the cockpit, or forge auth status prints Cloud: Unreachable.

The most common cause: the CLI's default server URL is http://localhost:3000, and there is no environment-variable override. If you never passed --server, every command is talking to your own machine. Fix it once at login — the URL is persisted to ~/.forgeai/config.json on success:

forge auth login --server https://forgeai-production-382c.up.railway.app

If the URL is correct but the connection still drops, check the network path. The CLI's Socket.io connection is WebSocket-only — there is no HTTP long-polling fallback. Corporate proxies, VPNs, or reverse proxies that block or fail to upgrade WebSocket connections will break forge connect even when plain HTTPS requests (like login) work. Use an https:// URL and a network that allows WebSocket upgrades. See Authenticating the CLI and Security.

Diagnosis steps:

forge auth status        # prints server URL, then Cloud: Connected / Unreachable
forge org list           # per-org status: connected / disconnected / not registered / unreachable

Device code expired or login timed out

forge auth login prints a verification URL and an 8-character code, then polls the server for up to 30 minutes. If you approve too late, the poll times out (or the code is rejected as expired). There is nothing to repair — run forge auth login again to get a fresh code, and approve it at /device on the cockpit while the CLI is still polling.

Related login failures:

• "You are not a member of any organization. Create one first." — approving a device requires membership in at least one organization. Create one in the cockpit, then retry. See Organizations & members.
• Registration rejected with a plan-limit error — your plan's CLI-connection limit is reached (1 device on Free). The CLI suggests upgrading or freeing a slot with forge org unlink <slug>. See Plans & billing.
• Expired session later on — CLI tokens follow the cockpit session lifetime (20 days, refreshed every 7 days of activity). After 3 consecutive WebSocket authentication failures the CLI exits and asks you to run forge auth login again.

Docker is not running

Docker is a hard requirement for agent execution — agents run in local containers. If Docker Desktop is not running, forge vm init (and agent startup) fails:

forge vm init

The command checks the Docker daemon with docker info (5-second timeout) and exits with code 1, pointing you to Docker Desktop, if the daemon is unreachable. Start Docker and re-run it. forge vm init then ensures the agent image getforgeai/agent:latest exists — trying docker pull first and falling back to a local docker build. Beta note: the local image build targets linux/arm64, so Apple Silicon is the primary supported platform today; see Prerequisites.

To inspect the agent runtime:

forge vm status      # active sessions and whether Docker is ready
forge vm cleanup     # remove containers for STOPPED sessions
forge vm stop-all    # force-stop all ForgeAI-managed containers

Agents fail: no AI credentials

Agents run with your AI credentials, configured in each container — ForgeAI does not provide AI credits. If no credentials are stored for the configured agent engine, the forge connect daemon warns at startup that agents will fail to authenticate and tells you which command to run:

forge auth setup-claude     # agent-type CLAUDE_CODE (default)
forge auth setup-codex      # agent-type CODEX
forge auth setup-opencode   # agent-type OPENCODE
forge auth setup-kilo       # agent-type KILO

For Claude Code this runs claude setup-token (you must already be logged into Claude Code on this machine) and stores the long-lived token in the macOS Keychain, or AES-256-GCM-encrypted under ~/.forgeai/auth/ on other platforms. For Codex, OpenCode and Kilo it imports the engine's existing login from your machine or stores an API key, with the same storage. If an agent later exits with an authentication error, the CLI re-reads the stored credentials and, if they are unchanged, asks you to run the matching forge auth setup-* command again.

If your AI credits run out mid-task, the task does not burn its retry budget: the CLI device enters a cooldown (default 20 minutes, configurable 1-120) during which it is excluded from dispatch. The cockpit shows "Credits exhausted" with a countdown under Settings → CLI Devices, plus a Re-include button to clear the cooldown early.

The workflow branch stays pending or shows an error

When a workflow is created with a git branch configured, the wizard header shows the source branch, the base branch, and a status badge: pending, created, or error. The branch is created by your connected CLI, on your machine, with your local git credentials. See Workflows.

• Stuck on pending — no CLI was connected when the workflow was created; the wizard shows "Connect a CLI to create the workflow branch". Nothing is lost: the cockpit automatically re-sends the branch-creation request as soon as a CLI connects. Run forge connect and the badge updates live.
• error — the CLI ran the git operations and failed. Typical causes: the local clone's remote URL does not match the project's configured repository URL, the branch name already exists but was not created from the configured source branch, or the clone/fetch itself failed (for example, git authentication). The exact git error appears in the CLI output — run forge connect --attach or check ~/.forgeai/daemon.log for [branch] lines.

Beta note: an errored branch is not retried automatically — the automatic re-send only covers pending branches, and the Retry button in the wizard chat retries the agent dispatch for the current step, not branch creation. The error status cannot be cleared: even if you create the branch manually on your machine, the cockpit keeps showing error and tasks generated by the workflow will not run on it (the dispatcher only uses the workflow branch once the cockpit has marked it created). Fix the git problem on the CLI machine, then delete the workflow and create a new one to restart the branch flow.

The board is not updating

The live board is driven by two WebSocket connections: your browser to the cockpit, and your CLI to the cockpit. Either one going stale makes the board look frozen. See Tasks & the live board.

1. Check the status bar at the bottom of the board. "No CLI connected" means no CLI in the org currently has a live heartbeat.
2. Check the CLI side. CLI presence is a heartbeat sent every 30 seconds with a 60-second server-side expiry, so a killed laptop or dropped VPN shows up as Disconnected within about a minute. Run:

forge connect            # prints daemon PID and per-org status; reconnects missing orgs
forge reconnect          # re-establish dropped connections (requires a running daemon)

3. Refresh the browser tab if the CLI reports connected but the board still lags — the browser reconnects and reloads current state.

You do not lose events during a CLI outage: the CLI journals events locally as NDJSON while the WebSocket is down and replays them to the cloud over REST when it reconnects (deduplicated per event, rate-limited to 10 sync requests per minute per CLI). If a CLI disconnects mid-task, its active tasks return to waiting and are re-dispatched to other available CLIs; tasks awaiting human input keep their state.

One more culprit: an unhealthy MCP bridge. If the CLI prints MCP unhealthy — this CLI will not receive dispatches, the dispatcher skips this device (the cockpit shows "MCP broken — dispatches paused"). The CLI re-probes every 60 seconds; if it never recovers, restart the daemon with forge connect --stop then forge connect.

A CLI device looks stale in the cockpit

Devices that were registered on machines you no longer use (or duplicate registrations) linger in Settings → CLI Devices as Disconnected. Clean them up from any authenticated CLI:

forge cli list             # all registered devices; yours is flagged (current)
forge cli unlink <cliId>   # unregister a device (y/N confirmation)

The device owner or an org admin can do the same from the cockpit: Disconnect closes the device's connection and releases its incomplete tasks, while Unlink additionally deletes the device record and unassigns its tasks. Unlinking stale devices also frees plan CLI slots — see Plans & billing.

Where logs and the journal live

All CLI state is under ~/.forgeai/:

Path	Contents
~/.forgeai/daemon.log	Background daemon output — the first place to look when forge connect misbehaves
~/.forgeai/events/	Local NDJSON event journal, one file per organization
~/.forgeai/config.json	Server URL, linked orgs, agent settings
~/.forgeai/docker/sessions/	Per-task agent session directories

For live debugging, run the daemon in the foreground so logs stream to your terminal:

forge connect --attach

Inspect and manage the journal with:

forge journal status    # last sync time, pending events, sync cursor
forge journal list      # total events, pending-sync count, last event
forge journal clear     # delete entries (warns that unsynced events are lost)

Beta note: journal list and journal clear without an argument read a default journal file, while journal status reads the default organization's journal — the one forge connect actually writes. Prefer forge journal status for an accurate pending count.

FAQ

Is my code uploaded to ForgeAI?

No. Agents run in Docker containers on your machine, and your repository is cloned locally using your own git credentials — the cockpit never receives your repository. The cloud stores coordination data: projects, tasks, workflow state, and artifacts (a file path plus, optionally, a copy of deliverable file content for in-cockpit viewing). Workflow conversation messages are encrypted at rest with AES-256-GCM using a per-workflow key, and are permanently deleted when the workflow completes. Details in Security.

Which coding agents are supported?

Four engines, all running in local Docker containers with your own credentials (see Prerequisites): Claude Code (the default), Codex, OpenCode, and Kilo Code. Pick one per CLI device with forge config set agent-type <CLAUDE_CODE|CODEX|OPENCODE|KILO> or from the cockpit under Settings → CLI Devices, and store the matching credentials with forge auth setup-claude, setup-codex, setup-opencode, or setup-kilo. If you switch engines on an image built before Codex/OpenCode support, the CLI fails fast and tells you to update the agent image.

Can I self-host ForgeAI?

ForgeAI follows an open-core model. The execution half — the CLI, the agents, the git operations — runs entirely on your own machine and is published on npm under the Apache-2.0 license. The cockpit (this web app) is a proprietary multi-tenant SaaS and is not offered for self-hosting. See Installing the CLI.

Do I pay for AI usage?

You bring your own AI tokens: agents authenticate with the credentials you store via forge auth setup-claude / setup-codex / setup-opencode, so AI usage is billed to your own subscription or API key (Claude, ChatGPT/OpenAI, your OpenCode provider, or your Kilo account), not by ForgeAI. Platform billing itself is inactive during the beta — see Plans & billing.

Getting help

Still stuck? Re-run the basics in order: forge auth status, forge vm init, forge connect --attach, and watch ~/.forgeai/daemon.log. If the problem is on the cockpit side, check your organization's device list under Settings → CLI Devices.

To reach the team:

• Feedback button — the message icon in the top bar of every organization page (also in the workflow wizard toolbar) opens a short form with a message field and a satisfaction rating. Submissions go directly to the ForgeAI team.
• Contact form — the public contact page at /contact on the cockpit has a full support form (name, email, subject, message); replies go to the email address you enter.
• Contact support dialog — error screens (such as 404 and permission errors) include a Contact support button that opens the same kind of support form.