From 6c64dc057f08217e8a1a7d9dd245040d2e39d014 Mon Sep 17 00:00:00 2001
From: RockChinQ <rockchinq@gmail.com>
Date: Fri, 13 Mar 2026 10:36:46 -0400
Subject: [PATCH] feat: support pre-setting instance_id via
 LANGBOT__INSTANCE_ID env var

In SaaS (cloud edition), the instance_id can now be injected via
environment variable to match the pod UUID. This enables zero-lookup
telemetry routing in Space - no need to reverse-lookup instance_id
to find the pod.
---
 src/langbot/pkg/core/stages/load_config.py | 31 ++++++++++++++++------
 1 file changed, 23 insertions(+), 8 deletions(-)

diff --git a/src/langbot/pkg/core/stages/load_config.py b/src/langbot/pkg/core/stages/load_config.py
index 43933def..0aa70e74 100644
--- a/src/langbot/pkg/core/stages/load_config.py
+++ b/src/langbot/pkg/core/stages/load_config.py
@@ -146,14 +146,29 @@ class LoadConfigStage(stage.BootingStage):
         await ap.instance_config.dump_config()
 
         # load or generate instance id
-        ap.instance_id = await config.load_json_config(
-            'data/labels/instance_id.json',
-            template_data={
-                'instance_id': f'instance_{str(uuid.uuid4())}',
-                'instance_create_ts': int(time.time()),
-            },
-            completion=False,
-        )
+        # In SaaS (cloud edition), the instance id can be pre-set via LANGBOT__INSTANCE_ID
+        # environment variable to match the pod UUID, enabling zero-lookup telemetry routing.
+        env_instance_id = os.environ.get('LANGBOT__INSTANCE_ID')
+        if env_instance_id:
+            ap.instance_id = await config.load_json_config(
+                'data/labels/instance_id.json',
+                template_data={
+                    'instance_id': env_instance_id,
+                    'instance_create_ts': int(time.time()),
+                },
+                completion=False,
+            )
+            # Override with env value even if file already existed with a different id
+            ap.instance_id.data['instance_id'] = env_instance_id
+        else:
+            ap.instance_id = await config.load_json_config(
+                'data/labels/instance_id.json',
+                template_data={
+                    'instance_id': f'instance_{str(uuid.uuid4())}',
+                    'instance_create_ts': int(time.time()),
+                },
+                completion=False,
+            )
 
         constants.instance_id = ap.instance_id.data['instance_id']
         constants.edition = ap.instance_config.data.get('system', {}).get('edition', 'community')