HHostingByteSoftware
Ctrl K
ComunidadGuías…

docs/connect-opencode.mdx

Rama main · réplica de lectura del repositorio original.

Archivo original ↗Preguntar a KiBot
---
title: "Connect OpenCode"
description: "Launch OpenCode on a Cotal mesh and choose the model and options for your installed version."
kind: "Guide (informative)"
audience: "operators"
---

import { Callout } from 'fumadocs-ui/components/callout';

Run OpenCode with its own terminal interface and the shared `cotal_*` tools.
The connector installs its plugin at launch and directs peer messages into the session you can see.
First [start a mesh](run-a-mesh.mdx).

<Callout type="warn" title="Beta connector">
Session resume and selected MCP-server sharing are unsupported.
Spawned OpenCode agents allow tool execution without approval and inherit the operator's configured MCP servers.
</Callout>

## Prepare OpenCode [#no-install-needed]

Install and authenticate `opencode` on the execution host using the [OpenCode documentation](https://opencode.ai/docs/).
Cotal recognizes the OpenCode 1.x `opencode-ai` line and the 2.x `@opencode/cli` line.
It rejects other major versions.

No OpenCode-side Cotal installation is needed.
The OpenCode choice in `cotal setup` records your preference, and the connector injects its plugin at launch.

## Launch OpenCode [#spawn-it]

Run from the space's project folder:

```bash
cotal spawn --harness opencode
```

A bare spawn runs OpenCode in this terminal. `--on <instance>` selects a manager and attaches when its runtime streams a terminal.
To launch a `researcher` persona without opening its terminal, add `--detach`:

```bash
cotal spawn researcher --harness opencode --detach
cotal ps
cotal attach researcher
```

For direct execution, add `--foreground` instead of `--detach`.
To select a persona file, use `--file ./researcher.md`.
You can also set `agent: opencode` in an [agent file](agent-files.mdx) or a [team manifest](manifest.mdx).
See [Launch agents](launch-agents.mdx) for persona selection and terminal controls.

## Choose a model [#choose-a-model]

Inspect the available catalog:

```bash
cotal models --harness opencode
```

On 1.x, add `--refresh` to refresh OpenCode's provider cache first.
On 2.x, the connector runs `opencode api --standalone GET /api/model`, which starts a private OpenCode server for that one request.

Choose a `provider/model` ID and, when the model offers variants, a variant from that listing:

```bash
cotal spawn --harness opencode --model <provider/model> --variant <variant>
```

You can also set `model:` and `variant:` in the agent file.
Explicit flags override those fields.
Before joining the mesh, the connector checks an explicit model against the server that will run the session.
A model visible only in the CLI catalog can still be refused.
Cold startup waits up to two minutes for the Cotal session, with five more seconds for the manager to receive a boot failure.
On OpenCode 1.19.5, a model-catalog lookup on a fresh home can leave dependency-install locks that OpenCode recovers after about a minute.
Each launch keeps its server boot output in `<workspace>/.cotal/opencode/<name>/boot.<token>.log`, including failed launches.
If startup fails, read that log on the execution host, correct any setup error, then launch again.

## Work in the session [#how-it-binds]

Type in the attached OpenCode TUI to use the same session that receives mesh messages.
On OpenCode 1.x, use `/new` to reset the context while keeping the mesh identity.
On 2.x, keep mesh work in the launched session because the connector does not follow `/new` into a new session.
To rebuild a wedged mesh connection from OpenCode, use `/reconnect`.

The connector injects configuration through `OPENCODE_CONFIG_CONTENT` without writing your global config.
This configuration merges with your existing settings, including MCP servers.
Each managed agent stores its session database under `<workspace>/.cotal/opencode/<name>/`.
See the [OpenCode connector reference](opencode-connector-reference.mdx) for configuration, message delivery, and shutdown behavior.

## Watch structured events [#event-plane]

OpenCode publishes run boundaries, assistant text, and tool activity to `events.<owner>.<actor>` by default, on 1.x and 2.x.
It excludes user text, tool arguments, and tool results.
Reasoning publication is off by default.
On 2.x it publishes the session the connector launched, and a session started with `/new` is not published.
Use [Watch a mesh](watch-a-mesh.mdx) to observe agents and the [event reference](opencode-connector-reference.mdx#event-plane) for the stream's limits.

On a space that permits opting out, add `--no-events` to disable publication.

## Check the limits [#limits]

- Session resume and exact-session continuation are unsupported.
- `connectors.opencode.mcpServers` is unsupported. Agents inherit the operator's MCP servers through the config merge, without a Cotal filter for selecting a subset.
- Spawned agents use `permission: "allow"`. Tool calls do not wait for human approval.
- OpenCode 2.x has no `/new` session handoff.

## Continue [#see-also]

- [Connector comparison](connectors.mdx)
- [Define a team](define-a-team.mdx)
- [MCP tools](mcp-tools.mdx)
- [OpenCode connector reference](opencode-connector-reference.mdx)
- [Connect Codex](connect-codex.mdx)
- [Deploy against an external broker](deploy.mdx)