AI setup

The KiBro AI Gateway provides centrally managed access to approved AI models. Access is tied to a personal API key, and the available models can differ by key.

Caution

Request a personal AI Gateway API key from an administrator. Do not use another developer’s key or a provider account credential. Never commit the key to a repository or let it leak into AI sessions or other places!

OpenCode 2 is required

This setup, including the image-generation plugin, requires OpenCode 2. OpenCode 1 uses incompatible configuration and plugin APIs and is no longer supported by these instructions. Upgrade to OpenCode 2 before continuing.

OpenCode

OpenCode 2 is the recommended client. Install it by following the official terminal client guide, then configure the gateway:

1. Store the API key in a private file. Linux/macOS is the preferred setup:

   mkdir -p ~/.config/opencode
   chmod 700 ~/.config/opencode
   printf 'KiBro AI Gateway API key: '
   read -r -s KIBRO_AI_API_KEY
   printf '\n'
   printf '%s' "$KIBRO_AI_API_KEY" > ~/.config/opencode/kibro-api-key.env
   unset KIBRO_AI_API_KEY
   chmod 600 ~/.config/opencode/kibro-api-key.env

   WSL is the preferred Windows setup. If you use WSL, follow the Linux/macOS commands above from your WSL terminal. For a native Windows installation, run this in PowerShell instead:

   $configDir = Join-Path $HOME ".config\opencode"
   New-Item -ItemType Directory -Force -Path $configDir | Out-Null
   $secureApiKey = Read-Host "KiBro AI Gateway API key" -AsSecureString
   $apiKey = [System.Net.NetworkCredential]::new("", $secureApiKey).Password
   $keyPath = Join-Path $configDir "kibro-api-key.env"
   [System.IO.File]::WriteAllText($keyPath, $apiKey, [System.Text.UTF8Encoding]::new($false))
   Remove-Variable secureApiKey, apiKey

2. Add the following provider to ~/.config/opencode/opencode.json. On Windows, this is $HOME\.config\opencode\opencode.json in PowerShell.

   Merge, if the file already exists and has content!

   If the file already contains settings, merge only the providers entry instead of replacing the file. Optionally merge the model key to select the recommended default model.

   The permissions array is optional. The example is a conservative starting point that allows routine inspection while prompting for shell commands and blocking access to common secret files. Permission rules are ordered; the last matching rule wins.

   {
     "$schema": "https://opencode.ai/config.json",
     "model": "kibro-ai-gateway/normal",
     "permissions": [
       { "action": "*", "resource": "*", "effect": "ask" },
       { "action": "read", "resource": "*", "effect": "allow" },
       { "action": "read", "resource": ".env*", "effect": "deny" },
       { "action": "read", "resource": "**/.env*", "effect": "deny" },
       { "action": "read", "resource": "*.env.example", "effect": "allow" },
       { "action": "read", "resource": "**/*.env.example", "effect": "allow" },
       { "action": "read", "resource": "*auth.json", "effect": "deny" },
       { "action": "read", "resource": "/tmp/opencode/*", "effect": "allow" },
       { "action": "edit", "resource": ".env*", "effect": "deny" },
       { "action": "edit", "resource": "**/.env*", "effect": "deny" },
       { "action": "shell", "resource": "*", "effect": "ask" },
       { "action": "shell", "resource": "pwd", "effect": "allow" },
       { "action": "shell", "resource": "which *", "effect": "allow" },
       { "action": "shell", "resource": "command -v *", "effect": "allow" },
       { "action": "shell", "resource": "find *", "effect": "allow" },
       { "action": "shell", "resource": "grep *", "effect": "allow" },
       { "action": "shell", "resource": "ls *", "effect": "allow" },
       { "action": "shell", "resource": "rg *", "effect": "allow" },
       { "action": "shell", "resource": "tree *", "effect": "allow" },
       { "action": "shell", "resource": "file *", "effect": "allow" },
       { "action": "shell", "resource": "stat *", "effect": "allow" },
       { "action": "shell", "resource": "wc *", "effect": "allow" },
       { "action": "shell", "resource": "realpath *", "effect": "allow" },
       { "action": "shell", "resource": "readlink *", "effect": "allow" },
       { "action": "shell", "resource": "basename *", "effect": "allow" },
       { "action": "shell", "resource": "dirname *", "effect": "allow" },
       { "action": "shell", "resource": "cmp *", "effect": "allow" },
       { "action": "shell", "resource": "diff *", "effect": "allow" },
       { "action": "glob", "resource": "*", "effect": "allow" },
       { "action": "grep", "resource": "*", "effect": "allow" },
       { "action": "subagent", "resource": "*", "effect": "allow" },
       { "action": "skill", "resource": "*", "effect": "allow" },
       { "action": "question", "resource": "*", "effect": "allow" },
       { "action": "webfetch", "resource": "*", "effect": "allow" },
       { "action": "websearch", "resource": "*", "effect": "allow" }
     ],
     "providers": {
       "kibro-ai-gateway": {
         "package": "@opencode/ai/providers/openai-compatible",
         "name": "KiBro AI Gateway",
         "settings": {
           "baseURL": "https://ai-gateway.kiwis-and-brownies.de/v1",
           "apiKey": "{file:~/.config/opencode/kibro-api-key.env}"
         },
         "models": {
           "low": {
             "modelID": "gpt-6-luna-max",
             "name": "Low (Luna 6 Max)",
             "capabilities": {
               "tools": true,
               "input": ["text", "image"],
               "output": ["text"]
             }
           },
           "normal": {
             "modelID": "gpt-6-sol-low",
             "name": "Normal (Sol 6 Low)",
             "capabilities": {
               "tools": true,
               "input": ["text", "image"],
               "output": ["text"]
             }
           },
           "medium": {
             "modelID": "gpt-5.6-sol-medium",
             "name": "Medium (Sol 5.6 Medium)",
             "capabilities": {
               "tools": true,
               "input": ["text", "image"],
               "output": ["text"]
             }
           },
           "high": {
             "modelID": "gpt-6-astra-low",
             "name": "High (Astra Low)",
             "capabilities": {
               "tools": true,
               "input": ["text", "image"],
               "output": ["text"]
             }
           }
         }
       }
     }
   }

