Connection Methods and Vendors¶

SuperQode provides six connection and interoperability methods: Local, ACP, MCP, A2A, BYOK, and SDK runtimes. The :connect screen does not open on those methods, because a method is a transport rather than a decision. It opens on one question, who should run the coding loop, in three answers: use an agent someone else built, run a SuperQode harness on a model you choose, or build a harness for this repository. The methods above are how each answer is carried out, and every vendor-specific command remains available for direct selection.

Start With The Outcome¶

SuperQode has three related selectors:

For a first session, run superqode, choose :connect, and start coding. Use :harness when you want another agent or run contract. Building a custom HarnessSpec is a later step.

Harness Choices¶

The Harness Switcher is the centralized inventory for runnable harnesses:

:harness
:harness all
:harness current

Switching can preserve the current conversation or fork an independent branch:

:harness switch workbench
:harness switch qwen-code --fork
:sessions switch

Connection Methods¶

Harness Protocol is also supported for portable harness import and export. It defines harness artifacts rather than an intelligence connection.

TUI Connection Picker¶

Open the complete product-level picker:

:connect

The root screen has three options, agents, models, and build, one per rung of the ownership ladder. Open any of them directly:

:connect agents
:connect models
:connect build

Above the options, the root screen lists what it detected on this machine: installed agents, running local engines, API keys already in the environment, and agent configuration files in the repository. Nothing has to be read first to find out what is usable here.

The existing-harness screen stays short by offering three categories: agent-subscriptions, agent-acp, and other-harnesses. The subscription screen keeps vendors in a stable order and shows the remaining setup directly for the highlighted row. Other rows remain one-line choices. This prevents row numbers from moving between machines while keeping installed and unavailable routes clear without turning the picker into a catalogue page.

:connect agent-subscriptions
:connect agent-acp
:connect other-harnesses

Each vendor row also carries badges for harness licence, model openness, and transport, for example open harness, open weights, ACP. These are two independent facts rather than one category: Codex ships an Apache-2.0 harness that drives only OpenAI models, and Factory Droid is a closed harness that runs whatever model you bring.

Row numbers are screen positions. The displayed number, arrow-key highlight, mouse target, and typed number always select the same row. Named shortcuts such as :connect codex remain stable regardless of row position.

When SuperQode owns the loop, the harness step is also directly addressable:

:connect harness-core
:connect harness-workbench
:connect harness-presets
:connect harness-repo

The models screen holds the three routes where SuperQode owns the tool loop:

:connect local
:connect byok
:connect plan

:connect plan covers subscriptions that expose a model endpoint, so a plan you already pay for can drive a SuperQode harness instead of the vendor agent. Its direct routes are plan-zai, plan-grok, plan-copilot, plan-moonshot, plan-qwen, plan-opencode, plan-ollama-cloud, plan-deepseek, and plan-minimax, each used as :connect <route>.

:connect plan-zai
:connect plan-grok
:connect plan-copilot
:connect plan-moonshot
:connect plan-qwen
:connect plan-opencode
:connect plan-ollama-cloud
:connect plan-deepseek
:connect plan-minimax

The build screen leads with importing, because a repository that already has agent configuration does not need to author anything:

:connect build-import
:connect build-preset
:connect build-wizard
:connect build-blank

Imported and cloned specs are written into the repository as YAML, so they are versioned, reviewable, and evaluable like any other source file.

:connect agents opens the vendor submenu. Every product on it is also a direct profile, so the submenu never becomes a required step:

:connect codex
:connect cursor
:connect amp
:connect antigravity
:connect grok
:connect copilot
:connect devin
:connect droid
:connect kiro
:connect glm-cli
:connect qwen-code
:connect kimi-code

Only vendor-plan and vendor-managed sign-in routes appear in this submenu. API-key-only routes remain under :connect byok; transport alternatives such as the Copilot CLI remain in the ACP picker.

Optional non-ACP harness integrations sit at the bottom of the same screen:

:connect other-harnesses

Pre-ladder names still resolve, so muscle memory and older documentation keep working. :connect subscriptions lands on the vendor subscription screen, and :connect local, :connect byok, and :connect acp go straight to their screens without passing through the root question.

The root picker is intentionally shorter than the full catalogs. Inside the TUI, :explore shows every capability category with its live state on this machine, and :tour shows the ownership ladder with each rung ticked off as you complete it. The following commands show the same authoritative inventory from the shell:

