> ## Documentation Index
> Fetch the complete documentation index at: https://runinfra.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Goose

> Configure Goose for RunInfra with a preview adapter and an environment credential handoff.

Configure Goose for RunInfra with a manual process-environment credential handoff.

Support level: `preview`.

<Note>
  This preview writes Goose's model and URL settings without changing the keyring or `secrets.yaml`. Set `OPENAI_API_KEY` in Goose's launch environment. Confirm the settings and request destination in a new Goose chat before relying on this preview.

  `on` requires `--preview`. Preview is not a dry run: it writes settings and sends a request using credits. Helper mode is the default; literal key mode is refused.
</Note>

## Connect Goose

Have Goose installed, a workspace API key, and available RunInfra credits.

```bash theme={"dark"}
npx @runinfra/connect goose --preview
```

The bare agent command is an alias for `on`. In an interactive terminal, Connect starts login if needed. Review and approve the proposed changes. Connect saves a snapshot, writes the configuration, and makes a real Chat Completions request that uses credits. Complete the environment handoff below before launching Goose.

To choose a model during setup:

```bash theme={"dark"}
npx @runinfra/connect goose on --model deepseek-v4-flash --preview
```

See [Connect](/docs/tools-sdks/connect) for status, diagnostics, and key replacement.

## What Connect writes

| Platform        | Connect's configuration target                                                             |
| --------------- | ------------------------------------------------------------------------------------------ |
| macOS and Linux | `~/.config/goose/config.yaml`, or `goose/config.yaml` inside an absolute `XDG_CONFIG_HOME` |
| Windows         | `%APPDATA%\Block\goose\config\config.yaml`                                                 |

Connect uses an absolute `GOOSE_PATH_ROOT` instead of those locations when set. It writes `config/config.yaml` inside that root. On Windows, Connect requires absolute `APPDATA` and `PROGRAMDATA` values for the default path and system-configuration check.

Connect sets `active_provider` to `openai`, enables and configures `providers.openai`, and sets its `model` to the selected catalog id. It writes `OPENAI_HOST: https://api.runinfra.ai` with `OPENAI_BASE_PATH: v1/chat/completions`. It does not combine that recipe with `OPENAI_BASE_URL`.

Connect writes only the selected model id. It does not add context or output metadata. Review system and additional configurations, command-line flags, process overrides, auxiliary model settings, and token limits before starting a new chat.

