Environment Variables Reference

Complete reference of all environment variables supported by OpenHands

This page provides a reference of environment variables that can be used to configure OpenHands. Environment variables provide an alternative to TOML configuration files and are particularly useful for containerized deployments, CI/CD pipelines, and cloud environments.

Environment Variable Naming Convention

OpenHands follows a consistent naming pattern for environment variables:

• Core settings: Direct uppercase mapping (e.g., debug → DEBUG)
• LLM settings: Prefixed with LLM_ (e.g., model → LLM_MODEL)
• Agent settings: Prefixed with AGENT_ (e.g., enable_browsing → AGENT_ENABLE_BROWSING)
• Sandbox settings: Prefixed with SANDBOX_ (e.g., timeout → SANDBOX_TIMEOUT)
• Security settings: Prefixed with SECURITY_ (e.g., confirmation_mode → SECURITY_CONFIRMATION_MODE)

Core Configuration Variables

These variables correspond to the [core] section in config.toml:

Environment Variable	Type	Default	Description
DEBUG	boolean	false	Enable debug logging throughout the application
DISABLE_COLOR	boolean	false	Disable colored output in terminal
CACHE_DIR	string	"/tmp/cache"	Directory path for caching
SAVE_TRAJECTORY_PATH	string	"./trajectories"	Path to store conversation trajectories
REPLAY_TRAJECTORY_PATH	string	""	Path to load and replay a trajectory file
FILE_STORE_PATH	string	"/tmp/file_store"	File store directory path
FILE_STORE	string	"memory"	File store type (memory, local, etc.)
FILE_UPLOADS_MAX_FILE_SIZE_MB	integer	0	Maximum file upload size in MB (0 = no limit)
FILE_UPLOADS_RESTRICT_FILE_TYPES	boolean	false	Whether to restrict file upload types
FILE_UPLOADS_ALLOWED_EXTENSIONS	list	[".*"]	List of allowed file extensions for uploads
MAX_BUDGET_PER_TASK	float	0.0	Maximum budget per task (0.0 = no limit)
MAX_ITERATIONS	integer	100	Maximum number of iterations per task
RUNTIME	string	"docker"	Runtime environment (docker, local, cli, etc.)
DEFAULT_AGENT	string	"CodeActAgent"	Default agent class to use
JWT_SECRET	string	auto-generated	JWT secret for authentication
RUN_AS_OPENHANDS	boolean	true	Whether to run as the openhands user
VOLUMES	string	""	Volume mounts in format host:container[:mode]

LLM Configuration Variables

These variables correspond to the [llm] section in config.toml:

Environment Variable	Type	Default	Description
LLM_MODEL	string	"claude-3-5-sonnet-20241022"	LLM model to use
LLM_API_KEY	string	""	API key for the LLM provider
LLM_BASE_URL	string	""	Custom API base URL
LLM_API_VERSION	string	""	API version to use
LLM_TEMPERATURE	float	0.0	Sampling temperature
LLM_TOP_P	float	1.0	Top-p sampling parameter
LLM_MAX_INPUT_TOKENS	integer	0	Maximum input tokens (0 = no limit)
LLM_MAX_OUTPUT_TOKENS	integer	0	Maximum output tokens (0 = no limit)
LLM_MAX_MESSAGE_CHARS	integer	30000	Maximum characters that will be sent to the model in observation content
LLM_TIMEOUT	integer	0	API timeout in seconds (0 = no timeout)
LLM_NUM_RETRIES	integer	8	Number of retry attempts
LLM_RETRY_MIN_WAIT	integer	15	Minimum wait time between retries (seconds)
LLM_RETRY_MAX_WAIT	integer	120	Maximum wait time between retries (seconds)
LLM_RETRY_MULTIPLIER	float	2.0	Exponential backoff multiplier
LLM_DROP_PARAMS	boolean	false	Drop unsupported parameters without error
LLM_CACHING_PROMPT	boolean	true	Enable prompt caching if supported
LLM_DISABLE_VISION	boolean	false	Disable vision capabilities for cost reduction
LLM_CUSTOM_LLM_PROVIDER	string	""	Custom LLM provider name
LLM_OLLAMA_BASE_URL	string	""	Base URL for Ollama API
LLM_INPUT_COST_PER_TOKEN	float	0.0	Cost per input token
LLM_OUTPUT_COST_PER_TOKEN	float	0.0	Cost per output token
LLM_REASONING_EFFORT	string	""	Reasoning effort for o-series models (low, medium, high)

AWS Configuration

Environment Variable	Type	Default	Description
LLM_AWS_ACCESS_KEY_ID	string	""	AWS access key ID
LLM_AWS_SECRET_ACCESS_KEY	string	""	AWS secret access key
LLM_AWS_REGION_NAME	string	""	AWS region name

Agent Configuration Variables

These variables correspond to the [agent] section in config.toml:

Environment Variable	Type	Default	Description
AGENT_LLM_CONFIG	string	""	Name of LLM config group to use
AGENT_FUNCTION_CALLING	boolean	true	Enable function calling
AGENT_ENABLE_BROWSING	boolean	false	Enable browsing delegate
AGENT_ENABLE_LLM_EDITOR	boolean	false	Enable LLM-based editor
AGENT_ENABLE_JUPYTER	boolean	false	Enable Jupyter integration
AGENT_ENABLE_HISTORY_TRUNCATION	boolean	true	Enable history truncation
AGENT_ENABLE_PROMPT_EXTENSIONS	boolean	true	Enable skills (formerly known as microagents) (prompt extensions)
AGENT_DISABLED_MICROAGENTS	list	[]	List of skills to disable

Sandbox Configuration Variables

These variables correspond to the [sandbox] section in config.toml:

Environment Variable	Type	Default	Description
SANDBOX_TIMEOUT	integer	120	Sandbox timeout in seconds
SANDBOX_USER_ID	integer	1000	User ID for sandbox processes
SANDBOX_BASE_CONTAINER_IMAGE	string	"nikolaik/python-nodejs:python3.12-nodejs22"	Base container image
SANDBOX_USE_HOST_NETWORK	boolean	false	Use host networking
SANDBOX_RUNTIME_BINDING_ADDRESS	string	"0.0.0.0"	Runtime binding address
SANDBOX_ENABLE_AUTO_LINT	boolean	false	Enable automatic linting
SANDBOX_INITIALIZE_PLUGINS	boolean	true	Initialize sandbox plugins
SANDBOX_RUNTIME_EXTRA_DEPS	string	""	Extra dependencies to install
SANDBOX_RUNTIME_STARTUP_ENV_VARS	dict	{}	Environment variables for runtime
SANDBOX_BROWSERGYM_EVAL_ENV	string	""	BrowserGym evaluation environment
SANDBOX_VOLUMES	string	""	Volume mounts (replaces deprecated workspace settings)
AGENT_SERVER_IMAGE_REPOSITORY	string	""	Runtime container image repository (e.g., ghcr.io/openhands/agent-server)
AGENT_SERVER_IMAGE_TAG	string	""	Runtime container image tag (e.g., 1.26.0-python)
SANDBOX_KEEP_RUNTIME_ALIVE	boolean	false	Keep runtime alive after session ends
SANDBOX_PAUSE_CLOSED_RUNTIMES	boolean	false	Pause instead of stopping closed runtimes
SANDBOX_CLOSE_DELAY	integer	300	Delay before closing idle runtimes (seconds)
SANDBOX_RM_ALL_CONTAINERS	boolean	false	Remove all containers when stopping
SANDBOX_ENABLE_GPU	boolean	false	Enable GPU support
SANDBOX_CUDA_VISIBLE_DEVICES	string	""	Specify GPU devices by ID
SANDBOX_VSCODE_PORT	integer	auto	Specific port for VSCode server

Sandbox Environment Variables

Variables prefixed with SANDBOX_ENV_ are passed through to the sandbox environment:

Environment Variable	Description
SANDBOX_ENV_*	Any variable with this prefix is passed to the sandbox (e.g., SANDBOX_ENV_OPENAI_API_KEY)

Security Configuration Variables

These variables correspond to the [security] section in config.toml:

Environment Variable	Type	Default	Description
SECURITY_CONFIRMATION_MODE	boolean	false	Enable confirmation mode for actions
SECURITY_SECURITY_ANALYZER	string	"llm"	Security analyzer to use (llm, invariant)
SECURITY_ENABLE_SECURITY_ANALYZER	boolean	true	Enable security analysis

Debug and Logging Variables

Environment Variable	Type	Default	Description
DEBUG	boolean	false	Enable general debug logging
DEBUG_LLM	boolean	false	Enable LLM-specific debug logging
DEBUG_RUNTIME	boolean	false	Enable runtime debug logging
LOG_TO_FILE	boolean	auto	Log to file (auto-enabled when DEBUG=true)

Runtime-Specific Variables

Docker Runtime

Environment Variable	Type	Default	Description
SANDBOX_VOLUME_OVERLAYS	string	""	Volume overlay configurations

Docker Conversation Runtime (Canvas)

When running Agent Canvas locally via the dev-safe.mjs launcher, Canvas can forward conversation-runtime settings to its bundled Agent Server. This enables OH_CONVERSATION_RUNTIME=docker, which runs each conversation in an isolated Docker container instead of the default local process runtime.

Canvas forwards these settings only when the operator explicitly sets them. Unset values remain absent so Agent Server defaults stay authoritative.

