Easy local backend env var (#3116)

* feat: add support for local backend URL override

Add KILOCODE_BACKEND_BASE_URL environment variable to enable testing against a local Kilo Code backend. Refactor hardcoded API URLs across providers, webview, and CLI to use getKiloUrl() and getKiloUrlFromToken() functions for dynamic URL resolution. Include new launch configuration and documentation updates for local development workflow.

* Clean and fixes

* more cleanup

* Flip the fn params

* refactor(shared): replace getKiloUrl with getApiUrl and getAppUrl

Replace the generic getKiloUrl function with two specific functions:
- getApiUrl for API endpoints (e.g., /extension-config.json)
- getAppUrl for app/web URLs (e.g., /profile, /support)

This improves type safety and clarity by separating concerns between API and app URL generation.

BREAKING CHANGE: getKiloUrl function removed, use getApiUrl or getAppUrl instead

* refactor(shared): centralize kilocode URL utilities in @roo-code/types

Move getApiUrl, getAppUrl, and getKiloUrlFromToken functions from src/shared/kilocode/ to packages/types/src/kilocode/kilocode.ts and update all imports across the codebase. This consolidates shared utilities into the types package, reducing duplication and improving maintainability.

* refactor(types): add getExtensionConfigUrl and refactor URL utilities

- Introduce getExtensionConfigUrl function for extension config endpoint
- Refactor getApiUrl and getAppUrl to use shared buildUrl helper
- Update tests to cover new function and maintain backwards compatibility
- Use getExtensionConfigUrl in Gemini CLI provider instead of hardcoded URL

* Address PR comments

* Cleanup and revert post main-merge

* Temporarily disable flakey autocomplete tests

* ci: prevent API rate limit exceeded for actions/setup-java@v4

Add check-latest: false and token configuration to setup-java steps
in code-qa.yml and marketplace-publish.yml.

* 'chore: WIP'

Author: hassoncs

.github/workflows/code-qa.yml

@@ -162,6 +162,8 @@ jobs:
               with:
                   distribution: 'jetbrains'
                   java-version: '21'
+                  check-latest: false
+                  token: ${{ secrets.GITHUB_TOKEN }}
             - name: Install system dependencies
               run: |
                 sudo apt-get update
@@ -209,4 +211,4 @@ jobs:
               run: pnpm install
             - name: Run unit tests
               working-directory: cli
-              run: pnpm test
+              run: pnpm test

.github/workflows/marketplace-publish.yml

@@ -134,6 +134,8 @@ jobs:
               with:
                   distribution: "jetbrains"
                   java-version: "21"
+                  check-latest: false
+                  token: ${{ secrets.GITHUB_TOKEN }}
             - name: Install system dependencies
               run: |
                   sudo apt-get update

.vscode/launch.json

@@ -44,6 +44,23 @@
 			},
 			"resolveSourceMapLocations": ["${workspaceFolder}/**", "!**/node_modules/**"],
 			"presentation": { "hidden": false, "group": "tasks", "order": 1 }
+		},
+		{
+			"name": "Run Extension [Local Backend]",
+			"type": "extensionHost",
+			"request": "launch",
+			"runtimeExecutable": "${execPath}",
+			"args": ["--extensionDevelopmentPath=${workspaceFolder}/src", "--disable-extensions"],
+			"sourceMaps": true,
+			"outFiles": ["${workspaceFolder}/dist/**/*.js"],
+			"preLaunchTask": "${defaultBuildTask}",
+			"env": {
+				"NODE_ENV": "development",
+				"VSCODE_DEBUG_MODE": "true",
+				"KILOCODE_BACKEND_BASE_URL": "${input:kilocodeBackendBaseUrl}"
+			},
+			"resolveSourceMapLocations": ["${workspaceFolder}/**", "!**/node_modules/**"],
+			"presentation": { "hidden": false, "group": "tasks", "order": 2 }
 		}
 	],
 	"inputs": [
@@ -52,6 +69,12 @@
 			"description": "Directory the dev extension will open in",
 			"default": "${workspaceFolder}/launch",
 			"type": "promptString"
+		},
+		{
+			"id": "kilocodeBackendBaseUrl",
+			"description": "Override the kilocode backend base URL",
+			"default": "http://localhost:3000",
+			"type": "promptString"
 		}
 	]
 }

