Lumoswitch Docs
Agent setup

Kilo Code Agent setup

Kilo Code is an open-source coding agent for planning, editing code, running commands, and using tools from a terminal, VS Code-compatible editor, or JetBrains. CLI and IDE share a configuration system, but graphical surfaces do not inherit one-time variables from the current shell.

Create a Lumoswitch API configuration with OpenAI-compatible output first.

Choose a setup method

MethodCLIVS Code / JetBrains
One-time launchSupported through process-scoped KILO_CONFIG_CONTENTNot supported; the editor process does not inherit the current shell
Persistent useAgent-supported config path + optional launcherProviders settings or global configuration
RemovalDelete only dedicated filesRemove only the named provider fields from shared configuration

Prepare the connection values

PlaceholderValue
{{api_base_url}}The downstream API URL, including /v1
{{access_key}}The Lumoswitch Access Key selected for this configuration
{{model}}The client-facing model name shown by the API configuration
{{kilo_config_json}}Complete Kilo config generated from effective reasoning capabilities

The templates do not guess context and output limits. For a custom model outside Kilo's built-in catalog, add accurate limit.context and limit.output values before regular use or automatic compaction and context reporting may be inaccurate.

One-time launch

LUMOSWITCH_KILO_CONFIG='{{kilo_config_json}}'
env \
  LUMOSWITCH_KILO_API_KEY="{{access_key}}" \
  KILO_CONFIG_CONTENT="$LUMOSWITCH_KILO_CONFIG" \
  kilo --model "openai-compatible/{{model}}"

KILO_CONFIG_CONTENT is an official trusted process-level configuration source. It expires when Kilo exits and does not write global or project kilo.jsonc. The generated catalog marks reasoning only for routes with verified reasoning support; keep tool_call: true only when the target model genuinely supports tools.

Persistent CLI use

This creates Agent-supported Lumoswitch configuration and an optional launcher without changing global ~/.config/kilo/kilo.jsonc:

set -e
LUMOSWITCH_ROOT="$HOME/.config/lumoswitch/agents/kilo-code"
LUMOSWITCH_ENV="$LUMOSWITCH_ROOT/env.sh"
LUMOSWITCH_LAUNCHER="$HOME/.local/bin/lumoswitch-kilo-code"
mkdir -p "$LUMOSWITCH_ROOT" "$(dirname "$LUMOSWITCH_LAUNCHER")"
umask 077

if [ -f "$LUMOSWITCH_LAUNCHER" ]; then
  LUMOSWITCH_BACKUP="$LUMOSWITCH_LAUNCHER.backup.$(date +%Y%m%d-%H%M%S)-$$"
  cp "$LUMOSWITCH_LAUNCHER" "$LUMOSWITCH_BACKUP"
  chmod 600 "$LUMOSWITCH_BACKUP"
fi

LUMOSWITCH_KILO_CONFIG="$LUMOSWITCH_ROOT/kilo.json"
printf '%s\n' '{{kilo_config_json}}' > "$LUMOSWITCH_KILO_CONFIG"

cat > "$LUMOSWITCH_ENV" <<'LUMOSWITCH_ENV_EOF'
export KILO_CONFIG="$HOME/.config/lumoswitch/agents/kilo-code/kilo.json"
export LUMOSWITCH_KILO_API_KEY="{{access_key}}"
export LUMOSWITCH_KILO_MODEL="{{model}}"
LUMOSWITCH_ENV_EOF

case "$SHELL" in
  */zsh) LUMOSWITCH_PROFILE="$HOME/.zshrc" ;;
  */bash) LUMOSWITCH_PROFILE="$HOME/.bashrc" ;;
  *) LUMOSWITCH_PROFILE="$HOME/.profile" ;;
esac
touch "$LUMOSWITCH_PROFILE"
LUMOSWITCH_PROFILE_MARKER='# Lumoswitch Agent: kilo-code'
LUMOSWITCH_SOURCE_LINE='[ -f "$HOME/.config/lumoswitch/agents/kilo-code/env.sh" ] && . "$HOME/.config/lumoswitch/agents/kilo-code/env.sh"'
if ! grep -Fqx "$LUMOSWITCH_SOURCE_LINE" "$LUMOSWITCH_PROFILE"; then
  printf '\n%s\n%s\n' "$LUMOSWITCH_PROFILE_MARKER" "$LUMOSWITCH_SOURCE_LINE" >> "$LUMOSWITCH_PROFILE"