Connect could not confirm the `OPENAI_HOST`/`OPENAI_BASE_PATH` URL recipe, `GOOSE_PATH_ROOT` and `XDG_CONFIG_HOME` overrides, complete override and file precedence, OpenAI provider and model-id acceptance, or required model fields and optional limits against the current Goose documentation; check the [environment guide](https://goose-docs.ai/docs/guides/environment-variables), [provider guide](https://goose-docs.ai/docs/getting-started/providers/), and [multi-model guide](https://goose-docs.ai/docs/guides/multi-model/) before relying on it.

### Key placement

Helper mode is the default; pass the key through `OPENAI_API_KEY`. Connect leaves the keyring unchanged and does not put the key in Goose's YAML. You do not need to pass `--key-source helper` explicitly. Set `RUNINFRA_API_KEY` securely, then run this handoff in the environment that launches Goose:

<Tabs>
  <Tab title="macOS and Linux">
    ```bash theme={"dark"}
    export OPENAI_API_KEY="$RUNINFRA_API_KEY"
    ```
  </Tab>

  <Tab title="PowerShell">
    ```powershell theme={"dark"}
    $env:OPENAI_API_KEY = $env:RUNINFRA_API_KEY
    ```
  </Tab>
</Tabs>

A terminal-only assignment does not configure an already running app or a Start menu launch. Goose must receive `OPENAI_API_KEY` in its actual process environment.

Connect does not change the keyring, `secrets.yaml`, dotenv files, or shell profiles. Companion-secret groups, including custom headers, require manual review. Do not assume Goose automatically loads a dotenv file.

Goose ignores provider keys in `config.yaml`. `OPENAI_API_KEY` in the launching process takes precedence over stored secrets. Confirm it contains the intended key without printing it.

Connect could not confirm companion-secret resolution, missing or empty handoff values, keyring fallback details or automatic dotenv loading against the current Goose documentation; check the [environment guide](https://goose-docs.ai/docs/guides/environment-variables) and [configuration implementation](https://github.com/aaif-goose/goose/blob/main/crates/goose/src/config/base.rs) before relying on it.

## Verify

Connect's API probe does not prove Goose loaded the configuration or replaced an active chat. Confirm the settings and request destination in a new Goose chat.

After restarting, inspect settings locally with the diagnostic Connect names. Connect does not execute it:

<Tabs>
  <Tab title="macOS and Linux">
    ```bash theme={"dark"}
    goose info -v
    ```
  </Tab>

  <Tab title="PowerShell">
    ```powershell theme={"dark"}
    goose info -v
    ```
  </Tab>
</Tabs>

Do not share raw diagnostic output. It shows active settings and their values. This is not proof of authentication or request destination. Check a new chat separately in an authorized environment. Confirm the selected model and actual destination. Connect prints no automatic Goose request check.

## Restart

Fully restart Goose with `OPENAI_API_KEY` in its process environment. Start a new chat.

## Troubleshooting

| Symptom                                 | What to check                                                                                                                                                                      |
| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Literal mode is refused                 | Omit the key-source option to use the default helper mode, or pass `--key-source helper`. Complete the `OPENAI_API_KEY` handoff. Connect leaves the keyring unchanged.             |
| Connect refuses a URL or model override | Review `GOOSE_PROVIDER`, `GOOSE_MODEL`, `GOOSE_FAST_MODEL`, and companion `OPENAI_*` variables. Remove conflicting launch overrides before retrying.                               |
| Connect finds layered settings          | Review `GOOSE_ADDITIONAL_CONFIG_FILES` and `/etc/goose/config.yaml`, or `%PROGRAMDATA%\goose\config.yaml` on Windows. Connect refuses these competing layers without editing them. |
| Existing YAML is refused                | Review an existing `OPENAI_BASE_URL`, legacy selectors, inline credentials, and foreign OpenAI provider settings. Connect does not silently migrate them.                          |
| The API probe passes but Goose fails    | Check the actual process environment, saved selection, startup hooks, and request destination. A probe is not Goose activation proof.                                              |

Connect could not confirm BOM, duplicate-key, alias or flow-style trailing-comma handling, unknown-field acceptance, native comment preservation, concurrent saves, permissions or post-save restoration against the current Goose documentation; check the [configuration implementation](https://github.com/aaif-goose/goose/blob/main/crates/goose/src/config/base.rs) before relying on it.

## Revert

```bash theme={"dark"}
npx @runinfra/connect goose off
```

With intact state and snapshots, `off` restores the original bytes from before the first `on` in the active connection. If the managed file did not exist then, Connect removes it. Later `on` calls and key rotations keep that restore point.

If Goose or another editor changed the file, Connect refuses to overwrite it. Back up and review the edits before choosing to discard them:

```bash theme={"dark"}
npx @runinfra/connect goose off --force
```

Connect saves the current contents in a recovery snapshot and prints its id before restoring the origin. Keep the snapshots. If the origin snapshot is missing, review routing manually. Cleanup does not guarantee original-byte restoration or removal of the saved route. See [Connect recovery](/docs/tools-sdks/connect#what-off-restores).

Restore the previous `OPENAI_API_KEY` process environment yourself. File restoration does not undo manual environment or keyring changes.

## Related

<Columns cols={3}>
  <Card title="Connect" icon="plug" href="/docs/tools-sdks/connect">
    Set up, inspect, and restore your coding agent.
  </Card>

  <Card title="Chat completions" icon="braces" href="/docs/api-reference/chat-completions">
    Read the request contract.
  </Card>

  <Card title="Models" icon="list" href="/docs/api-reference/models">
    Find model ids and context windows.
  </Card>
</Columns>