Environment Variable	Type	Default	Description
OH_CONVERSATION_RUNTIME	string	unset	Conversation runtime type. Set to docker to run conversations in Docker containers.
OH_CONVERSATION_IMAGE	string	unset	Docker image to use for conversation containers.
OH_CONVERSATION_CONTAINER_MEMORY	string	unset	Memory limit for conversation containers (e.g., 2g).
OH_CONVERSATION_CONTAINER_CPUS	string	unset	CPU limit for conversation containers.
OH_CONVERSATION_CONTAINER_PIDS_LIMIT	string	unset	PID limit for conversation containers.
OH_CONVERSATION_CONTAINER_STARTUP_TIMEOUT	string	unset	Startup timeout for conversation containers (seconds).

These variables are specific to Canvas’s dev-safe.mjs launcher and are forwarded to the bundled Agent Server process. Docker provisioning and setting interpretation are handled by Agent Server.

Remote Runtime

Environment Variable	Type	Default	Description
SANDBOX_API_KEY	string	""	API key for remote runtime
SANDBOX_REMOTE_RUNTIME_API_URL	string	""	Remote runtime API URL

Local Runtime

Environment Variable	Type	Default	Description
RUNTIME_URL	string	""	Runtime URL for local runtime
RUNTIME_URL_PATTERN	string	""	Runtime URL pattern
RUNTIME_ID	string	""	Runtime identifier
LOCAL_RUNTIME_MODE	string	""	Enable local runtime mode (1 to enable)

Integration Variables

Git Provider Access

Environment Variable	Type	Default	Description
ALLOW_INSECURE_GIT_ACCESS	boolean	false	Allow OpenHands to connect to git providers over plain HTTP. Set this only for trusted local or internal git providers (such as Gitea/Forgejo) where HTTPS is not available.

ALLOW_INSECURE_GIT_ACCESS=true permits insecure HTTP connections to git providers. Only enable it for trusted local or internal networks that you control. Do not use it for public or untrusted git providers.

When running OpenHands with Docker, set this on the OpenHands server container:

docker run -e ALLOW_INSECURE_GIT_ACCESS=true openhands/openhands

GitHub Integration

Environment Variable	Type	Default	Description
GITHUB_TOKEN	string	""	GitHub personal access token

Third-Party API Keys

Environment Variable	Type	Default	Description
OPENAI_API_KEY	string	""	OpenAI API key
ANTHROPIC_API_KEY	string	""	Anthropic API key
GOOGLE_API_KEY	string	""	Google API key
AZURE_API_KEY	string	""	Azure API key
TAVILY_API_KEY	string	""	Tavily search API key

Server Configuration Variables

These are primarily used when running OpenHands as a server:

Environment Variable	Type	Default	Description
FRONTEND_PORT	integer	3000	Frontend server port
BACKEND_PORT	integer	8000	Backend server port
FRONTEND_HOST	string	"localhost"	Frontend host address
BACKEND_HOST	string	"localhost"	Backend host address
WEB_HOST	string	"localhost"	Web server host
SERVE_FRONTEND	boolean	true	Whether to serve frontend

Deprecated Variables

These variables are deprecated and should be replaced:

Environment Variable	Replacement	Description
WORKSPACE_BASE	SANDBOX_VOLUMES	Use volume mounting instead
WORKSPACE_MOUNT_PATH	SANDBOX_VOLUMES	Use volume mounting instead
WORKSPACE_MOUNT_PATH_IN_SANDBOX	SANDBOX_VOLUMES	Use volume mounting instead
WORKSPACE_MOUNT_REWRITE	SANDBOX_VOLUMES	Use volume mounting instead

Usage Examples

Basic Setup with OpenAI

export LLM_MODEL="gpt-4o"
export LLM_API_KEY="your-openai-api-key"
export DEBUG=true

Docker Deployment with Custom Volumes

export RUNTIME="docker"
export SANDBOX_VOLUMES="/host/workspace:/workspace:rw,/host/data:/data:ro"
export SANDBOX_TIMEOUT=300

Remote Runtime Configuration

export RUNTIME="remote"
export SANDBOX_API_KEY="your-remote-api-key"
export SANDBOX_REMOTE_RUNTIME_API_URL="https://your-runtime-api.com"

Security-Enhanced Setup

export SECURITY_CONFIRMATION_MODE=true
export SECURITY_SECURITY_ANALYZER="llm"
export DEBUG_RUNTIME=true

Notes

1. Boolean Values: Environment variables expecting boolean values accept true/false, 1/0, or yes/no (case-insensitive).

2. List Values: Lists should be provided as Python literal strings, e.g., AGENT_DISABLED_MICROAGENTS='["skill1", "skill2"]'.

3. Dictionary Values: Dictionaries should be provided as Python literal strings, e.g., SANDBOX_RUNTIME_STARTUP_ENV_VARS='{"KEY": "value"}'.

4. Precedence: Environment variables take precedence over TOML configuration files.

5. Docker Usage: When using Docker, pass environment variables with the -e flag:

   docker run -e LLM_API_KEY="your-key" -e DEBUG=true openhands/openhands
   

6. Validation: Invalid environment variable values will be logged as errors and fall back to defaults.