Skip to content

πŸ™Œ OpenHands: AI-Driven Development

docs: document truthy value convention for env var enable toggles (#14258)

aivong-openhandsa32af0d4c551
diff --git a/AGENTS.md b/AGENTS.md
index 203ef9cacd..ee2881a6d5 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -453,6 +453,24 @@ To add a new LLM model to OpenHands, you need to update multiple files across bo
- The `organize_models_and_providers` function groups models by provider
- Default model selection prioritizes verified models for each provider
+### Environment Variable Enable Toggles
+
+When adding a new boolean enable toggle read from an environment variable (e.g. `FEATURE_ENABLED`, `SLACK_WEBHOOKS_ENABLED`), the check **must** accept both `'true'` and `'1'` as truthy values. Older Helm chart versions default to `'1'` rather than `'true'`, so accepting only one form silently disables the feature in those deployments.
+
+**Required pattern:**
+```python
+os.getenv('MY_FEATURE_ENABLED', 'false').lower() in ('true', '1')
+```
+
+**Do not use:**
+```python
+os.getenv('MY_FEATURE_ENABLED', 'false').lower() == 'true' # breaks when value is '1'
+os.getenv('MY_FEATURE_ENABLED', 'false') == '1' # breaks when value is 'true'
+bool(os.getenv('MY_FEATURE_ENABLED')) # treats any non-empty string as True
+```
+
+This applies anywhere an env var gates a feature: backend config, web client config injectors, integration service initialization, etc. Add a unit test for the `'1'` case alongside the `'true'` case.
+
### Sandbox Settings API (SDK Credential Inheritance)
The sandbox settings API allows SDK-created conversations to inherit the user's SaaS credentials