Caterm

YOUR FIRST DEVICE

One computer.
A new way in.

Sign in to Caterm, connect a machine you own, then choose how you want to work from the browser.

1. Install Caterm on Linux

On Linux, install Caterm under the account you want to use, including root:

Optional: use a separate login account

Caterm also supports running directly as root. To use a separate account instead, create one from the root shell and switch to it before installing.

Bash
# Administrator shell only:
id caterm >/dev/null 2>&1 || adduser --disabled-password --gecos '' caterm
su - caterm

If you create this account, run installation and connection commands in its shell. Desktop sharing uses the account and display environment of your X11 desktop.

Bash
curl -fsSL https://downloads.caterm.com/install.sh | sh

The installer selects x86_64 or ARM64, verifies SHA-256, and installs a single caterm executable in ~/.local/bin. It requires glibc 2.36 or newer, curl, and tar. No Node.js, Rust, or GitHub account is needed.

Bash
export PATH="$HOME/.local/bin:$PATH"
caterm --version

Add ~/.local/bin to your shell's PATH if it is not already configured. The installer leaves your shell profile unchanged.

Inspect the installer, choose a version, or change the directory
Bash
curl -fsSL https://downloads.caterm.com/install.sh -o caterm-install.sh
less caterm-install.sh
sh caterm-install.sh --help
# Select a version already published in R2:
read -r -p 'Published version (X.Y.Z): ' CATERM_INSTALL_VERSION
sh caterm-install.sh --version "$CATERM_INSTALL_VERSION" --bin-dir "$HOME/.local/bin"
Upgrade an existing installation

Stop a running daemon, rerun the installer, then restart with your connection options. If stop reports no running daemon, continue with installation. Your saved credential is retained.

Bash
caterm stop
curl -fsSL https://downloads.caterm.com/install.sh | sh
caterm --version

For a normal connection, reconnect with caterm connect --saved. If you share a desktop, use --desktop in that desktop's environment.

For screen sharing, continue with Linux desktop sharing to check your environment and prepare X11.

2. Connect your device

Sign in with Google or email and password and choose Add a device. On Mac, use the Caterm app's enrollment flow. For the Linux daemon, copy the generated command and run it on your machine. The same 8-digit code works for the Linux command, Mac manual entry, and Mac connection link. Enrollment codes expire after five minutes and can be used once.

This is a simulated example for a daemon already installed on your device; use the server origin and enrollment code from your own workspace.

caterm connect --server https://your-caterm.example \
  --enrollment-code 00123456

Keep the device online. For later daemon connections, use caterm connect --saved. Revoke the device in its settings if the saved credential may have been exposed.

3. Prepare your AI agent

Install and sign in to Codex or Claude Code on the device. Configure its executable and project root in the Mac app's Settings → Personal agent or the daemon environment. Open Chat → New conversation, choose the device, select your agent, and choose a project folder.

Follow the Codex and Claude Code setup guide →

4. Choose your remote tools

Share a device

Owners can share all locally enabled tools with another verified Caterm account from device Settings. Each user creates independent conversations.

Running Caterm locally

For development, use Node.js 24+, pnpm 9, stable Rust with Cargo, Docker for PostgreSQL, and a Firebase project with Google and Email/Password sign-in enabled. From the repository root:

scripts/setup.sh
scripts/db-up.sh
# In separate terminals:
scripts/run-server.sh
scripts/run-web.sh

Configure the generated .env with your database and Firebase values before starting. Open http://127.0.0.1:5173; the API listens on 127.0.0.1:8080. For a local daemon, run the built target/debug/caterm with the generated enrollment command and the API origin http://127.0.0.1:8080.