Using goose with SoAI

goose can route its OpenAI-compatible model requests through SoAI and can load SoAI as a remote Streamable HTTP extension.

Connect the model API

  1. In the SoAI WebUI, select the Settings button at the right of the header, choose Settings, and open OpenAI. This tab appears only to an Administrator with API key management (OPENAI_API_ADMIN). Select Create key and copy the key when it is shown.
  2. For tools, open MCP > MCP tokens. The MCP tab appears only to an Administrator with MCP administration (MCP_ADMIN), and creating a personal token also requires MCP usage (MCP_USE). Changing server mode or exposed tools also requires Configuration changes (CONFIG_PATCH).
  3. Open Models and copy an exact Chat Completions model ID with tool-calling support. This requires Model read access (MODEL_READ).

Configure the model provider

Select the OpenAI provider in goose configure. Set its host to the SoAI origin and its base path to v1/chat/completions. The equivalent environment and configuration are: 

export OPENAI_API_KEY='YOUR_SOAI_API_KEY'
export OPENAI_HOST='https://SOAI_HOST:5090'
export OPENAI_BASE_PATH='v1/chat/completions'
export SSL_CERT_FILE='/path/to/ca-bundle-containing-soai.pem'
active_provider: openai
providers:
  openai:
    enabled: true
    model: YOUR_MODEL_ID
    configured: true

Start a session and send a short prompt. goose distinguishes OPENAI_HOST from OPENAI_BASE_PATH; a wrong path normally produces a 404.

Connect goose Desktop to the SoAI model API

  1. Open the sidebar, select Settings, then open the Models tab.
  2. Select Configure providers, choose OpenAI, and enter the SoAI API key.
  3. Set Host URL to https://SOAI_HOST:5090. goose uses the default v1/chat/completions base path.
  4. Submit the provider, select Switch models, choose Use custom model, and enter YOUR_MODEL_ID.

The model name at the bottom of goose Desktop is a shortcut to Change Model. The desktop process must trust the SoAI CA before provider verification can succeed.

Connect MCP tools

Merge this entry into ~/.config/goose/config.yaml:

extensions:
  soai:
    type: streamable_http
    name: soai
    description: SoAI MCP
    enabled: true
    uri: https://SOAI_HOST:5090/mcp
    headers:
      Authorization: "Bearer ${SOAI_MCP_TOKEN}"
    env_keys:
      - SOAI_MCP_TOKEN
    envs: {}
    timeout: 60
export SOAI_MCP_TOKEN='YOUR_MCP_TOKEN'
goose session

Verify the live connection by asking goose to list or use a harmless exposed read-only tool; a saved extension alone does not confirm a completed handshake.

Connect goose Desktop to SoAI MCP

  1. Open the sidebar, select Extensions, then select Add custom extension.
  2. Choose Remote Extension (Streamable HTTP), set the ID and name to soai, and set the URL to https://SOAI_HOST:5090/mcp.
  3. Add the request header Authorization with value Bearer YOUR_MCP_TOKEN, choose an appropriate timeout, and select Add.
  4. Confirm that the extension is enabled, then ask goose to use a harmless exposed SoAI tool.

goose stores a header entered in the Desktop form in its extension configuration. Treat that configuration as a secret and prefer the environment-referenced YAML form above on shared systems.

Related documentation