getting-started.md

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:

Read https://docs.cotal.ai/prompt.md, then set up Cotal on this machine: install it, start a local mesh, and put an agent on it.

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.

Start a local mesh

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.10+ 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. What it creates is not writable by group or other accounts, whatever your umask. 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.

Use the absolute launcher printed by the installer if plain cotal still selects an older installation. type -a cotal shows shell aliases, functions and executable candidates. The installer cannot change the current shell's cached command; refresh that cache after correcting PATH order. Do not follow an older executable's force-seed advice to repair command selection.

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

npm install -g cotal-ai   # puts `cotal` on your PATH
cotal setup --configure-only  # save preparation; start the space separately

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 names the selected space and the common commands; 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.

The CLI sends usage telemetry by default. Run cotal telemetry off to disable it, or read Telemetry for the fields and other settings.

Requirements:

• Node 22.10 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.
• On Linux, a glibc system. Cotal's Linux terminal binaries target glibc, 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, and cotal up refuses one older than 2.12, naming its path and version. One in a folder other accounts can write, such as a Homebrew install on macOS, gives way to the one that ships with the package. cotal status shows which one Cotal will run. A presence bucket created file-backed by an older Cotal needs 2.14.5 or newer, and cotal up names the broker when it is older. Cotal now creates that bucket in memory, which needs no newer broker.

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 prepares a space before a separate startup decision. Use --configure-only for this guide's manual startup sequence. The guided flow asks five questions and shows your answers before it writes anything:

1. Where your space runs. Local is a space this machine starts. Self-hosted is a space that runs on a server and is registered here, with cotal space add or from a connection file the space's operator gives you. Cloud cannot be chosen: sign in with cotal login, which registers your Cloud spaces here, then choose Self-hosted and pick one.
2. Which application your agents run in. Every installed connector is a choice, and its hint comes from the connector itself: one that declares its own setup runs it (Claude installs its plugin that way), and one whose executable is not on PATH is named. Setup records your choice as the space's harness preference, so a bare cotal spawn in that space launches it.
3. Which runtimes your agents run in. pty is built in and always set up. Each other runtime (tmux, cmux, orca, herdr, and any third-party one you installed) shows whether it is set up and whether its tool is on PATH. Installed ones and ones whose tool was found start selected. Setup installs the ones you keep and checks that each answers; it never removes one you leave out.
4. The project folder. The space's root. Its .cotal/agents holds the space's personas. Setup offers to create a folder that does not exist yet.
5. The space name. For a local space it defaults to the folder's name.

Save writes the answers, Change asks again with your answers kept, and Cancel saves nothing. Without --configure-only, successful preparation asks separately whether to start, and only a typed y or yes starts it. --start requests it directly; scripts also need --detach. A denied or uncertain start keeps completed preparation saved and names the unmet startup stage. Setup then seeds one agent: the generic default persona that a bare cotal spawn launches, in the project's .cotal/agents. Edit it to taste. It joins no channels at boot, but may join, create, read, and post to channels on demand. It declares capabilities: [spawn, run], so it can manage teammates and start durable workflows through cotal_run on a static-auth mesh. 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.

Re-running setup after an upgrade repairs the earlier untouched default template that had an empty post ACL. The repair requires a byte-for-byte match, so any persona you edited is left unchanged. A default that already has wildcard post access and only spawn also stays unchanged. To enable workflows for an existing persona, follow the capability update steps. Run via npx with no global cotal, setup also offers to npm i -g cotal-ai so you can just type cotal. The dashboard needs no install: @cotal-ai/web ships inside cotal-ai.

With --configure-only, setup leaves the space stopped and prints the next commands. If you accepted its startup offer, use cotal status to inspect that launch before starting another agent. For manual startup, run:

cotal up --detach          # start the mesh + delivery daemon + manager (JWT-authed by default)
cotal spawn                # run your agent in this terminal and talk to it (Ctrl-C to leave)
cotal watch                # watch live mesh observations in the terminal
cotal down                 # stop everything

Before the manager launches Claude Code

A bare cotal spawn runs Claude Code in your terminal, where you answer its first-run screens yourself. An agent the manager launches (cotal spawn --detach, cotal_spawn or cotal up -f) has nobody at its terminal, and Cotal does not answer those screens. Do Claude's first run once beforehand: run claude in a terminal as the same user, pick a text style, log in, then exit.

A managed Claude agent runs in Bypass Permissions mode, which Claude asks each user to accept once. Cotal never accepts it for you. Pick one route:

• Keep Claude's normal prompts: launch with --opt permission-mode=default, or in a manifest give the agent launchOptions: {permission-mode: default}. The agent joins without the warning. Tool calls that need permission, including mesh tools you have not approved, wait at its terminal until you answer them there: cotal attach <name> on the built-in pty runtime, or the agent's window in the runtime's own app, such as tmux attach-session -t cotal-<space> for tmux.
• Accept it yourself: run claude --permission-mode bypassPermissions in a terminal and choose Yes, I accept.

A managed launch that stops on one of these screens fails after 15 seconds, and the manager's log under .cotal/ names the screen and the step that clears it.

The dashboard ships with cotal-ai, but its service definition and explicit credential are configured separately. See Watch a mesh for its supported scope. cotal console also provides the terminal TUI. Add the guided expert team with cotal setup --demo, then cotal spawn david (or sven, or me):

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. A bare cotal spawn runs the agent in your terminal and needs no manager. 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> --full (all channels, scope spawn,role:default so it may spawn and may delegate the default role; for a narrow row, name --scope, --allow-subscribe and --allow-publish instead of --full), 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 four commands, which every other page builds on:

Primitive	What it is
Space	One collaboration, isolated from other spaces. Your mesh is a space.
Endpoint	A connected participant; agents publish presence, while invisible observers can opt out.
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

cotal status shows what is set up and running: the machine, its processes, the spaces it knows, and the start command for anything that is down. It starts nothing itself. Running cotal setup again with the same answers changes nothing. Another space needs no second setup: cotal space create <name> in another folder prepares it with the default persona and your application, and cotal up there starts it.

The dashboard is a separately configured owned service. Its default bind is loopback port 7799; its private single-use browser link is kept in the original launch's owner-private session record, not printed into logs. Follow the dashboard setup before starting it. Starting an absent service never installs its extension or creates a caller credential.

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 service start web --space main # only after explicit dashboard definition/credential setup
cotal console --space main           # the same live view as a TUI in the terminal
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 with the same answers adds the guided team (david, sven, me) to a space you already set up. 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.

Non-interactive setup

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

npx cotal-ai setup --destination local --harness claude --project . --space main --no-input
npx cotal-ai up --root . --space main --detach  # start this prepared project

Without a terminal, setup asks nothing, so every input is a flag; a missing one is refused before anything is written. A script sets up a runtime only when --runtime <name> names it. --json prints one result that lists every file setup wrote, and an application whose executable is not on PATH exits 4 with the rest saved, so an agent or a CI job can check the result (add --demo for the guided team). cotal up --root . --space main then starts from the prepared project even when another root is available above it. It brings up the mesh, delivery daemon and 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 preserves edited personas. Use --configure-only to avoid a startup offer; dashboard configuration and startup are separate.
• Set COTAL_SKIP_ASSIST=1 to disable the debug handoff offer on failures.

Next: Choose a workflow for existing sessions, hosted spaces, teams, services and durable runs. The connector matrix compares all supported applications.