---
name: catalex-setup
description: Start with no CatalEx installed, install its CLI, set up the runtime, onboard an agent and verify a reply.
---

# Set up with an AI agent

This is the fresh setup path: **nothing from CatalEx needs to be installed before you give your agent the setup prompt**. The agent installs the `catalex` command-line client first, then uses it to install and configure the rest.

You need an Apple Silicon Mac and a terminal-capable Codex or Claude Code agent that is installed and signed in. Open that agent in the folder you want to onboard. If you do not have an AI tool yet, install and sign in to your chosen tool first.

Follow the steps below in order. Keep the agent’s existing folder, AI tool, instructions, tools and restrictions. If CatalEx is already installed, use the [existing setup path](https://docs.catalex.co/getting-started/agent-setup#existing-installations) instead.

## 1. Install the CatalEx CLI

The `catalex` command is required for every later step. On a fresh computer it does not exist yet. Download and run the installer using the Mac’s terminal tools:

```bash
catalex_installer="$(mktemp)"
curl -fsSL https://raw.githubusercontent.com/catalex-ai/catalex-builds/main/relay/install/catalex.sh -o "$catalex_installer" &&
  sh "$catalex_installer" --no-launch
export PATH="$HOME/.local/bin:$PATH"
catalex version
```

The installer installs the CLI and, on Apple Silicon macOS, the CatalEx app. `--no-launch` keeps the app closed until setup is ready. It verifies the downloaded release files against their checksums.

**Expected result:** `catalex version` prints a CatalEx version number. Do not run the remaining `catalex` commands until this succeeds. If the command is not found, use the PATH line above in this terminal or open a new terminal.

If the person explicitly wants no desktop app, run the installer with **`--no-app` instead of `--no-launch`**. Do not combine those flags: `--no-launch` controls an app installation, while `--no-app` omits it.

## 2. Install the runtime components

Now that the CLI works, choose the setup the person wants and install its components:

| Setup | Install with the CLI |
| --- | --- |
| Native chats in CatalEx | `catalex install relay dashboard` |
| Agents and messaging on this computer | `catalex install relay hosted-relay dashboard` |
| Connect these agents to an existing server | `catalex install relay dashboard` |

Use an explicit choice from the person or agent package. Otherwise ask which setup they want; offer Everything on this computer, with messaging now or later. The default messaging service uses SQLite and needs no separate database server or Docker.

```bash
catalex install status
```

**Expected result:** the chosen components are installed. This installs software; it does not configure or start a setup yet. The component identifiers above are command arguments, not instructions to manage separate projects.

## 3. Check the AI tool

```bash
catalex providers
```

Use the AI tool the folder already runs on: `claude` or `codex`. If it is missing, ask the person to install it. If it needs sign-in, use `catalex providers login claude` or `catalex providers login codex` and let them complete sign-in themselves. Check providers again.

**Expected result:** the chosen AI tool is installed and signed in. Do not change the folder to a different provider to work around an error.

## 4. Configure and start CatalEx

Run **one** command for the chosen setup. These examples use Claude; replace `claude` with `codex` for a Codex agent:

```bash
# Native chats only
catalex setup --mode native_chat --native-providers claude --start

# Agents and messaging on this computer
catalex setup --preset everything --native-providers claude --start
```

A connection to an existing server needs its real URL and a private connector-token file; follow [the server setup steps](https://docs.catalex.co/getting-started/install#connect-to-an-existing-server). Never send a token to an example address.

Add `--no-launch` to setup if the person wants the app kept closed. A no-app or no-launch choice also means **do not call `catalex open`** later.

```bash
catalex status
```

**Expected result:** a native-only setup reports `native_chat` ready. Messaging setups also need their messaging components and service connection ready. Saved choices are reused when the same setup command is repeated after an interruption.

## 5. Onboard the agent folder

Use the absolute folder where this agent’s instructions live. Do not copy a packaged agent into an empty folder. For multiple roles, onboard each role’s folder separately.

```bash
catalex agents onboard --folder /absolute/agent-folder --name Helper --agent claude --json
```

Use `codex` for Codex. Without `--apply`, the command only inspects. Review findings and follow [the onboarding remedies](https://docs.catalex.co/agents/add-an-agent#resolve-onboarding-findings). For Claude packages that require folder isolation, use `--isolation folder`. For Codex, do not remove a package’s isolation requirements to make it register.

Then repeat with the same choices and `--apply`. Record the changed files and agent ID. Preserve everything outside CatalEx’s marked integration block and retain the package’s native guards. An agent whose tool serves one fixed person needs [per-person routing](https://docs.catalex.co/agents/folders-and-tools#tools-that-serve-one-person) before it can safely serve separate chats.

## 6. Verify a real reply

```bash
catalex channels list --json
catalex chats create --channel NATIVE_CHAT_CHANNEL_ID --name "Setup check" --json
printf 'Reply with exactly: CATALEX READY\n' | catalex chats send CHAT_ID --wait
catalex chats history CHAT_ID
```

Read the agent’s `native_chat` channel ID from the list and the chat ID from the create result. Older versions call this channel `browser`. Do not substitute an account ID. The response must contain `CATALEX READY`.

Next ask a question whose answer requires a known folder file or native tool, and compare the result with that source. Test a restriction if the package has one. A greeting alone does not prove tools or instructions loaded. Keep the chat for inspection. Open the installed app with `catalex open` only when the person wants it opened; skip this for no-app or no-launch setups.

## 7. Connect messaging if requested

Follow [WhatsApp](https://docs.catalex.co/channels/whatsapp), [Slack](https://docs.catalex.co/channels/slack) or [Google Chat](https://docs.catalex.co/channels/google-chat). For terminal setup, use [the checkpoint workflow](https://docs.catalex.co/channels/agent-workflow). A service on this computer needs a public HTTPS address. Ask before provisioning a tunnel service the person has not selected.

Assign the account to the intended agent, review its access rules and limits, then send a real message from the receiving app. Do not claim WhatsApp, Slack or Google Chat works from a native-chat test.

## 8. Report the result

Report the version, setup choice, agent name and folder, onboarding file changes, native reply evidence and messaging delivery evidence separately. Name remaining work with its next command: provider sign-in, trust prompt, account credentials, public address or delivery check.

If a step fails, read the code and next action, repair through supported commands and retry. Do not silently switch providers or recreate accounts. See [Troubleshooting](https://docs.catalex.co/troubleshooting).

## Existing installations

Check `command -v catalex` first. If it is present, run `catalex version` and `catalex install status`; install any missing components from step 2. Then inspect `catalex status`. If nothing is configured yet, continue with steps 3 and 4. If a saved setup is stopped, run `catalex start`. Reuse a running setup rather than reinstalling or resetting it. Connect an additional installed provider with `catalex providers connect PROVIDER` when needed, then continue with step 5 for a new agent folder.

## Rules and recovery

Use `catalex <command> --help` for the installed release’s flags and `--json` when you need structured fields. Use supported CLI operations for configuration and lifecycle; do not edit CatalEx configuration/databases, call private APIs or kill its processes to bypass an error.

Keep secrets out of chat and command arguments. Use private files or the app’s credential fields. Preserve the package’s guards and instructions outside CatalEx’s marked block. Do not delete data, replace a server identity or expand permissions without authorization. Inspect the original operation before retrying an uncertain change. Installation, configuration, onboarding and a verified reply are separate outcomes.