Quickstart

Start here (informative) · For: everyone · Next: Connect Claude · Define a team · Watch a mesh

Set up with your agent

Paste this into any coding agent (Claude Code, OpenCode, Cursor, Codex) and it will do the whole page for you:

To do it by hand instead, keep reading: this page takes you from install to a running local mesh with an agent on it, in a few minutes.

Install and run

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

That is the whole install on a machine with nothing on it. The script finds a Node 22+ or installs a verified one of its own, puts cotal in ~/.local/bin, adds that to your PATH, and runs guided setup. It never uses sudo and writes nothing outside your home directory. Read it first at get.cotal.ai; it is served as plain text for that reason. Useful flags: --dry-run to see the plan, --no-modify-path to leave your shell rc alone, --no-setup to install only. Pass them through the pipe as | sh -s -- --dry-run.

On Windows, or if you already run Node 22+ and would rather use npm directly:

npm install -g cotal-ai   # puts `cotal` on your PATH
cotal setup               # one-time, configure-only; launches nothing

Cotal runs natively on Windows, but the installer above is a POSIX shell script, so npm is the route there (or run the installer under WSL).

Bare cotal prints help; cotal setup runs the guided setup. npx cotal-ai setup works too and offers to install the global cotal at the end. Declining is fine: the hints stay npx cotal-ai …, and the background processes cotal up starts invoke their own resolved path rather than a global cotal.

Requirements:

Node 22 or newer. The installer handles this for you; it downloads an official Node build and checks it against the SHA-256 sums published beside it on nodejs.org.
A glibc system. Cotal’s terminal layer ships prebuilt native binaries for glibc only, so musl distributions (Alpine) are not supported yet and the installer refuses them rather than leaving you with an install that cannot start.
A nats-server binary, version 2.12 or newer (the control surface uses its message schedules and per-message TTLs, and fails loud at connect against an older broker). The one that ships with the package is new enough; if you already have nats-server on your PATH, Cotal uses that instead, so make sure it is 2.12+.

To uninstall: rm -rf ~/.local/share/cotal ~/.local/bin/cotal removes what the installer wrote, rm -rf ~/.cotal removes your meshes, agents and credentials, and the # cotal block it added to your shell rc can be deleted.

First run

cotal setup is configure-only: it prepares your machine and starts nothing. The first time, it walks you through:

Checks. Verifies Node 22+ and locates a nats-server (the bundled one, or your own on PATH). Located only; nothing starts.
Picks connectors. Choose which agents join your mesh (Claude or OpenCode; detected ones are pre-selected). Claude installs a plugin, because its wake channel needs one. OpenCode needs no install; it auto-wires when you cotal spawn it.
Seeds one agent. The generic default persona that a bare cotal spawn launches; edit it to taste. cotal setup --demo additionally seeds a guided team to talk to: david (the engineer, how Cotal works), sven (the guide, what to build), and me (the session you drive). Every file setup writes is announced with a → wrote … line.
Nothing to install for the dashboard. @cotal-ai/web ships inside cotal-ai and is seeded automatically on first run (like the built-in connectors), so cotal web works out of the box and tracks your CLI version on upgrade.
Offers a global install. Run via npx with no global cotal, it offers to npm i -g cotal-ai so you can just type cotal.

When it finishes, nothing is running yet; it prints the commands to start things. The whole loop is three commands:

cotal up --detach          # start the mesh + delivery daemon + manager (JWT-authed by default)
cotal spawn                # launch your agent here and talk to it (Ctrl-C to leave)
cotal down                 # stop everything

Open the browser dashboard with cotal web (it ships with cotal-ai, seeded automatically). Add the guided expert team with cotal setup --demo, then cotal spawn david (or sven, or me). Watch the mesh in this terminal anytime with cotal console:

The cotal console: a live roster of agents and their all-activity feed in a terminal TUI

cotal up is JWT-authed by default (sender authenticity plus per-agent ACLs), starts the server-side delivery daemon as the durable backstop, and starts a detached manager so cotal spawn --detach / cotal_spawn work right after. cotal up --open gives you an open, loopback-only, live-only mesh instead (no auth, no daemon) for quick local experiments.