DEVELOPMENT.md

@@ -248,6 +248,18 @@ These hooks help maintain code quality and consistency. If you encounter issues
 - Check the Output panel in VSCode (View > Output) and select "Kilo Code" from the dropdown
 - For webview issues, use the browser developer tools in the webview (right-click > "Inspect Element")
 
+### Testing with Local Backend
+
+To test the extension against a local Kilo Code backend:
+
+1. **Set up your local backend** at `http://localhost:3000`
+2. **Use the "Run Extension [Local Backend]" launch configuration**:
+    - Go to Run and Debug (Ctrl+Shift+D)
+    - Select "Run Extension [Local Backend]" from the dropdown
+    - Press F5 to start debugging
+
+This automatically sets the `KILOCODE_BACKEND_BASE_URL` environment variable, making all sign-in/sign-up buttons point to your local backend instead of production.
+
 ## Contributing
 
 We welcome contributions to Kilo Code! Here's how you can help:

cli/src/services/telemetry/identity.ts

@@ -9,6 +9,7 @@ import * as crypto from "crypto"
 import * as os from "os"
 import { KiloCodePaths } from "../../utils/paths.js"
 import { logs } from "../logs.js"
+import { getApiUrl } from "@roo-code/types"
 
 /**
  * User identity structure
@@ -107,7 +108,7 @@ export class IdentityManager {
 
 		try {
 			// Fetch user profile from Kilocode API
-			const response = await fetch("https://api.kilocode.ai/api/profile", {
+			const response = await fetch(getApiUrl("/profile"), {
 				headers: {
 					Authorization: `Bearer ${kilocodeToken}`,
 					"Content-Type": "application/json",

packages/types/src/__tests__/kilocode.test.ts

@@ -1,7 +1,14 @@
 // npx vitest run src/__tests__/kilocode.test.ts
 
 import { describe, it, expect, vi, beforeEach, afterEach } from "vitest"
-import { ghostServiceSettingsSchema, checkKilocodeBalance } from "../kilocode/kilocode.js"
+import {
+	ghostServiceSettingsSchema,
+	checkKilocodeBalance,
+	getApiUrl,
+	getAppUrl,
+	getKiloUrlFromToken,
+	getExtensionConfigUrl,
+} from "../kilocode/kilocode.js"
 
 describe("ghostServiceSettingsSchema", () => {
 	describe("autoTriggerDelay", () => {
@@ -205,3 +212,199 @@ describe("checkKilocodeBalance", () => {
 		expect(result).toBe(false)
 	})
 })
+
+describe("URL functions", () => {
+	const originalEnv = process.env.KILOCODE_BACKEND_BASE_URL
+
+	// Helper functions to create properly formatted test tokens
+	const createDevToken = () => {
+		const payload = { env: "development" }
+		return `header.${btoa(JSON.stringify(payload))}.signature`
+	}
+
+	const createProdToken = () => {
+		const payload = {}
+		return `header.${btoa(JSON.stringify(payload))}.signature`
+	}
+
+	afterEach(() => {
+		// Reset environment variable after each test
+		if (originalEnv) {
+			process.env.KILOCODE_BACKEND_BASE_URL = originalEnv
+		} else {
+			delete process.env.KILOCODE_BACKEND_BASE_URL
+		}
+	})
+
+	describe("getExtensionConfigUrl", () => {
+		it("should use path structure for development", () => {
+			process.env.KILOCODE_BACKEND_BASE_URL = "http://localhost:3000"
+			expect(getExtensionConfigUrl()).toBe("http://localhost:3000/extension-config.json")
+		})
+		it("should use subdomain structure for production", () => {
+			expect(getExtensionConfigUrl()).toBe("https://api.kilocode.ai/extension-config.json")
+		})
+	})
+
+	describe("getApiUrl", () => {
+		it("should handle production URLs correctly", () => {
+			// API URLs using /api path structure
+			expect(getApiUrl("/extension-config.json")).toBe("https://kilocode.ai/api/extension-config.json")
+			expect(getApiUrl("/marketplace/modes")).toBe("https://kilocode.ai/api/marketplace/modes")
+			expect(getApiUrl("/marketplace/mcps")).toBe("https://kilocode.ai/api/marketplace/mcps")
+			expect(getApiUrl("/profile/balance")).toBe("https://kilocode.ai/api/profile/balance")
+			expect(getApiUrl()).toBe("https://kilocode.ai/api")
+		})
+
+		it("should handle development environment", () => {
+			process.env.KILOCODE_BACKEND_BASE_URL = "http://localhost:3000"
+
+			expect(getApiUrl("/extension-config.json")).toBe("http://localhost:3000/api/extension-config.json")
+			expect(getApiUrl("/marketplace/modes")).toBe("http://localhost:3000/api/marketplace/modes")
+			expect(getApiUrl("/marketplace/mcps")).toBe("http://localhost:3000/api/marketplace/mcps")
+			expect(getApiUrl()).toBe("http://localhost:3000/api")
+		})
+
+		it("should handle paths without leading slash", () => {
+			process.env.KILOCODE_BACKEND_BASE_URL = "http://localhost:3000"
+			expect(getApiUrl("extension-config.json")).toBe("http://localhost:3000/api/extension-config.json")
+		})
+
+		it("should handle empty and root paths", () => {
+			expect(getApiUrl("")).toBe("https://kilocode.ai/api")
+			expect(getApiUrl("/")).toBe("https://kilocode.ai/api/")
+		})
+	})
+
+	describe("getAppUrl", () => {
+		it("should handle production URLs correctly", () => {
+			expect(getAppUrl()).toBe("https://kilocode.ai")
+			expect(getAppUrl("/profile")).toBe("https://kilocode.ai/profile")
+			expect(getAppUrl("/support")).toBe("https://kilocode.ai/support")
+			expect(getAppUrl("/sign-in-to-editor")).toBe("https://kilocode.ai/sign-in-to-editor")
+		})
+
+		it("should handle development environment", () => {
+			process.env.KILOCODE_BACKEND_BASE_URL = "http://localhost:3000"
+
+			expect(getAppUrl()).toBe("http://localhost:3000")
+			expect(getAppUrl("/profile")).toBe("http://localhost:3000/profile")
+			expect(getAppUrl("/support")).toBe("http://localhost:3000/support")
+		})
+
+		it("should handle paths without leading slash", () => {
+			process.env.KILOCODE_BACKEND_BASE_URL = "http://localhost:3000"
+			expect(getAppUrl("profile")).toBe("http://localhost:3000/profile")
+		})
+
+		it("should handle empty and root paths", () => {
+			expect(getAppUrl("")).toBe("https://kilocode.ai")
+			expect(getAppUrl("/")).toBe("https://kilocode.ai")
+		})
+	})
+
+	describe("getKiloUrlFromToken", () => {
+		it("should handle production token URLs correctly", () => {
+			const prodToken = createProdToken()
+
+			// Token-based URLs using api.kilocode.ai subdomain
+			expect(getKiloUrlFromToken("https://api.kilocode.ai/api/profile", prodToken)).toBe(
+				"https://api.kilocode.ai/api/profile",
+			)
+			expect(getKiloUrlFromToken("https://api.kilocode.ai/api/profile/balance", prodToken)).toBe(
+				"https://api.kilocode.ai/api/profile/balance",
+			)
+			expect(getKiloUrlFromToken("https://api.kilocode.ai/api/organizations/123/defaults", prodToken)).toBe(
+				"https://api.kilocode.ai/api/organizations/123/defaults",
+			)
+			expect(getKiloUrlFromToken("https://api.kilocode.ai/api/openrouter/", prodToken)).toBe(
+				"https://api.kilocode.ai/api/openrouter/",
+			)
+			expect(getKiloUrlFromToken("https://api.kilocode.ai/api/users/notifications", prodToken)).toBe(
+				"https://api.kilocode.ai/api/users/notifications",
+			)
+		})
+
+		it("should map development tokens to localhost correctly", () => {
+			const devToken = createDevToken()
+
+			// Development token should map to localhost:3000
+			expect(getKiloUrlFromToken("https://api.kilocode.ai/api/profile", devToken)).toBe(
+				"http://localhost:3000/api/profile",
+			)
+			expect(getKiloUrlFromToken("https://api.kilocode.ai/api/profile/balance", devToken)).toBe(
+				"http://localhost:3000/api/profile/balance",
+			)
+			expect(getKiloUrlFromToken("https://api.kilocode.ai/api/organizations/456/defaults", devToken)).toBe(
+				"http://localhost:3000/api/organizations/456/defaults",
+			)
+			expect(getKiloUrlFromToken("https://api.kilocode.ai/api/openrouter/", devToken)).toBe(
+				"http://localhost:3000/api/openrouter/",
+			)
+			expect(getKiloUrlFromToken("https://api.kilocode.ai/api/users/notifications", devToken)).toBe(
+				"http://localhost:3000/api/users/notifications",
+			)
+		})
+
+		it("should handle invalid tokens gracefully", () => {
+			const consoleSpy = vi.spyOn(console, "warn").mockImplementation(() => {})
+			// Use a token that looks like JWT but has invalid JSON payload
+			const result = getKiloUrlFromToken("https://api.kilocode.ai/api/test", "header.invalid-json.signature")
+			expect(result).toBe("https://api.kilocode.ai/api/test")
+			expect(consoleSpy).toHaveBeenCalledWith("Failed to get base URL from Kilo Code token")
+			consoleSpy.mockRestore()
+		})
+	})
+
+	describe("Real-world URL patterns from application", () => {
+		it("should correctly handle marketplace endpoints", () => {
+			// These are the actual endpoints used in RemoteConfigLoader
+			expect(getApiUrl("/marketplace/modes")).toBe("https://kilocode.ai/api/marketplace/modes")
+			expect(getApiUrl("/marketplace/mcps")).toBe("https://kilocode.ai/api/marketplace/mcps")
+		})
+
+		it("should correctly handle app navigation URLs", () => {
+			// These are the actual URLs used in Task.ts and webviewMessageHandler.ts
+			expect(getAppUrl("/profile")).toBe("https://kilocode.ai/profile")
+			expect(getAppUrl("/support")).toBe("https://kilocode.ai/support")
+		})
+
+		it("should correctly handle token-based API calls", () => {
+			// These are the actual API endpoints used throughout the application
+			const prodToken = createProdToken()
+			expect(getKiloUrlFromToken("https://api.kilocode.ai/api/profile", prodToken)).toBe(
+				"https://api.kilocode.ai/api/profile",
+			)
+			expect(getKiloUrlFromToken("https://api.kilocode.ai/api/profile/balance", prodToken)).toBe(
+				"https://api.kilocode.ai/api/profile/balance",
+			)
+			expect(getKiloUrlFromToken("https://api.kilocode.ai/api/users/notifications", prodToken)).toBe(
+				"https://api.kilocode.ai/api/users/notifications",
+			)
+		})
+
+		it("should maintain backwards compatibility for legacy endpoints", () => {
+			expect(getExtensionConfigUrl()).toBe("https://api.kilocode.ai/extension-config.json")
+			expect(getApiUrl("/extension-config.json")).toBe("https://kilocode.ai/api/extension-config.json")
+			expect(getApiUrl("/extension-config.json")).not.toBe(getExtensionConfigUrl())
+		})
+	})
+
+	describe("Edge cases and error handling", () => {
+		it("should handle various localhost configurations", () => {
+			process.env.KILOCODE_BACKEND_BASE_URL = "http://localhost:8080"
+			expect(getApiUrl("/test")).toBe("http://localhost:8080/api/test")
+
+			process.env.KILOCODE_BACKEND_BASE_URL = "http://127.0.0.1:3000"
+			expect(getApiUrl("/test")).toBe("http://127.0.0.1:3000/api/test")
+		})
+
+		it("should handle custom backend URLs", () => {
+			process.env.KILOCODE_BACKEND_BASE_URL = "https://staging.example.com"
+
+			expect(getAppUrl()).toBe("https://staging.example.com")
+			expect(getApiUrl("/test")).toBe("https://staging.example.com/api/test")
+			expect(getAppUrl("/dashboard")).toBe("https://staging.example.com/dashboard")
+		})
+	})
+})