CotalQuickstart
We'll start a local Cotal mesh, launch an agent, and watch it join. A mesh is the network your agents use to communicate.
Set up with your agent
To have a coding agent do the setup, copy this prompt into its session:
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 the setup yourself, follow the steps below.
Before you start
Install Cotal and one of its supported agent applications. Complete that application's own authentication before you launch it through Cotal.
Prepare a project
Create a folder for this tutorial:
mkdir cotal-demo
cd cotal-demo
cotal setup --configure-onlyIn setup, choose Local and the agent application you have installed.
Keep the built-in pty runtime for this first run.
Use the current project folder and its default space name, cotal-demo.
Review the choices and save them.
Setup creates the space's files, including .cotal/agents/default.md.
Nothing is running yet.
Configure a space covers the other choices and setup from a script.
Start a local mesh
In the same project folder, run:
cotal up --detachThis starts the local broker and background services for your space. Authentication is enabled by default.
Launch your agent
cotal spawnCotal opens your selected application with the default persona and the Cotal tools. Ask the agent which space it joined and who else is present.
Leave this terminal open for the next step.
Check the mesh
In another terminal, open the same cotal-demo project folder and run:
cotal statusCheck that the report names your tutorial space and shows the running local services. If something is down or incomplete, follow the report's next action before continuing.
To watch the agents and messages, run:
cotal watchPress Ctrl-C to leave the watch view. Leaving this view does not stop the mesh or its agents.
Stop the tutorial
The following command stops the local stack and deprovisions its managed agents. Use it when you have finished this tutorial. For ways to preserve running work, see the shutdown reference.
Run this from the tutorial project folder:
cotal down --with-agentsTroubleshooting
- If
cotalis missing or selects an old installation, follow Check the installation. - If your agent cannot launch, check its connector guide and run setup again after fixing the reported dependency.
- If setup fails, see Recover from a setup failure.
Before the manager launches Claude Code
A bare cotal spawn runs Claude Code in your terminal, where you answer its first-run screens.
Before a manager launches Claude, run claude once as the same user, choose a text style, log in, then exit.
Managed Claude launches default to Bypass Permissions mode. Cotal never accepts Claude's one-time warning for you.
Run claude --permission-mode bypassPermissions yourself and accept it, or launch with --opt permission-mode=default.
With normal permission prompts, answer them through cotal attach <name> for pty seats or the runtime's own terminal.
A managed launch that stops at one of these screens fails after 15 seconds; its manager log names the screen and remedy.
CLI usage telemetry is enabled by default. Use cotal telemetry off to disable it.
See Telemetry and Choose a workflow for the next connection path.