From 3c4890790483008cfb1d07cf558922ebb70bc584 Mon Sep 17 00:00:00 2001
From: Josh Lambert <josh@kilocode.ai>
Date: Wed, 18 Mar 2026 13:25:41 -0400
Subject: [PATCH] docs: document environment variables for local backend
 testing

---
 CONTRIBUTING.md | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index ed0cb83d8a..59571d307f 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -70,6 +70,26 @@ kilo serve           # Start headless API server
 kilo web             # Start server + open web interface
 ```
 
+### Testing with a local backend
+
+To point the CLI at a local backend (e.g., a locally running Kilo API server on port 3000), set the `KILO_API_URL` environment variable:
+
+```bash
+KILO_API_URL=http://localhost:3000 bun dev
+```
+
+This redirects all gateway traffic (auth, model listing, provider routing, profile, etc.) to your local server. The default is `https://api.kilo.ai`.
+
+There are also optional overrides for other services:
+
+| Variable                  | Default                          | Purpose                                   |
+| ------------------------- | -------------------------------- | ----------------------------------------- |
+| `KILO_API_URL`            | `https://api.kilo.ai`            | Kilo API (gateway, auth, models, profile) |
+| `KILO_SESSION_INGEST_URL` | `https://ingest.kilosessions.ai` | Session export / cloud sync               |
+| `KILO_MODELS_URL`         | `https://models.dev`             | Model metadata                            |
+
+> **VS Code:** The repo includes a "VSCode - Run Extension (Local Backend)" launch config in `.vscode/launch.json` that sets `KILO_API_URL=http://localhost:3000` automatically.
+
 ### Pull Request Expectations
 
 - **Issue First Policy:** All PRs must reference an existing issue.