fi
printf '%s\n' "$LUMOSWITCH_PROFILE" > "$LUMOSWITCH_ROOT/profile-path"

cat > "$LUMOSWITCH_LAUNCHER" <<'LUMOSWITCH_LAUNCHER_EOF'
#!/usr/bin/env bash
set -e
LUMOSWITCH_ROOT="$HOME/.config/lumoswitch/agents/kilo-code"
LUMOSWITCH_ENV="$LUMOSWITCH_ROOT/env.sh"
LUMOSWITCH_LAUNCHER="$HOME/.local/bin/lumoswitch-kilo-code"

if [ "$1" = "--lumoswitch-clean" ]; then
  if [ -f "$LUMOSWITCH_ROOT/profile-path" ]; then
    LUMOSWITCH_PROFILE="$(cat "$LUMOSWITCH_ROOT/profile-path")"
    if [ -f "$LUMOSWITCH_PROFILE" ]; then
      LUMOSWITCH_PROFILE_MARKER='# Lumoswitch Agent: kilo-code'
      LUMOSWITCH_SOURCE_LINE='[ -f "$HOME/.config/lumoswitch/agents/kilo-code/env.sh" ] && . "$HOME/.config/lumoswitch/agents/kilo-code/env.sh"'
      LUMOSWITCH_PROFILE_TMP="$LUMOSWITCH_PROFILE.lumoswitch.$$"
      awk -v marker="$LUMOSWITCH_PROFILE_MARKER" -v source="$LUMOSWITCH_SOURCE_LINE" '$0 != marker && $0 != source' "$LUMOSWITCH_PROFILE" > "$LUMOSWITCH_PROFILE_TMP"
      mv "$LUMOSWITCH_PROFILE_TMP" "$LUMOSWITCH_PROFILE"
    fi
  fi
  if [ -d "$LUMOSWITCH_ROOT" ]; then
    find "$LUMOSWITCH_ROOT" -depth \( -type f -o -type l \) -delete
    find "$LUMOSWITCH_ROOT" -depth -type d -exec rmdir {} \; 2>/dev/null || true
  fi
  find "$(dirname "$LUMOSWITCH_LAUNCHER")" -maxdepth 1 -type f -name 'lumoswitch-kilo-code.backup.*' -delete
  rm -f "$LUMOSWITCH_LAUNCHER"
  printf '%s\n' 'Lumoswitch native setup and optional launcher removed. Open a new terminal to refresh the environment.'
  exit 0
fi

if [ -f "$LUMOSWITCH_ENV" ]; then . "$LUMOSWITCH_ENV"; fi
exec kilo "$@"
LUMOSWITCH_LAUNCHER_EOF

chmod 600 "$LUMOSWITCH_ENV"
find "$LUMOSWITCH_ROOT" -type f -exec chmod 600 {} \;
chmod 700 "$LUMOSWITCH_LAUNCHER"
. "$LUMOSWITCH_ENV"
printf '%s\n' 'Native Lumoswitch setup saved. Future command: kilo'
printf '%s\n' 'Optional maintenance launcher: ~/.local/bin/lumoswitch-kilo-code'
kilo

For everyday use, run:

kilo

The managed user environment points KILO_CONFIG at the dedicated file, so plain kilo loads it without the launcher.

Native Windows PowerShell import

These commands run natively in Windows PowerShell without WSL and use the same connection values as the macOS/Linux templates on this page.

One-time use on Windows

& {
  $ErrorActionPreference = 'Stop'
  $lumoswitchConfigContent = @'
{{kilo_config_json}}
'@
  $lumoswitchEnvironmentNames = @('KILO_CONFIG_CONTENT', 'LUMOSWITCH_KILO_API_KEY')
  $lumoswitchPreviousEnvironment = @{}
  foreach ($lumoswitchName in $lumoswitchEnvironmentNames) {
    $lumoswitchPreviousEnvironment[$lumoswitchName] = [Environment]::GetEnvironmentVariable($lumoswitchName, 'Process')
  }
  $lumoswitchExitCode = 0
  try {
    [Environment]::SetEnvironmentVariable('KILO_CONFIG_CONTENT', $lumoswitchConfigContent, 'Process')
    [Environment]::SetEnvironmentVariable('LUMOSWITCH_KILO_API_KEY', '{{access_key}}', 'Process')
    $lumoswitchArguments = @('--model', 'openai-compatible/{{model}}')
    $lumoswitchExecutable = Get-Command 'kilo.cmd' -CommandType Application -ErrorAction SilentlyContinue
    if ($null -eq $lumoswitchExecutable) { $lumoswitchExecutable = Get-Command 'kilo' -CommandType Application -ErrorAction Stop }
    & $lumoswitchExecutable.Path @lumoswitchArguments
    if ($null -ne $LASTEXITCODE) { $lumoswitchExitCode = $LASTEXITCODE }
  } finally {
    foreach ($lumoswitchName in $lumoswitchEnvironmentNames) {
      [Environment]::SetEnvironmentVariable($lumoswitchName, $lumoswitchPreviousEnvironment[$lumoswitchName], 'Process')
    }
  }
  if ($lumoswitchExitCode -ne 0) { throw 'kilo exited with code ' + $lumoswitchExitCode }
}

