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

# LLM configuration

> Connect the model that drives Gimorra: a Claude login, an Anthropic API key, a proxy, or an OpenAI-compatible endpoint.

Gimorra runs its agents on a coding-agent engine, the Claude Code SDK by default, which uses the Anthropic Messages API. You choose the model and the endpoint that serves it. Pick one of the setups below, then [verify the connection](#verify-the-connection).

Gimorra reads settings from two places. An environment variable overrides the config file, and the config file overrides the built-in default:

```text theme={null}
environment variable  >  ~/.gimorra/configs.yaml  >  built-in default
```

## Pick a setup

> [tab] Claude login
>
> If the Claude Code CLI is logged in on this machine, you don't need to configure anything. When no endpoint, key or model is set, Gimorra uses that login.
>
> To set it explicitly and choose the model:
>
> ```bash theme={null}
> gimorra config set llm.connections.main.native-cli claude
> gimorra config set llm.connections.main.model claude-sonnet-5
> ```
>
> To use the login for one run without changing the default:
>
> ```bash theme={null}
> gimorra scan -t https://app.example.com --llm-profile native-cli-claude
> ```
>
> In a Claude Code cloud session, the shell already has the session's Claude settings, and Gimorra's runs use them.

> [tab] Anthropic API key
>
> ```bash theme={null}
> export GIMORRA_LLM_API_KEY=sk-ant-...
> export GIMORRA_LLM_MODEL=claude-opus-5   # optional; if unset, Gimorra picks a model per task
> ```
>
> With no base URL set, Gimorra sends requests to `https://api.anthropic.com`.
>
> Exporting only `ANTHROPIC_API_KEY` also works. In that case Gimorra passes the variable through unchanged, and you lose routing, the fallback ladder and `gimorra doctor llm`. Set the `GIMORRA_LLM_*` variables to get them.
>
> A Claude subscription works the same way. Run `claude setup-token` to get a token, then export it as `CLAUDE_CODE_OAUTH_TOKEN`.

> [tab] Anthropic-compatible proxy
>
> Use a proxy that speaks the Anthropic Messages API and sits in front of subscriptions you already pay for. One proxy key can reach several models, which you need for [routing](#route-work-to-different-models).
>
> ```bash theme={null}
> export GIMORRA_LLM_BASE_URL=http://127.0.0.1:8317   # no trailing /v1
> export GIMORRA_LLM_API_KEY=<the proxy's key>
> export GIMORRA_LLM_MODEL=<a model id the proxy serves>
> export GIMORRA_LLM_MODEL_FALLBACK=<a cheaper model id>   # optional
> ```
>
> Use the model ids that your proxy serves, not bare `claude-*` ids.

> [tab] OpenAI-compatible endpoint
>
> Use this for vLLM, LiteLLM, Ollama, LM Studio, OpenRouter, or any server that only answers `/v1/chat/completions`. Set the API type to `openai`, and keep `/v1` at the end of the base URL:
>
> ```bash theme={null}
> export GIMORRA_LLM_BASE_URL=http://127.0.0.1:8317/v1   # keep /v1 for an OpenAI endpoint
> export GIMORRA_LLM_API_KEY=sk-...                      # optional for a local server with no key
> export GIMORRA_LLM_MODEL=<a model id the endpoint serves>
> export GIMORRA_LLM_API=openai
> ```
>
> Gimorra runs a local bridge that translates Messages API requests into chat-completion requests. The bridge listens on `127.0.0.1` only, and it keeps your endpoint key out of the agents' environment. Through the bridge, Anthropic's server-side tools such as web search are unavailable, and the model gets a text note in place of each image.

## Example: a main lane with a standby behind it

This is a real-world setup: one proxy, two fast models doing the work, and a stronger model on each lane for when a fast one stumbles. Drop it in your shell profile and every run picks it up:

```bash theme={null}
# main: the connection every run uses
export GIMORRA_LLM_BASE_URL="https://llmproxy.example.com"
export GIMORRA_LLM_API_KEY="<your proxy key>"
export GIMORRA_LLM_MODEL="glm-5.3-flash"
export GIMORRA_LLM_MODEL_FALLBACK="gpt-5.5"

# standby: where a session goes when main keeps failing
export GIMORRA_STANDBY_LLM_BASE_URL="https://llmproxy.example.com"
export GIMORRA_STANDBY_LLM_API_KEY="<your proxy key>"
export GIMORRA_STANDBY_LLM_MODEL="deepseek-v4.1-flash"
export GIMORRA_STANDBY_LLM_MODEL_FALLBACK="deepseek-v4-pro"
```

When a session keeps failing, it walks down this ladder instead of failing the run:

```text theme={null}
main (glm-5.3-flash)  →  main fallback (gpt-5.5)  →  standby (deepseek-v4.1-flash)  →  standby fallback (deepseek-v4-pro)
```

The ladder tries the same endpoint with its `_MODEL_FALLBACK` first, because swapping models is a smaller change than swapping providers. That step alone often clears a model-level 429 or an "overloaded" error. When `_MODEL_FALLBACK` is a model Gimorra knows costs less, cheap-tier child agents also run on it, while the supervisor and the attack sessions keep the main model.

| Variable | What it sets |
| - | - |
| `<PREFIX>_BASE_URL` | The endpoint. Leave off `/v1` for an Anthropic-compatible proxy, keep it for an OpenAI-compatible one. |
| `<PREFIX>_API_KEY` | The key for that endpoint. |
| `<PREFIX>_MODEL` | The model the connection serves. Use the ids your proxy serves. |
| `<PREFIX>_MODEL_FALLBACK` | A second model on the same endpoint: the first rung down when this one fails. Optional. |
| `<PREFIX>_API` | Set to `openai` when the endpoint only answers `/v1/chat/completions`. Optional. |

Each connection has its own prefix. Declare as many as you have relays, and the ladder walks only the ones you set, in this order:

| Prefix | Connection | Role |
| - | - | - |
| `GIMORRA_LLM` | `main` | The default for every run |
| `GIMORRA_STANDBY_LLM` | `standby` | First fallback |
| `GIMORRA_RESERVE_LLM` | `reserve` | Second fallback |
| `GIMORRA_FAILOVER_LLM` | `failover` | Third fallback |
| `GIMORRA_AUXILIARY_LLM` | `auxiliary` | Fourth fallback |
| `GIMORRA_SPARE_LLM` | `spare` | Last fallback |
| `GIMORRA_FRONTIER_LLM` | `frontier` | Never a fallback. Pick it with `-L frontier` when you want the strongest model. |

Then prove every rung answers before you start a scan:

```bash theme={null}
gimorra doctor llm
```

## Save the settings in the config file

Each `GIMORRA_LLM_*` variable has a matching key under the `main` connection. `gimorra config set` saves the value in `~/.gimorra/configs.yaml`, with file mode `0600`:

```bash theme={null}
gimorra config set llm.connections.main.base_url https://proxy.example
gimorra config set llm.connections.main.api_key  sk-...
gimorra config set llm.connections.main.model    your/model
gimorra config set llm.connections.main.api      openai   # only for an OpenAI-compatible endpoint
```

`main` is the default connection. The supervisor, its child agents and every phase use it, unless a routing rule sends them somewhere else.

## Verify the connection

`gimorra config llm` shows the settings Gimorra resolved. `gimorra doctor llm` tests them by sending one 16-token request to each model:

```bash theme={null}
gimorra config llm   # read-only: the resolved connections and routing
gimorra doctor llm   # sends a test request to every connection a run would use
```

Run `gimorra doctor llm` after every change. If it passes, a run can reach the model.

## Route work to different models

You can add more connections and send different work to each one. For example, the supervisor can use a strong model while the child agents use a cheaper one. Add the connections to `~/.gimorra/configs.yaml`:

```yaml theme={null}
llm:
  connections:
    main:
      base_url: ${GIMORRA_LLM_BASE_URL:}
      api_key: ${GIMORRA_LLM_API_KEY:}
      model: ${GIMORRA_LLM_MODEL:}
    budget:
      base_url: https://proxy.example
      api_key: sk-...
      model: a-cheaper-model
  routing:
    default: main
```

To use a connection for one run, pass `--llm-profile`, or `-L` for short:

```bash theme={null}
gimorra scan -t https://app.example.com -L budget
gimorra audit ./repo -L budget
```

Gimorra checks routing rules in a fixed order and uses the first match: planning, profiles, kinds, tiers, engines, and then the default.

### When a provider fails

By default, `llm.routing.on_failure` is `chain`. When a session keeps failing on one connection, Gimorra moves it down the [fallback ladder](#example-a-main-lane-with-a-standby-behind-it) instead of failing the run. `llm.routing.retry_budget_ms` limits the total time one session spends retrying, and the default is 2 hours. Set `on_failure` to `off` if you want a session to fail as soon as its connection runs out of retries.

## Reasoning effort

`--llm-effort <level>`, or `-E`, sets the model's reasoning effort for one run. To change it on a run that is already going:

```bash theme={null}
gimorra eng effort <engagement-id> <level>
```

> [!NOTE]
>
> Gimorra spends tokens on your account. Every run has a spend limit. See [Budgets and limits](https://docs.vigolium.com/gimorra/running-a-scan.md#budgets-and-limits).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.