#models.json Reference

models.json configures local and custom model providers for the active Sero profile. The file lives in the profile-scoped agent directory:

<SERO_HOME>/agent/models.json

For the default profile, that is usually ~/.sero-ui/agent/models.json. Sero reads and writes this file through the local models UI, then refreshes model availability.

#Minimal shape

{
  "providers": {
    "lm-studio": {
      "baseUrl": "http://localhost:1234/v1",
      "api": "openai-completions",
      "apiKey": "lm-studio",
      "compat": {
        "supportsDeveloperRole": false,
        "supportsReasoningEffort": false
      },
      "models": [
        {
          "id": "local-model-id",
          "name": "Local model"
        }
      ]
    }
  }
}

providers is a map. Each key is the provider ID shown to Sero, and each value is a provider configuration.

#Provider fields

#Model entry fields

#Cost fields

When specified on a model, cost uses numbers per million tokens:

{
  "input": 0,
  "output": 0,
  "cacheRead": 0,
  "cacheWrite": 0
}

Model overrides can use partial cost objects, so only the fields you need to override are required there.

#Supported API shapes and discovery

#Resolver behavior for keys and headers

The Pi resolver handles apiKey and header values as follows:

• A value that starts with ! runs as a shell command with your Sero user privileges. Use this resolver only in a trusted profile file. Pi uses the command's trimmed standard output and caches the result for the process lifetime.
• $NAME and ${NAME} insert the named environment variable. Resolution fails if a referenced variable is not set.
• $$ inserts a literal $, and $! inserts a literal !.
• Other text is a literal value. A bare name such as LOCAL_MODEL_KEY is not an environment reference.

For example:

{
  "apiKey": "$LOCAL_MODEL_KEY",
  "headers": {
    "X-Team": "${MODEL_TEAM}"
  }
}

Treat command-based and environment-backed values as sensitive. Do not commit private models.json files.

#Model overrides

modelOverrides is keyed by model ID and can adjust display/metadata for built-in provider models:

{
  "providers": {
    "openai": {
      "modelOverrides": {
        "gpt-example": {
          "name": "Example display name",
          "reasoning": true,
          "contextWindow": 128000,
          "maxTokens": 8192
        }
      }
    }
  }
}

Supported override fields are name, reasoning, thinkingLevelMap, input, cost, contextWindow, maxTokens, headers, and compat.

#Validation and recovery

If models.json is malformed or contains unsupported values, the model registry can report an error and the local models UI may ask you to fix the invalid entry before adding or editing providers.

Recovery steps:

1. Back up <SERO_HOME>/agent/models.json.
2. Validate it as JSON.
3. Use the registry error to find and correct the invalid entry. Keep fields that are valid for your provider or Pi SDK version.
4. Reopen the model manager or restart Sero.
5. Test connection and fetch models again.

#Related docs

• Local LLMs with LM Studio
• Models and Providers
• State and Folders