Persistent use on Windows

This command backs up existing Lumoswitch-owned files and restricts access to the configuration and launcher for the current user.

& {
  $ErrorActionPreference = 'Stop'
  $lumoswitchRoot = Join-Path $env:LOCALAPPDATA 'Lumoswitch\agents\kilo-code'
  $lumoswitchLauncher = Join-Path $env:LOCALAPPDATA 'Lumoswitch\bin\lumoswitch-kilo-code.ps1'
  $lumoswitchBackupSuffix = (Get-Date -Format 'yyyyMMdd-HHmmss') + '-' + $PID

  function Protect-LumoswitchFile([string] $Path) {
    $lumoswitchSid = [Security.Principal.WindowsIdentity]::GetCurrent().User.Value
    & icacls.exe $Path '/inheritance:r' '/grant:r' ('*' + $lumoswitchSid + ':(F)') '*S-1-5-18:(F)' '*S-1-5-32-544:(F)' | Out-Null
    if ($LASTEXITCODE -ne 0) { throw "Could not restrict access to $Path" }
  }

  function Install-LumoswitchFile([string] $Path, [string] $Content) {
    [IO.Directory]::CreateDirectory((Split-Path -Parent $Path)) | Out-Null
    if (Test-Path -LiteralPath $Path) {
      $lumoswitchItem = Get-Item -LiteralPath $Path -Force
      if ($lumoswitchItem.PSIsContainer -or ($lumoswitchItem.Attributes -band [IO.FileAttributes]::ReparsePoint)) {
        throw "Lumoswitch refused to replace a directory or link: $Path"
      }
      $lumoswitchBackup = $Path + '.backup.' + $lumoswitchBackupSuffix
      Copy-Item -LiteralPath $Path -Destination $lumoswitchBackup
      Protect-LumoswitchFile $lumoswitchBackup
    }
    $lumoswitchTemporary = $Path + '.' + [Guid]::NewGuid().ToString('N') + '.tmp'
    try {
      [IO.File]::WriteAllText($lumoswitchTemporary, $Content, [Text.UTF8Encoding]::new($false))
      Move-Item -LiteralPath $lumoswitchTemporary -Destination $Path -Force
      Protect-LumoswitchFile $Path
    } finally {
      Remove-Item -LiteralPath $lumoswitchTemporary -Force -ErrorAction SilentlyContinue
    }
  }

  [IO.Directory]::CreateDirectory($lumoswitchRoot) | Out-Null
  $lumoswitchKiloConfig = Join-Path $lumoswitchRoot 'kilo.json'
  Install-LumoswitchFile $lumoswitchKiloConfig '{{kilo_config_json}}'

  $lumoswitchEnvironment = [ordered]@{}
  $lumoswitchEnvironment['KILO_CONFIG'] = (Join-Path $lumoswitchRoot 'kilo.json')
  $lumoswitchEnvironment['LUMOSWITCH_KILO_API_KEY'] = '{{access_key}}'
  $lumoswitchEnvironment['LUMOSWITCH_KILO_MODEL'] = '{{model}}'
  foreach ($lumoswitchEntry in $lumoswitchEnvironment.GetEnumerator()) {
    [Environment]::SetEnvironmentVariable($lumoswitchEntry.Key, $lumoswitchEntry.Value, 'User')
    [Environment]::SetEnvironmentVariable($lumoswitchEntry.Key, $lumoswitchEntry.Value, 'Process')
  }

  $lumoswitchLauncherContent = @'
param([Parameter(ValueFromRemainingArguments = $true)][string[]] $AgentArgs)
$ErrorActionPreference = 'Stop'
$lumoswitchRoot = Join-Path $env:LOCALAPPDATA 'Lumoswitch\agents\kilo-code'
$lumoswitchLauncher = Join-Path $env:LOCALAPPDATA 'Lumoswitch\bin\lumoswitch-kilo-code.ps1'

function Remove-LumoswitchFile([string] $Path) {
  if (-not (Test-Path -LiteralPath $Path)) { return }
  $lumoswitchItem = Get-Item -LiteralPath $Path -Force
  if ($lumoswitchItem.PSIsContainer -or ($lumoswitchItem.Attributes -band [IO.FileAttributes]::ReparsePoint)) {
    throw "Lumoswitch refused to remove a directory or link: $Path"
  }
  Remove-Item -LiteralPath $Path -Force
}

if ($AgentArgs.Count -gt 0 -and $AgentArgs[0] -eq '--lumoswitch-clean') {
  foreach ($lumoswitchName in @('KILO_CONFIG', 'LUMOSWITCH_KILO_API_KEY', 'LUMOSWITCH_KILO_MODEL')) {
    [Environment]::SetEnvironmentVariable($lumoswitchName, $null, 'User')
    [Environment]::SetEnvironmentVariable($lumoswitchName, $null, 'Process')
  }
  if (Test-Path -LiteralPath $lumoswitchRoot -PathType Container) {
    $lumoswitchRootItem = Get-Item -LiteralPath $lumoswitchRoot -Force
    if ($lumoswitchRootItem.Attributes -band [IO.FileAttributes]::ReparsePoint) { throw 'Lumoswitch refused to clean through a linked directory.' }
    foreach ($lumoswitchFile in @(Get-ChildItem -LiteralPath $lumoswitchRoot -File -Recurse -Force)) { Remove-LumoswitchFile $lumoswitchFile.FullName }
    foreach ($lumoswitchDirectory in @(Get-ChildItem -LiteralPath $lumoswitchRoot -Directory -Recurse -Force | Sort-Object FullName -Descending)) {
      if ($null -eq (Get-ChildItem -LiteralPath $lumoswitchDirectory.FullName -Force | Select-Object -First 1)) { Remove-Item -LiteralPath $lumoswitchDirectory.FullName -Force }
    }
    if ($null -eq (Get-ChildItem -LiteralPath $lumoswitchRoot -Force | Select-Object -First 1)) { Remove-Item -LiteralPath $lumoswitchRoot -Force }
  }
  $lumoswitchBin = Split-Path -Parent $lumoswitchLauncher
  if (Test-Path -LiteralPath $lumoswitchBin -PathType Container) {
    foreach ($lumoswitchBackup in @(Get-ChildItem -LiteralPath $lumoswitchBin -Filter 'lumoswitch-kilo-code.ps1.backup.*' -File -Force)) { Remove-LumoswitchFile $lumoswitchBackup.FullName }
  }
  Remove-LumoswitchFile $lumoswitchLauncher
  Write-Host 'Lumoswitch native setup and optional launcher removed. Open a new terminal to refresh the environment.'
  exit 0
}

$lumoswitchEnvironment = [ordered]@{}
$lumoswitchEnvironment['KILO_CONFIG'] = (Join-Path $lumoswitchRoot 'kilo.json')
$lumoswitchEnvironment['LUMOSWITCH_KILO_API_KEY'] = '{{access_key}}'
$lumoswitchEnvironment['LUMOSWITCH_KILO_MODEL'] = '{{model}}'
foreach ($lumoswitchEntry in $lumoswitchEnvironment.GetEnumerator()) {
  [Environment]::SetEnvironmentVariable($lumoswitchEntry.Key, $lumoswitchEntry.Value, 'Process')
}
$lumoswitchExecutable = Get-Command 'kilo.cmd' -CommandType Application -ErrorAction SilentlyContinue
if ($null -eq $lumoswitchExecutable) { $lumoswitchExecutable = Get-Command 'kilo.exe' -CommandType Application -ErrorAction SilentlyContinue }
if ($null -eq $lumoswitchExecutable) { $lumoswitchExecutable = Get-Command 'kilo' -CommandType Application -ErrorAction Stop }
$lumoswitchArguments = @()
& $lumoswitchExecutable.Path @lumoswitchArguments @AgentArgs
if ($null -ne $LASTEXITCODE) { exit $LASTEXITCODE }
'@
  Install-LumoswitchFile $lumoswitchLauncher $lumoswitchLauncherContent
  Write-Host 'Native Lumoswitch setup saved. Future command: kilo'
  Write-Host 'Optional maintenance launcher:' $lumoswitchLauncher
  $lumoswitchExecutable = Get-Command 'kilo.cmd' -CommandType Application -ErrorAction SilentlyContinue
  if ($null -eq $lumoswitchExecutable) { $lumoswitchExecutable = Get-Command 'kilo.exe' -CommandType Application -ErrorAction SilentlyContinue }
  if ($null -eq $lumoswitchExecutable) { $lumoswitchExecutable = Get-Command 'kilo' -CommandType Application -ErrorAction Stop }
  $lumoswitchArguments = @()
  & $lumoswitchExecutable.Path @lumoswitchArguments
  if ($null -ne $LASTEXITCODE -and $LASTEXITCODE -ne 0) { throw 'kilo exited with code ' + $LASTEXITCODE }
}

