Install and set up CatalEx
Before you begin
You need access to the catalex-ai/catalex-builds release repository and GitHub CLI authenticated with that access. The installer installs the desktop app on Apple Silicon macOS; elsewhere it installs the command-line client. See the release installation guide for supported release assets and alternatives.
Install and sign in to Codex or Claude Code on the computer where your agents run. Use the provider you already use for the folder.
Install the command
Run the release installer in a terminal:
sh -c "$(gh api repos/catalex-ai/catalex-builds/contents/relay/install/catalex.sh -H 'Accept: application/vnd.github.raw')" catalex-install --no-launch
export PATH="$HOME/.local/bin:$PATH"
catalex version
The installer verifies downloads against the release checksums. --no-launch keeps the app closed until setup is ready. If GitHub returns “Not Found,” check your repository access and gh auth status.
Choose what to run
| Setup | Use it for |
|---|---|
| Native chats only | Try your agent in the CatalEx app without a messaging service |
| Everything on this computer | Run agents, native chats and the messaging service locally |
| Connect to your own service | Run agents here with an existing remote messaging service |
| Messaging service only | Host messaging for agents that run on other computers |
For native chats only:
catalex install relay dashboard
catalex providers
catalex setup --mode native_chat --native-providers claude --start
For agents and the messaging service on this computer:
catalex install relay hosted-relay dashboard
catalex providers
catalex setup --preset everything --native-providers claude --start
Use codex instead of claude if that is your provider; use claude,codex to connect both. catalex providers reports installation and authentication problems. If sign-in is required, run catalex providers login claude or catalex providers login codex and complete the provider’s sign-in yourself.
Check setup and open the app:
catalex status
catalex open
Setup opens the installed app when started unless you pass --no-launch. Add an agent and verify a real reply before connecting a messaging app.
Connect to an existing service
Ask its administrator for the real service URL and a connector token. Store the token in a private file with mode 0600; pass its path to the command:
catalex install relay dashboard
catalex setup --preset self-hosted --service-url https://YOUR-SERVICE --token-file /absolute/private/token --native-providers claude --start
Replace https://YOUR-SERVICE with your service’s address. A connector token connects your agents; it does not grant service administration. Your administrator may need to complete messaging account setup.
Connect another provider later
In Settings → AI tools, connect an installed, signed-in provider. The equivalent commands are:
catalex providers discover
catalex providers connect codex
Existing agents retain their saved provider and model choices. See troubleshooting if setup cannot start.