Configure a space

Use setup to choose where a space runs, which agent application it uses, and where its project files live. Setup saves those choices without starting the space. Choose startup separately after preparation.

Prepare a space interactivelyCopy Anchor Link

Run this from the project folder:

cotal setup --configure-only

Set these choices in the guided flow:

1. Destination. Local means this machine starts the space. Self-hosted means the space runs elsewhere and is registered here. Register it with cotal space add or provide a connection file from its operator. Cloud cannot be selected here. Run cotal login, then choose Self-hosted and select the registered Cloud space.
2. Agent application. Choose an installed connector. Setup runs the connector's own setup steps when its application is available. This choice becomes the space's harness preference, which a bare cotal spawn uses.
3. Runtime. Keep the built-in pty runtime for a first run. Other choices include tmux, cmux, orca, and herdr. Setup shows installed tools and checks the runtimes you select. Leaving a runtime out does not uninstall it.
4. Project folder. This is the space's root. Agent personas live in its .cotal/agents directory. Setup can create a missing folder.
5. Space name. A local space defaults to the project folder's name.

Review the choices before saving. Choose Change to edit them or Cancel to save nothing. With --configure-only, setup does not start a process. Continue with the Quickstart after preparation.

Without --configure-only, successful interactive setup offers to start the space and open the default agent. Only a typed y or yes starts it. An incomplete or uncertain startup leaves preparation saved and reports the stage that needs attention. Inspect that outcome before trying to start again.

Automate setupCopy Anchor Link

A script must supply every required choice as a flag:

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

The first command prepares the current folder for the main space. The second starts that prepared project, even if another mesh root exists above it. Replace claude with your connector's name. The application it needs must be installed and authenticated.

A missing required flag is refused before setup writes anything. Scripts set up only the optional runtimes named with --runtime <name>. Add --json to get a result whose written list names the files setup wrote. If an application executable is missing, setup saves the other preparation and exits with code 4. Fix the missing dependency, then run the same setup again.

To request startup and launch the default agent from setup, use --start --detach. Scripts must include --detach with --start. For the full flag and result contracts, see the setup reference.

Customize the default agentCopy Anchor Link

Setup creates .cotal/agents/default.md in the project folder. Edit that file to change the persona's instructions, name, or role.

A fresh default agent joins no channels at boot. Its permissions let it join, create, read, and post to channels when needed. It also declares spawn and run capabilities, so it can manage teammates and start workflow runs on a static-auth mesh. See Agent files for the fields and Workflow runs for workflows.

Add the guided teamCopy Anchor Link

To add Cotal's demonstration personas to this space:

cotal setup --demo

Use the same project and space choices as before. The command adds david, who explains Cotal, sven, who discusses what to build, and me, a session for you to drive. Start a prepared local space if it is not running, then launch one of the personas:

cotal spawn david

To define your own team, follow Define a team.

Update preparationCopy Anchor Link

Running setup with the same choices is safe. It reports an existing prepared, started, or registered space and preserves your edited default persona. A project root or space name held by a different space is a conflict.

To create another local space, run cotal space create <name> in its own project folder. You do not need to repeat machine setup. See Run a mesh for defaults and space selection. Its startup instructions also cover unauthenticated development spaces. For per-user sign-in and agent grants, follow Identity.

If you use npx without a global installation, interactive setup can offer to install cotal-ai globally. Declining keeps subsequent command hints in npx cotal-ai form. The background services use their own resolved executable path.

The browser dashboard ships with Cotal but needs a separate service definition and credential. Follow Watch a mesh before starting it. It binds to loopback port 7799 by default. Its private browser link stays in the launching session's private record and is not printed in logs. The terminal console is available through cotal console.

Recover from a setup failureCopy Anchor Link

Read the reported failure before trying setup again. The setup log is <project>/.cotal/setup.log. The local broker log is <project>/.cotal/nats.log.

On an interactive terminal, setup may offer a debug session through an available connector. Exit that session to return to setup. Set COTAL_SKIP_ASSIST=1 to disable these offers.

Run cotal status to inspect saved preparation and running services. It does not start anything. For commands, flags, and exit codes, see the CLI reference.

Next stepsCopy Anchor Link