Connection Modes¶

SuperQode connects to intelligence in four ways: ACP agents, BYOK providers, local model servers, and vendor SDK runtimes. The connection mode decides where model work happens and who owns the agent loop. A harness decides what capabilities are allowed during a run.

Overview¶

Start from the TUI:

:connect

Direct examples:

:connect acp opencode
:connect byok openai gpt-4o-mini
:connect local ollama qwen3:8b
:connect codex
:connect claude

CLI equivalents:

superqode connect acp opencode
superqode connect byok openai gpt-4o-mini
superqode connect local ollama qwen3:8b
superqode --runtime codex-sdk --print "review this repo"

ACP¶

ACP mode connects SuperQode to an external coding agent. The agent manages its own model calls and may expose file editing, shell execution, MCP tools, and agent-specific slash commands.

Use ACP when:

• you want a full coding agent rather than a direct model call
• the agent already has its own auth and provider setup
• you want SuperQode's TUI, sessions, exports, and command surface around that agent
• you need agent-owned MCP or shell behavior

Common commands:

superqode agents list
superqode agents show opencode
superqode agents doctor opencode
superqode agents doctor opencode --live
superqode connect acp opencode

Example config:

default:
  mode: acp
  agent: opencode

agents:
  opencode:
    description: OpenCode coding agent
    protocol: acp
    command: opencode

coding_agent is still accepted for older configs, but new config should use agent.

BYOK¶

BYOK mode connects to hosted providers with your own API keys. SuperQode reads keys from environment variables and does not require secrets in YAML.

Use BYOK when:

• you want direct access to hosted models
• you need model comparison or provider switching
• you want API-key-based automation
• you want cost and model metadata where available

Set an API key:

export OPENAI_API_KEY=your-key
export ANTHROPIC_API_KEY=your-key
export GOOGLE_API_KEY=your-key

Connect:

:connect byok openai gpt-4o-mini

Check setup:

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

Example config:

default:
  mode: byok
  provider: openai
  model: gpt-4o-mini

providers:
  openai:
    api_key_env: OPENAI_API_KEY
    recommended_models:
      - gpt-4o-mini
      - gpt-4o

Local¶

Local mode connects to model servers running on your machine or infrastructure.

Use local mode when:

• repository contents should stay on your machine
• you want no per-token API cost
• you are evaluating local coding models
• you need offline or self-hosted workflows

Supported local provider paths include Ollama, LM Studio, MLX, vLLM, SGLang, TGI, and DS4 where installed and configured.

Ollama example:

ollama serve
ollama pull qwen3:8b
superqode providers doctor ollama --live

Connect:

:connect local ollama qwen3:8b

Example config:

default:
  mode: local
  provider: ollama
  model: qwen3:8b

providers:
  ollama:
    base_url: http://localhost:11434
    recommended_models:
      - qwen3:8b

Local tool support depends on the model family and provider. SuperQode has model-family policies for known local models and can fall back to no-tool or reduced-tool operation when a model cannot reliably call tools.

Connection Mode Versus Runtime¶

Connection mode answers: "What product, provider, agent, or local server am I connected to?"

Runtime answers: "Which execution engine runs the harness?"

Examples:

See Runtime Backends for backend details.

SDK runtimes¶

SDK mode runs a vendor's own agent engine inside SuperQode. You keep SuperQode's TUI, sessions, approvals, plan surface, and exports, while the vendor SDK owns the model calls and its native behaviors.

Use SDK mode when:

• you already pay for a ChatGPT or Claude subscription and want to use it instead of per-token API billing
• you want a vendor's native agent behavior, but with SuperQode's readable sessions, exports, and approval policies around it
• you are comparing vendor agents against local models in one interface

superqode --runtime codex-sdk --print "summarize this repository"
superqode --connect claude --print "summarize the last change"

See Runtime Backends for the full runtime matrix.

Choosing A Mode¶

Safety Notes¶

Connection mode does not by itself grant capabilities. The effective capabilities come from the active runtime, harness, provider, and approval policy.

For repeatable safety, use a HarnessSpec:

superqode harness init planner --template no-tool --output planner.yaml
superqode harness init coder --template coding --output coder.yaml
superqode harness doctor --spec coder.yaml

Review Safety & Permissions before allowing shell or write access in important repositories.

Next Steps¶

• Authentication
• Provider Configuration
• Runtime Backends
• Harness System