[Docs] Add a single exhaustive Environment-Variable reference table

[pcuci]

Env vars are scattered across docs/examples (LLM_, SANDBOX_, AGENT_, hidden debug flags). This fragmentation forces source-code grepping.

👍to upvote

[enyst]

I hear you, this is underdocumented for sure! We have this page on configuration: https://docs.all-hands.dev/modules/usage/configuration-options#llm-configuration

It's focused on the toml, but all these vars are also available as env vars, and that's not obvious perhaps. It seems like maybe we could add a ToC at the top of the page, and a description and/or examples of the rule of formation for env vars.

[lowlyocean]

It would also be helpful to know how to set debug logging to true, without having to mount a config.toml into a docker container

but all these vars are also available as env vars

If that's correct is there a prefix? Would it be CORE_DEBUG? Or just DEBUG? With the current docs, someone would have to try both to find out

[pcuci]

Setting DEBUG and DEBUG_RUNTIME to true seems to work

[enyst]

Indeed, as Paul said above. The vars directly under app config (outside a special section) are available as env vars under the same name as in toml, just uppercase, e.g. debug -> DEBUG.

Cc: @mamoodi maybe we can add more information about env vars, or a page just for them?

[lowlyocean]

By the way, DEBUG_RUNTIME didn't seem to work, but RUNTIME_DEBUG did. That one isn't mentioned on the doc page at all

[enyst]

It's this one https://github.com/All-Hands-AI/OpenHands/blob/77cd05c33b1eb292c336db772b973920f5b9daf4/openhands/runtime/impl/docker/docker_runtime.py#L164

This is only env var. 😓 It allows debugging the runtime (the sandbox). It's really way too little information about these.

[github-actions[bot]]

This issue is stale because it has been open for 30 days with no activity. Remove stale label or comment or this will be closed in 7 days.

[github-actions[bot]]

This issue is stale because it has been open for 30 days with no activity. Remove stale label or comment or this will be closed in 7 days.

[github-actions[bot]]

This issue is stale because it has been open for 40 days with no activity. Remove the stale label or leave a comment, otherwise it will be closed in 10 days.

[openhands-ai[bot]]

I'm on it! enyst can track my progress at all-hands.dev

🔴 Solvability: HARD

This is hard to resolve because the issue has no title, description, or technical context, providing only labels that suggest a documentation enhancement. Without specifics about what needs updating, where, and why, there’s no actionable path forward.

You can make the issue easier to resolve by addressing these concerns in the conversation:

• Add a clear title and a brief summary of the documentation change you want (what problem or gap are you addressing?).
• Point to the exact page/section/file and include the current text plus the proposed changes or examples to add.
• Provide context such as the affected version, target audience, and any links to related discussions or references that motivated the request.

[openhands-ai[bot]]

Summary

I have successfully addressed issue #8554 by creating a comprehensive environment variables reference table for OpenHands. Here's what was accomplished:

✅ Request Completion Checklist:

1. Created exhaustive environment variable documentation - Added a new docs/usage/environment-variables.mdx file with complete reference tables
2. Consolidated scattered documentation - Gathered all environment variables from across the codebase (LLM_, SANDBOX_, AGENT_, SECURITY_, DEBUG, etc.)
3. Organized by functional categories - Structured the documentation to match TOML configuration sections
4. Added practical examples - Included usage examples for different deployment scenarios
5. Cross-referenced existing docs - Updated configuration-options.mdx with links and naming pattern examples
6. Followed repository guidelines - Used proper MDX format, maintained consistency with existing documentation style

📋 Key Features of the New Documentation:

Comprehensive Coverage:

• 100+ environment variables documented across all categories
• Core, LLM, Agent, Sandbox, Security, Debug, Runtime, Integration, and Enterprise variables
• Deprecated variables clearly marked with replacements

Clear Organization:

• Consistent naming convention explanations
• Detailed tables with variable names, types, defaults, and descriptions
• Practical usage examples for common scenarios

User-Friendly Format:

• Searchable reference tables
• Cross-references between TOML and environment variable formats
• Notes on data types, validation, and precedence rules

🔗 Pull Request Created:

PR #10926: https://github.com/All-Hands-AI/OpenHands/pull/10926

The changes are concise and directly address the user's request without any extraneous modifications. The documentation now provides a single, comprehensive location for all environment variable information, eliminating the need for users to grep through source code to find configuration options.

This resolves the fragmentation issue described in #8554 and provides the exhaustive environment variable reference table that was requested.

_{View full conversation}