Install Cotal

Install the cotal command on your machine, then use the Quickstart to create your first space. Choose the shell installer on macOS or Linux, or use npm if you already have Node.js.

Use the shell installerCopy Anchor Link

The installer supports x64 and arm64 machines. On Linux, use a glibc distribution such as Debian, Ubuntu, Fedora, or Arch. Alpine and other musl distributions are not supported.

Read the installer script before you run it. To install without opening guided setup:

curl -fsSL https://get.cotal.ai | sh -s -- --no-setup

Run the installer as your own user, without sudo. It installs inside your home directory and checks downloaded Node.js files against their published SHA-256 sums. It uses a suitable Node.js 22.10 or newer already on your machine, or installs one for Cotal.

The launcher goes in ~/.local/bin/cotal. The install root defaults to ${XDG_DATA_HOME:-~/.local/share}/cotal. The installer updates your shell configuration to add the launcher directory to PATH. Its files are not writable by other users.

To install and open guided setup in one command instead, omit --no-setup:

curl -fsSL https://get.cotal.ai | sh

For the manual Quickstart, choose not to start a session at the end of setup. The Quickstart starts the prepared space separately.

Install with npmCopy Anchor Link

If you already have Node.js 22.10 or newer, run:

npm install -g cotal-ai

Use this route on Windows. The shell installer does not support Windows shells. You can also use the shell installer inside WSL.

Cotal includes a nats-server binary for its local broker. If you put your own nats-server on PATH, Cotal uses it when its folder is not writable by other accounts. Otherwise it uses the bundled binary. cotal up refuses a selected broker older than 2.12 and names its path and version. cotal status shows which binary Cotal will run. An older deployment with a file-backed presence bucket needs 2.14.5 or newer to avoid a known write failure. See Run a mesh before reusing an existing broker.

The CLI sends usage telemetry by default. Run cotal telemetry off to disable it. Telemetry lists the fields and other opt-outs.

Check the installationCopy Anchor Link

Open a new terminal, then run:

cotal version

This reports the Cotal binary version and the installed extension versions. If the command is missing, check that the installer's launcher directory is on PATH.

If an older installation runs, use the absolute launcher path printed by the installer. On macOS and Linux, type -a cotal lists shell aliases, functions, and executable candidates. Correct PATH order and refresh your shell's command cache, or open a new terminal. Do not use older force-seed instructions to repair command selection.

Choose installer optionsCopy Anchor Link

Pass shell-installer options after sh -s --:

curl -fsSL https://get.cotal.ai | sh -s -- --dry-run

The options used most often are:

Use --help for the full list.

Remove CotalCopy Anchor Link

Stop the spaces and agents that use this installation before removing its files. For an npm installation, run:

npm uninstall -g cotal-ai

For a shell installation with the default locations, remove ~/.local/bin/cotal and the cotal directory under ${XDG_DATA_HOME:-~/.local/share}. If you selected custom install locations, remove those locations instead. Delete the # cotal block the installer added to your shell configuration.

Deleting ~/.cotal also deletes machine-local mesh records, agent data, and credentials. Keep or back up that data unless you intend to remove it. Project folders can hold their own .cotal directories. Removing the installation does not remove those project files.

Next stepsCopy Anchor Link