Skip to main content

Add a computer to your account

Every computer that runs agents for your CatalEx account is listed under Settings → Computers. Signing in on a Mac with CatalEx adds that Mac by itself. To add a server or VM, create a one-time join code on a signed-in device and run the installer on the new computer.

Before you begin​

  • Sign in to CatalEx Cloud, or your own service, with a CatalEx account on the device you start from. The Computers tab appears only after this sign-in.
  • The new computer runs Linux on amd64 or arm64 with systemd, and you can use sudo there. Its agents need Codex or Claude Code installed on it.
  • CatalEx releases are downloaded from the private catalex-ai/catalex-builds GitHub repository. On the new computer, use a fine-grained personal access token with read access to that repository's contents.

1. Create a join code​

In the app, open Settings → Computers and choose Add computer. The dialog shows a one-time join code, how long it stays valid, and a command for the new computer with Copy command.

From the terminal:

catalex computers add

Expected result: a join code (one computer, one use, valid for 15 minutes by default), the fingerprint of this device's key, and the installer command. Keep the code private; it goes into a hidden prompt, never into a command line or URL. For a shorter lifetime, add --lifetime 10m. If the code expires, create a new one.

If the command fails with COMPUTERS_DISABLED, the messaging service has computers turned off; ask its administrator to turn them on.

2. Run the installer on the new computer​

The installer is published at https://docs.catalex.co/install.sh. Run it on the new computer, replacing FINGERPRINT and ORIGIN with the values from step 1:

printf 'GitHub token: ' >&2; stty -echo; read -r GITHUB_TOKEN; stty echo; echo >&2
export GITHUB_TOKEN
curl -fsSL https://docs.catalex.co/install.sh | sudo --preserve-env=GITHUB_TOKEN sh -s -- \
  --join --trust FINGERPRINT --service ORIGIN

The first two lines read your GitHub token without showing it. When the installer asks, paste the join code. It installs the catalex command and Local Relay, runs them as the catalex service user (home /var/lib/catalex), and joins the computer to your account. Without sudo, drop sudo --preserve-env=GITHUB_TOKEN; the installer then runs CatalEx as your own user.

CatalEx 0.9.0-rc.35 and earlier print the installer address as https://get.catalex.ai, which does not exist. Use the command above with the fingerprint and service from that screen.

Expected result: the installer reports that the computer joined. On your other device, the app shows NAME joined your account. and lists the computer as Online. From the terminal:

catalex computers list

Running the installer again on a computer that already joined reports its service and computer ID and changes nothing.

3. Sign in to the AI tool on the new computer​

Agents on the new computer use its own Codex or Claude Code sign-in. Install the tool for the catalex service user, then sign in as that user:

sudo -u catalex -H /var/lib/catalex/.local/bin/claude auth login
# Or, for Codex on a computer without a browser:
sudo -u catalex -H /var/lib/catalex/.local/bin/codex login --device-auth

Use your tool's installed path if it differs. Without sudo in step 2, sign in as your own user instead.

4. Add agents on the new computer​

Choose the new computer when you add an agent. Its agents appear under Agents → Everything else, grouped by computer, and their work stays on that computer.

Manage your computers​

Settings → Computers lists each computer with its state, such as Online or Offline · last seen 3 days ago. From there you can Rename, Remove (asks first; that computer's agents stop answering, and chat history is kept), or Stop using for agents on this computer. From the terminal:

catalex computers list
catalex computers rename COMPUTER_ID NAME
catalex computers remove COMPUTER_ID
Last updated on