The import writes the Agent-supported persistent configuration and starts kilo directly. The saved Lumoswitch maintenance script is not required to start the Agent; run it with --lumoswitch-clean when you need to restore or remove this setup.

Remove the CLI setup

Windows PowerShell

Exit every Lumoswitch session for this Agent, then run the command below. The optional maintenance launcher removes the managed native configuration, restores any preserved shared file, clears Lumoswitch user environment values, and removes itself.

& {
  $lumoswitchLauncher = Join-Path $env:LOCALAPPDATA 'Lumoswitch\bin\lumoswitch-kilo-code.ps1'
  if (-not (Test-Path -LiteralPath $lumoswitchLauncher -PathType Leaf)) {
    throw 'The optional Lumoswitch maintenance launcher is missing. Run persistent import again before cleanup.'
  }
  & powershell.exe -NoLogo -NoProfile -ExecutionPolicy Bypass -File $lumoswitchLauncher --lumoswitch-clean
}

macOS / Linux

"$HOME/.local/bin/lumoswitch-kilo-code" --lumoswitch-clean

The command removes only dedicated files created by this page. It does not remove Kilo sessions, global configuration, project configuration, or other providers.

Persistent VS Code and JetBrains setup

Kilo officially provides VS Code-family extensions and a JetBrains plugin. All local clients read ~/.config/kilo/kilo.jsonc, so a correct global provider can be reused.

