# Quickstart

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:

```text wrap
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](/docs/installation/) and one of its supported [agent applications](/docs/connectors/).
Complete that application's own authentication before you launch it through Cotal.

## Prepare a project

Create a folder for this tutorial:

```bash
mkdir cotal-demo
cd cotal-demo
cotal setup --configure-only
```

In 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](/docs/setup/) covers the other choices and setup from a script.



## Start a local mesh

In the same project folder, run:

```bash
cotal up --detach
```

This starts the local broker and background services for your space.
Authentication is enabled by default.



## Launch your agent

```bash
cotal spawn
```

Cotal opens your selected application with the default persona and the [Cotal tools](/api-reference/mcp-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:

```bash
cotal status
```

Check 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:

```bash
cotal watch
```

Press Ctrl-C to leave the watch view.
Leaving this view does not stop the mesh or its agents.



## Stop the tutorial

> **Warning**
>
> 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](/api-reference/cli-shutdown/#down).



Run this from the tutorial project folder:

```bash
cotal down --with-agents
```



## Troubleshooting

- If `cotal` is missing or selects an old installation, follow [Check the installation](/docs/installation/#check-the-installation).
- If your agent cannot launch, check its [connector guide](/docs/connectors/) and run setup again after fixing the reported dependency.
- If setup fails, see [Recover from a setup failure](/docs/setup/#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](/docs/telemetry/) and [Choose a workflow](/docs/using-cotal/) for the next connection path.

## Next steps

[Define a team](/docs/define-a-team/)

Choose several agents and their channels in one file.



[Connectors](/docs/connectors/)

Set up another agent application.



[Examples](/docs/examples/)

Try a complete example.



[Run a mesh](/docs/run-a-mesh/)

Manage spaces, agent defaults, and day-to-day operation.