superqode agents list --protocol acp
superqode providers list
superqode runtime list

Named Product and Vendor Routes¶

Several vendors can be reached through more than one method. Choose the route that matches the account, runtime, and harness ownership required for the task.

Product names in this table identify connection paths, not bundled subscriptions. Authentication and usage terms remain controlled by each vendor.

ACP Coding Agents¶

ACP connects SuperQode to an external coding-agent harness. The agent manages its own model calls and can expose file editing, shell execution, MCP tools, and agent-specific commands. SuperQode supplies the terminal interface, session switching, harness selection, policy controls, and normalized events supported by the adapter.

Open the ACP picker:

:connect acp
:connect acp enterprise
:connect acp all

The default view contains installed and featured agents. The all form opens the complete live registry.

Connect directly:

:connect acp opencode
:connect acp poolside
:connect acp glm

The bundled offline catalog contains the following agents. The all picker can also include additional entries from the official ACP registry and user definitions.

Inspect installation and authentication requirements:

superqode agents show poolside
superqode agents doctor poolside
superqode agents doctor poolside --live

See ACP Agents for registry behavior, configuration, and protocol details.

BYOK Providers¶

BYOK connects SuperQode directly to a hosted model API. API keys are read from environment variables or SuperQode's local credential store. Secrets do not need to be placed in a HarnessSpec.

:connect byok
:connect byok openai <model>
:connect byok anthropic <model>

The built-in provider registry contains these hosted routes:

grok-cli is an authenticated subscription route used by :grok api; it is not an API-key BYOK provider.

Check provider setup and discover current models:

superqode providers list
superqode providers doctor openai
superqode providers guide openai
superqode models --provider openai

Model lists change more frequently than released documentation. The authoritative current inventory is the in-product catalog:

superqode models
superqode models --provider <provider>
superqode providers list

The picker combines curated built-in routes with live discovery where a provider exposes it. Harness model policy can then pin a primary model and fallbacks without changing the connection documentation.

See BYOK Providers for API-key variables and detailed provider configuration.

Local Providers¶

Local mode connects to a server running on the current machine or on private infrastructure.

Open the local picker or select a provider directly:

:connect local
:connect local ollama qwen3:8b
:connect local ds4 laguna-s-2.1

See Local Providers for setup, server lifecycle, model selection, and hardware guidance.

SDK Runtimes¶

SDK runtimes embed or call a vendor execution engine while preserving SuperQode's terminal, sessions, approvals, plans, and evidence surface.

List the installed runtime adapters:

superqode runtime list

See Runtime Backends for optional dependencies, event normalization, and runtime capability differences.

MCP Tool Connections¶

MCP connects tools and resources to a SuperQode harness or to an ACP agent that accepts MCP server definitions. MCP does not select a model.

:mcp
:mcp list
:mcp doctor

Project and user MCP configuration can be stored in:

.superqode/mcp.json
~/.superqode/mcp.json
~/.config/superqode/mcp.json

Enabled MCP servers are passed to compatible ACP sessions during session/new. Restart the ACP session after changing MCP configuration.

See MCP Configuration for transports and configuration. See MCP Command for the harness server interface.

A2A Agent Connections¶

A2A connects remote agents through Agent2Agent cards and task endpoints. It is used for remote delegation and agent-provider integration rather than direct model selection.

:a2a connect http://localhost:8000
:a2a discover http://agent:8080
:a2a call myagent "Review the authentication module"

See A2A Protocol for provider configuration, authentication, task lifecycle, and streaming.

Connection Method Versus Harness¶

A connection chooses the model, external agent, provider, or runtime. A HarnessSpec defines the controls applied to work:

• context and memory
• tools and skills
• model and runtime policy
• evaluation and acceptance gates
• budgets and permissions
• workflow and optimization settings

Switching a connection does not delete saved sessions or HarnessSpecs. Use :sessions to resume a session and :harness to list or switch harnesses.

Safety and Diagnostics¶

Connection alone does not grant capabilities. Effective access comes from the active runtime, harness, provider, agent, and approval policy.

Use the relevant doctor command before important work:

superqode providers doctor openai
superqode agents doctor opencode --live
superqode harness doctor --spec harness.yaml

Review Safety and Permissions before enabling shell or write access in important repositories.

Related Documentation¶

• Authentication
• Provider Configuration
• ACP Agents
• BYOK Providers
• Local Providers
• Runtime Backends
• Harness System