Get the CatalEx app

The CatalEx app is the main way to use CatalEx on a Mac. You download it, open it and sign in with Google. Your agents run on this Mac, and CatalEx Cloud carries their messages, so you run no server and need no public address. The app keeps CatalEx running, so you do not need a terminal.

The app is for Macs with Apple silicon. To install from a terminal, or to let an AI agent do it, see Install CatalEx and Set up with an AI agent.

Before you begin

• A Mac with Apple silicon.
• Claude Code or Codex, installed and signed in on this Mac. The app does not install them.
• A Google account. CatalEx has no email and password sign-in.

In the app

1. Download CatalEx for Mac (Apple silicon). The checksums are in SHA256SUMS.
2. Open the .dmg and drag CatalEx to Applications.
3. Open CatalEx. The build is not notarized, so macOS may refuse the first launch. In that case open System Settings, choose Privacy & Security, and select Open Anyway for CatalEx. Or Control-click the app and choose Open.
4. CatalEx opens one window and shows the Starting CatalEx screen while it prepares everything on this Mac. This may take a few seconds. It needs no sign-in and no AI tool at this point.
5. On a first launch, the setup starts. Its milestones, top left, are You, Your AI, CatalEx Cloud and Done.
   • What describes you best? Pick a role. It only chooses the sample chat you see at the end. Select Pick your AI.
   • Pick your AI. Claude Code and Codex are listed. Each shows Ready, or Not found on this Mac with Locate… if you want to point CatalEx at the program. Tick the ones to use, at least one, and select Reach it from anywhere.
   • Reach it from anywhere. Select Log in using Google. Your browser opens Google's account chooser. Pick your account and finish there.
   • Linking this Mac. The window shows Finish in your browser. until the sign-in is done. Signing in and joining this Mac to your account are one step, and the window then shows Starting CatalEx… while CatalEx comes up.
   • You're all set. The next screen, You are done, shows a sample chat. Select Create your first agent.
6. If the sign-in does not finish, the window shows Sign-in didn't finish. with the reason. Select Try again. If CatalEx cannot start afterwards, it shows There was an error starting CatalEx. Select Retry.

You end up in the Agents view. With no agent yet, it opens Bring your agent, the first of four steps: Bring your agent, Say hi, Take it where you work and Set how it replies. Add an agent walks through them.

What you see

The side navigation lists Agents, Marketplace, Analytics and Settings. At the bottom it shows your name and picture. Select it to open your account, which has Log out. The small light on it shows the health of the whole setup.

The app keeps CatalEx running while the app is open. Closing the window leaves the app and your agents running in the menu bar. Quit CatalEx in the menu bar menu also leaves CatalEx running, so agents keep answering. The menu also has Open CatalEx, Settings…, Check for Updates…, Set Up CatalEx… and Open at Login.

Sign out and back in

Select your name at the bottom of the side navigation, then Log out. The dialog Are you sure you want to log out? has one option, Also stop the agents running on this Mac. It is off by default, so the agents keep running unless you tick it.

After a log out the app shows Welcome back to CatalEx with Log in using Google. Your agents and chats are still there once you sign in. Sign-in is required: while signed out, the app shows no agents, chats or channels.

If another device signed you out, or this Mac was removed from your account, the window says so ("You were signed out from another device." or "This computer was removed from your account.") with Sign in again to continue.

Starting and repair screens

The app watches CatalEx and repairs it without asking. If something stops, the Starting CatalEx screen comes back while the app restarts it. It reinstalls damaged program files from its own copy, and if your saved data is damaged it moves that data aside, never deleting it, and starts again at the sign-in. Only when three restarts in a row fail does the app show Oops, there was an issue starting CatalEx. with Try again. See Troubleshooting.

With the CLI

The app carries its own copy of catalex and places it in ~/.local/bin, but it does not add that folder to your PATH. For catalex in a terminal, run the one-line installer, or run ~/.local/bin/catalex path add and open a new terminal.

Task	Command
Sign in with Google (opens your browser, waits up to 10 minutes)	catalex login
Check who is signed in	catalex account status
Sign out (agents keep running)	catalex logout
Sign out and stop the agents on this Mac	catalex logout --stop-agents
Open the app	catalex open
See whether the app runs, its version and whether it opens at login	catalex app status
Quit the app; agents and chats keep running	catalex app quit
Open the app at login, or stop that	catalex app login on, catalex app login off

catalex login prints the sign-in link too, in case no browser opens. When it succeeds it prints:

Signed in to SERVICE as EMAIL.
This computer is now one of your computers.
Trusted for changes: yes

catalex account status then prints Account: signed in as EMAIL, the service, a client ID and Trusted for changes: yes. catalex open accepts --section agents, --section settings, --section settings/providers or --section settings/channels to open a view.

The setup questions of the app have one terminal equivalent for everything after the role: catalex setup --preset cloud --native-providers claude --start (use codex, or claude,codex). It signs in as catalex login does, joins this Mac and starts CatalEx. The role question has no command because it only picks the sample chat.

Limits

• The app is for macOS on Apple silicon. catalex also runs on Linux; see Devices.
• Every catalex command that touches agents, chats or channels needs a sign-in and fails with ACCOUNT_SIGNIN_REQUIRED without one. Commands that install, update, set up, start, stop or check CatalEx run signed out.
• A page opened in a plain browser shows only CatalEx needs you to sign in. Open the app, or run catalex login, then select I've signed in.
• The app offers CatalEx Cloud only. Running everything on this computer, or against a server of your own, is a terminal setup: catalex setup --preset everything or --preset self-hosted. See the command reference.