User Guide · Coral

Coral won’t start an agent: first-run fixes

The four first-run problems we see most, with the exact command or setting for each.

Coral starts the agent command you pick (Claude Code, Codex, Antigravity or Pi) in its own terminal. It does not install those commands and it cannot sign you in to them. Find your symptom below.

1. The agent launched, but you can’t prompt it

What it means. Launching means the agent process started. It does not prove the command is signed in or can reach its model, so the agent can look idle.

Coral 157 and later. For Claude and Codex, if the command is installed but not signed in, Coral shows a card that says “<command> is not signed in”, with a way to sign in and a Check again button. It reads the command’s own status straight away. While an agent is working on its first reply you see “Working” with a timer after a few seconds, and “Still working. Open the terminal to see what it is doing.” after 30 seconds. If the command exits first, the message is “<name> stopped before answering”, with a Restart button.

Fix.

Open the agent’s terminal in the dashboard and look for a trust-this-folder or sign-in prompt. Answer it, or sign in as the prompt says. Coral cannot sign an agent in for you.
To check sign-in from your own terminal, run claude auth status --json (signed out shows loggedIn false) or codex login status. Coral’s own sign-in check covers Claude and Codex only.
Sign in the way the vendor describes: Claude Code, Codex, Antigravity, Pi.

Coral does not type its own messages (board messages, nudges, a new agent’s first prompt) into an agent that is waiting at a prompt. It waits until you answer, then sends the message once.

You may have searched for: agent launched but not responding, claude not signed in, coral agent idle, trust this folder prompt.

2. tmux: optional, or missing

Coral 157 and later. On macOS and Linux, tmux is optional. Coral runs agents in its own built-in terminal by default, so a missing tmux does not stop an agent from starting. Install tmux if you want agents to keep running after Coral quits. To use it, install it as in the table below, then choose it in Settings › Terminal › Terminal backend (it applies the next time Coral starts), or start Coral with coral --backend tmux. If tmux is the chosen backend and it is missing, a line under the launch dialog shows the install command for your system and a Check again button, and Launch stays off until tmux is found. Quitting Coral on the built-in terminal ends its agents; with tmux they keep running across a quit, a restart and an update. If you upgrade while agents are still running in tmux, Coral uses tmux for that one start so none of them is hidden.

Earlier versions. On macOS and Linux, Coral runs agents in tmux by default. You may see “tmux not found” or “tmux is required”. Install tmux as below, or start Coral with coral --backend pty to run without it.

Your system	Fix
macOS app	tmux 3.7c is bundled. If it is reported missing, the app bundle was probably modified or partly copied: download `Coral.dmg` again.
macOS, other builds	`brew install tmux`
Debian or Ubuntu	`sudo apt install tmux`
Fedora	`sudo dnf install tmux`
Other Linux	Install `tmux` with your distribution’s package manager, or start Coral with `coral --backend pty` to run without tmux.
Windows	Nothing to install: Windows does not use tmux.

To use a tmux in a specific place, set CORAL_TMUX_BIN=/path/to/tmux. If you see “server version is too old” after an upgrade, an older tmux server is still running; point CORAL_TMUX_BIN at the tmux that started it, and restart that server only after you have finished its sessions, because restarting ends the processes inside it.

You may have searched for: tmux not found, tmux is required, coral tmux missing linux, tmux server version is too old.

3. Windows notes

Download: Coral-x64.msi (installer) or Coral-x64-portable.zip, both for 64-bit Windows. They are not code-signed, so SmartScreen warns that the publisher is unknown. Check the file as the README describes before you run it.
Address: the default port on Windows is 8450, not 8420. Open http://localhost:8450.
No tmux: Windows uses its own built-in terminal backend (ConPTY).
Agent commands: install them with the commands in section 4, which use npm.
Working folder: a network path cannot be used as an agent’s working folder. Choose a folder on this computer.

You may have searched for: coral windows smartscreen, coral localhost 8450, coral windows no tmux.

4. “CLI not found” at launch (provider unavailable)

What it means. Coral could not find the agent’s command (claude, codex, agy or pi) on your PATH, in Settings › CLI paths or in the usual install places. The message reads “<command> CLI not found. Install it: …”. In Coral’s usage categories this is called provider unavailable.

Agent	Install command
Claude Code	`npm install -g @anthropic-ai/claude-code`
Codex	`npm install -g @openai/codex`
Antigravity	Antigravity’s installer. The installer puts `agy` in `~/.local/bin`, which Coral checks; add that folder to your `PATH` to run `agy` in your own terminal. Sign in as described in section 1.
Pi	`npm install -g --ignore-scripts @earendil-works/pi-coding-agent`

Already installed? Set its full path in Settings › CLI paths (open the menu in the top bar, choose Settings, then the Agents section). If a path you set cannot be run, Coral says so and does not start a different program instead.

To recheck, launch the agent again. Coral looks for the command at every launch. If the agent then starts but does not answer, go to section 1.

You may have searched for: claude CLI not found, codex CLI not found, agy not found, coral provider unavailable.

Still stuck?

See Coral’s troubleshooting guide and getting started. If you write to support@subgentic.ai, include your Coral version, your OS and architecture, and the relevant lines from coral.log in your data folder. Do not paste prompts, source code or API keys.