Connection Methods and Vendors¶

SuperQode provides seven connection and interoperability methods: Local, ACP, UHP, 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
:harness switch uhp
:sessions switch

Connection Methods¶

The Protocols screen¶

ACP, A2A, and UHP all connect something that owns its own agent loop, so they share the fourth row of :connect:

:connect protocols

:connect a2a fetches the card and can send one message. Open cards need no token. The TUI screen takes Bearer, API key, HTTP Basic, OAuth, extra headers, and mutual TLS the same way the CLI does. A Bearer is never written into the card.

MCP is deliberately not on that screen. It extends whatever harness is already running rather than owning a loop, so it stays on :mcp.

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. Open and Closed rows add the SPDX licence to that line when SuperQode has verified it, so open harness · AGPL-3.0 and open harness · MIT are told apart without leaving the picker. A blank licence means unverified rather than absent, so no badge is drawn.

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-rlm
:connect harness-workbench
:connect harness-pipy
: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 muse
:connect grok
:connect copilot
:connect devin
:connect droid
:connect kiro
:connect glm-cli
:connect qwen-code
:connect kimi-code
:connect deepagents-code
:connect junie
:connect fx
:fx

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. Factory Droid's own key is a Closed harness (:connect droid-key), not a Subscriptions row and not SuperQode BYOK. Junie has both: :connect junie on Subscriptions and :connect junie-key on Closed.

The rest of the existing-harness screen depends on the connect menu flag (SUPERQODE_CONNECT_MENU or connect_menu in ~/.superqode/config.json). v1 (the compiled default) keeps Other harnesses. v2 replaces that row with Open harnesses and Closed harnesses:

:connect other-harnesses
:connect open-harnesses
:connect closed-harnesses
:connect letta
:connect warp

Under v2 the two category rows carry the same agent- prefix as the subscription and ACP rows, so every existing-harness category is selectable by its registry id as well as its short alias:

:connect agent-open-harnesses
:connect agent-closed-harnesses

Open is OSI-licensed harnesses on a key or local model. Closed is proprietary harnesses on that vendor's key. Setup-card rows such as Letta Code and Warp Agent are listed so you can find them; SuperQode does not start their loop from that row yet.

Eleven rows connect today. Tau, DeepSeek Harness, and DeepAgents switch to a SuperQode-hosted adapter and then run the model you choose. OpenCode, Grok Build, Qwen Code, Kimi Code, fast-agent, Pi, Prime Agent, and fx keep their own loop: the model step only decides which credentials they are handed, and SuperQode passes those to the agent process alone rather than exporting them into your shell. fx skips the model picker entirely and injects AI_GATEWAY_API_KEY into the child. Prime is reached over its Python RPC backend rather than ACP, so a local pick is registered in Prime's own models.json instead of being passed as an environment variable.

The remaining rows print a setup card naming the key or local model to configure in the harness itself. Every id in the table also works as superqode --connect <id> and completes in the TUI.

A key is only ever passed under a variable that is known to be read: the one the catalog records for that harness, or the provider's own documented variable for a model-agnostic agent. When you pick a local endpoint that neither names, the agent still attaches and SuperQode says the model has to be set inside it, rather than exporting an endpoint under a name the agent ignores.

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:

Factory (factory) is a harness-only credential slot for :connect droid-key (superqode auth login factory). It is not listed under :connect byok.

The grok-cli provider is an authenticated subscription route used by :grok api; it is not an API-key BYOK provider. The grok-cli runtime is the headless grok -p vendor loop (:runtime grok-cli).

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 SuperQode to a remote agent from its published Agent Card. The remote agent owns its execution contract.

:connect a2a
:connect a2a https://superqode.onrender.com
superqode connect a2a --url https://superqode.onrender.com --inspect
superqode connect a2a --url https://superqode.onrender.com --conformance

:connect a2a (and :connect → Protocols → A2A) opens a screen for the origin and the credential the card asks for: empty for anonymous, Bearer, API key, user:password for HTTP Basic, OAuth (browser or stored token), extra headers, and mTLS cert/key. OAuth opens a browser at http://localhost:19876/a2a/oauth/callback. Logout clears the stored token. Check runs four client checks: fetch, shape, binding, one task. Open cards need no token.

See A2A Protocol.

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