In Settings → Providers → Custom provider, enter:

FieldValue
Provider IDlumoswitch
Display nameLumoswitch
Provider APIOpenAI Compatible
Base URL{{api_base_url}}
API key{{access_key}}
Models{{model}}

Graphical surfaces support persistent setup only. The editor starts them and they do not inherit the KILO_CONFIG_CONTENT or LUMOSWITCH_KILO_API_KEY used above.

Remove the IDE setup

Delete the lumoswitch custom provider from Providers settings. If the installed version requires editing Global Config directly, remove only provider.lumoswitch, and remove or change the top-level model only if it points to lumoswitch/....

There is no terminal command for automatically rewriting kilo.jsonc because it is shared by CLI, VS Code, and JetBrains and may contain comments, other providers, and project rules. Removing ~/.config/kilo would destroy all client settings. A custom API Key written inside the provider block is removed with that block. OAuth credentials should instead use the provider's Disconnect action or kilo auth logout; that command is not for a normal Lumoswitch Key.

Kilo also has Cloud, mobile, and Slack surfaces, but this local custom provider does not automatically sync into hosted runtimes. This page covers local CLI, VS Code, and JetBrains only. There is no standalone Kilo Desktop app.

Verify and troubleshoot

  • Run kilo models and confirm that the model appears.
  • Model identifiers use provider/model; this CLI template uses openai-compatible/{{model}}.
  • Add accurate limit.context and limit.output values and set tool_call according to actual model capability.

References: Kilo Code introduction, Custom Models, Settings, CLI Reference, and JetBrains.

Maintainer publication fields
  • Platform ID: kilo-code
  • Display name: Kilo Code CLI
  • Downstream protocol: openai-compatible
  • commandTemplate: copy the complete One-time launch code block
  • Persistent strategy: native
  • persistentCommandTemplate: copy the complete Persistent CLI use code block
  • futureCommand: kilo
  • Display order: 110
  • Last verified: 2026-08-27

Goose Agent setup

Understand Goose and configure, temporarily switch, or remove Lumoswitch

OpenClaw Agent setup

Understand OpenClaw's Gateway model and configure or remove Lumoswitch

On this page

Kilo Code Agent setupChoose a setup methodPrepare the connection valuesOne-time launchPersistent CLI useNative Windows PowerShell importOne-time use on WindowsPersistent use on WindowsRemove the CLI setupWindows PowerShellmacOS / LinuxPersistent VS Code and JetBrains setupRemove the IDE setupVerify and troubleshoot