Configuration¶

SuperQode uses two complementary configuration files:

• superqode.yaml stores project defaults, provider hints, ACP agent definitions, MCP servers, aliases, and gateway settings.
• HarnessSpec files such as harness.yaml store run behavior: runtime, model policy, tools, sandbox, approvals, checks, hooks, events, and output.

Most developers can start with superqode config init, then run :local init inside the TUI to generate superqode.local.yaml for the machine they are using.

Why There Are Two Files¶

superqode.yaml answers: what is configured for this project or machine?

Use it for provider definitions, API key environment variable names, local endpoints, MCP servers, memory providers, aliases, and default connection hints. It is created by:

superqode config init

harness.yaml answers: how should this agent run behave?

Use it for the runtime backend, model policy, tool access, sandbox, approvals, checks, hooks, workflow, events, and output contract. It is created by commands such as:

superqode harness init my-coder --template coding --output harness.yaml
superqode local init --repo .

superqode.local.yaml is also a HarnessSpec. It is the local-first harness generated by :local init or superqode local init --repo ..

The files compose at runtime. A harness can say which model family, runtime, tools, and approval policy to use. superqode.yaml supplies the project environment around it, such as provider endpoints, MCP servers, memory configuration, and project defaults. A harness is not active just because it exists. Load one with superqode --harness harness.yaml, superqode --harness superqode.local.yaml, or :harness <path> inside the TUI.

Create Project Config¶

cd /path/to/project
superqode config init

SuperQode looks for config in this order:

Minimal Config¶

For the local-first default:

superqode:
  version: "1.0"
  team_name: "My Project"

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

providers:
  ollama:
    base_url: http://localhost:11434
    recommended_models:
      - qwen3:8b
      - qwen3-coder:30b-a3b
      - gemma4:e4b

For a hosted provider:

superqode:
  version: "1.0"
  team_name: "My Project"

default:
  mode: byok
  provider: openai
  model: <openai-model>

providers:
  openai:
    api_key_env: OPENAI_API_KEY
    recommended_models:
      - <openai-model>
      - <openai-fast-model>

For an ACP agent:

superqode:
  version: "1.0"
  team_name: "My Project"

default:
  mode: acp
  agent: opencode

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

coding_agent is still accepted for compatibility, but new config should use agent for ACP defaults.

Add A Harness¶

Create a reusable harness when you want the same runtime, tool, sandbox, and approval policy across runs:

superqode harness init my-coder --template coding --output harness.yaml
superqode harness doctor --spec harness.yaml
superqode harness run --spec harness.yaml --prompt "summarize this repository"

Load the same harness in the TUI:

superqode --harness harness.yaml

Or from inside the TUI:

:harness harness.yaml
:harness status

Common Config Commands¶

superqode config init
superqode config init --force

Harness commands:

superqode harness list-templates
superqode harness validate --spec harness.yaml
superqode harness inspect --spec harness.yaml
superqode harness compile --spec harness.yaml --json

Provider Settings¶

Providers are configured by ID. API keys should be stored in environment variables, not in YAML.

providers:
  anthropic:
    api_key_env: ANTHROPIC_API_KEY
    recommended_models:
      - <anthropic-model>

  google:
    api_key_env: GOOGLE_API_KEY
    recommended_models:
      - gemini-flash-latest

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

Check setup:

superqode providers doctor
superqode providers doctor openai --json
superqode providers guide ollama
superqode providers recommend coding

MCP Servers¶

Use mcp_servers for Model Context Protocol servers:

mcp_servers:
  filesystem:
    transport: stdio
    enabled: true
    auto_connect: true
    command: npx
    args:
      - -y
      - "@modelcontextprotocol/server-filesystem"
      - "."

SuperQode also accepts mcpServers for compatibility with common MCP config formats.

Environment Variables¶

What Belongs Where¶

Next Steps¶

• YAML Reference
• MCP Configuration
• Harness System
• Provider Guide