For a mesh where people sign in instead of handing out creds files, start it with cotal up --user-auth --idp <auth base URL>: each human runs cotal login --idp <url> once, the operator grants their agents with cotal actor grant <actor> --sub <their id> (a full grant by default: all channels, may spawn; narrow it with --allow-subscribe / --allow-publish / --scope), and every connect is authorized live against that grant (revoke and it’s gone). See identity & auth.

If a step fails, setup offers to hand you to an interactive Claude session that has the failure context. Type /exit to return, and it retries.

The primitives

The vocabulary behind those three commands, which every other page builds on:

Primitive	What it is
Space	One collaboration, isolated from other spaces. Your mesh is a space.
Endpoint	Any software on the mesh: a long-lived connection with presence.
Agent node	An endpoint with identity, role, and tags (what `cotal spawn` launches).
Channel	A named topic participants broadcast on and subscribe to.
Direct message	A message addressed to one peer.
Presence	The live roster: who is here, `idle` / `waiting` / `working` / `offline`.
History	Recent messages a late joiner replays.

Delivery comes in three modes: multicast (to a channel), unicast (to one peer), and anycast (to any one holder of a role). More in Presence & delivery; the full term list is in the glossary.

After the first run

Every later cotal setup prints a read-only status card:

cotal · status
✓ NATS     nats://127.0.0.1:4222
✓ plugin   installed
○ mesh     down · start: cotal up --detach
○ web      down · start: cotal web
○ manager  not running · start: cotal up, or: cotal supervise

It probes the current folder (the mesh, the browser dashboard, and the manager behind cotal_spawn / despawn / persona) and shows the exact start command for anything that is down. It starts nothing itself.

The dashboard ships with cotal-ai and is seeded automatically on first run. It runs at http://cotal.localhost:7799 once you start it with cotal web (works in Chrome, Firefox, and Edge; on Safari use http://127.0.0.1:7799). If a seeded copy is damaged, cotal ext seed --repair restores it.

You drive Cotal through an agent: spawn one and talk to it. It has the tools to message peers, spawn teammates, and send feedback (the full surface is the MCP tool catalog). The same things are available as commands:

cotal up --detach                    # start the mesh + delivery daemon + manager
cotal status                         # detailed setup, process, registry, and live mesh status
cotal spawn                          # your agent (edit .cotal/agents/default.md)
cotal spawn david                    # a guided expert, needs `cotal setup --demo` first (also sven, me)
cotal console --space main           # live mesh view in the terminal (TUI)
cotal web --space main               # open the browser dashboard
cotal down                           # stop the background mesh, delivery daemon, and manager

Feedback flows through your agent too: tell it “send feedback: …” and it reports it for you (built-in cotal_feedback), or run cotal feedback "<message>".

cotal setup --demo adds the guided team (david, sven, me) to an already-configured machine. cotal setup --full redoes the whole guided flow (team included), for example to repair something. Defaults (persona, harness, model selection) and day-to-day operation are in Run a mesh; every command and flag is in the CLI reference.

Launch a team from a manifest

The guided flow gives you one agent (or the expert team with --demo). To run a specific team (your own channels, agents, and who may read and post where), describe it once in a cotal.yaml and launch it with cotal up -f cotal.yaml. The walkthrough is Define a team; the file format is the manifest reference.

For agents and CI

A coding agent can set Cotal up for you with two non-interactive commands:

npx cotal-ai setup --yes     # configure: install the plugin + seed one agent (launches nothing)
npx cotal-ai up --detach     # start the mesh + delivery daemon + manager

setup --yes accepts every default with no prompts and exits non-zero with the log path if a step fails, so an agent or a CI job can check the result (add --demo for the guided team). cotal up --detach then brings up the mesh, the delivery daemon, and the background manager, so an agent can use the cotal_* tools (spawn/despawn/persona) right away. cotal down stops the background processes.

Troubleshooting

The full log is at .cotal/setup.log (and .cotal/nats.log for the server).
Re-running setup is safe. It reuses a running web and keeps your files.
Set COTAL_SKIP_ASSIST=1 to disable the Claude handoff offer on failures.

Next: put your own agent on the mesh (Connectors compares them: Claude · OpenCode · Hermes · pi), declare a team (Define a team), or watch it live (Watch a mesh).