3. OpenCode 2 reloads configuration changes automatically. If the provider does not appear, restart the background service with opencode service restart.

4. Run /models and select a model under KiBro AI Gateway. normal is the recommended default. Access to individual models depends on the policy assigned to your API key; ask an administrator if a request returns HTTP 403 with model_not_allowed.

Model discovery for custom OpenCode providers is not automatic. When an administrator introduces or renames a public model alias, add that alias to the models object before it appears in /models.

The low, normal, medium, and high keys are the model aliases shown and selected in OpenCode. Their modelID values are the identifiers sent to the gateway. They intentionally include the underlying GPT model family because OpenCode uses that identifier for model-specific behavior. Keep these IDs synchronized with the aliases configured in the gateway.

Image generation

OpenCode can generate an image through the KiBro AI Gateway and save it in the current working directory. Complete the OpenCode setup above first, then install the global OpenCode 2 plugin and /image command on Linux, macOS, or WSL:

curl -fsSL https://internaldocs.cluster.brezel.io/opencode/install-image-tool.sh | sh

For a native Windows installation, run this in PowerShell instead:

$configDir = Join-Path $HOME ".config\opencode"
New-Item -ItemType Directory -Force -Path "$configDir\plugins", "$configDir\commands" | Out-Null
Invoke-WebRequest "https://internaldocs.cluster.brezel.io/opencode/generate_image.txt" -OutFile "$configDir\plugins\generate_image.ts"
Invoke-WebRequest "https://internaldocs.cluster.brezel.io/opencode/image.md" -OutFile "$configDir\commands\image.md"
Remove-Item "$configDir\tools\generate_image.ts" -ErrorAction SilentlyContinue

Restart the OpenCode background service after installation:

opencode service restart

Then generate an image from any project directory with:

/image A hand-drawn kiwi bird wearing a brown hat

Type @ inside the command to autocomplete a reference image from the current project. The original image is uploaded to the image model with high input fidelity; it is not reduced to a text description:

/image Use @reference.png. Preserve the character and drawing style, but replace the background with a bakery.

You can also enter the relative path directly without @:

/image Use reference.png. Preserve the character and replace the background.

Reference images must be PNG, JPEG, or WebP files inside the active session directory. Up to 16 images can be supplied.

Output quality and dimensions

Add quality=<value> and size=<value> directly to the image prompt. Separate them from the description with semicolons so the requested settings are unambiguous:

/image A hand-drawn kiwi bird wearing a brown hat; quality=high; size=1536x1024

The supported quality values are:

Quality	Use
auto	Let the image model choose; this is the default
low	Faster generation with less detail
medium	Balanced speed and detail
high	Highest detail and slower generation

Aspect ratio is selected through one of the supported fixed image sizes:

Size	Shape and aspect ratio
auto	Let the image model choose; this is the default
1024x1024	Square, 1:1
1536x1024	Landscape, 3:2
1024x1536	Portrait, 2:3

Arbitrary dimensions and exact aspect ratios such as 16:9 are not supported. Choose the closest available size. For example:

/image A wide editorial illustration of a bakery at sunrise; quality=high; size=1536x1024
/image A portrait poster of a kiwi baker; quality=medium; size=1024x1536
/image A square app icon showing a kiwi; quality=high; size=1024x1024

The other supported options are:

Option	Values
format	png, jpeg, webp
background	auto, opaque, transparent
input_fidelity	low, high; applies only to reference images. high = closer match of faces, logos etc.

Without a reference image, input_fidelity is ignored and generation proceeds directly from the text prompt. The tool does not require or create a temporary reference image.

Options work the same way when using reference images:

/image Use @reference.png; preserve the subject; size=1536x1024; quality=high; format=png

OpenCode autocompletes @ file references, but custom slash commands do not provide autocomplete for option values. The image tool validates the values before sending the request.

The command selects the gateway’s image model automatically. Do not add an image entry to the OpenCode provider’s models object. The generated file is written to the active OpenCode session directory, and an existing file is never overwritten. OpenCode may ask you to approve the generate_image tool call, depending on your permission configuration.

Other clients

The gateway exposes an OpenAI-compatible API under https://ai-gateway.kiwis-and-brownies.de/v1. It can therefore be used by essentially any agent harness or SDK that accepts a custom OpenAI-compatible base URL, bearer API key, and model name. Use the public model aliases low, normal, and high; access remains subject to the policy for your API key.

Advanced users can also configure dedicated clients using the upstream CPA instructions:

• Codex client configuration: replace the local example base URL with https://ai-gateway.kiwis-and-brownies.de/v1 and use your personal gateway API key.
• Claude Code client configuration: replace the local example base URL with https://ai-gateway.kiwis-and-brownies.de and use your personal gateway API key.

Review permission and sandbox settings independently. The upstream examples contain permissive options that are not required merely to connect to the gateway.