Skip to main content
Security Warning: The Local Runtime runs without any sandbox isolation. The agent can directly access and modify files on your machine. Only use this runtime in controlled environments or when you fully understand the security implications.

​
Prerequisites

Before using the Local Runtime, ensure that:
  1. You can run OpenHands using the Development workflow.
  2. For Linux and Mac, tmux must be installed and available on your system.
  3. For Windows, PowerShell is available on your system.
The standard OpenHands Docker image does not include tmux. If you want to use Local Runtime inside Docker, see the Running Without Sandbox Inside Docker section below.

​
Configuration

To use the Local Runtime, besides required configurations like the LLM provider, model and API key, you’ll need to set the following options via environment variables or the config.toml file when starting OpenHands: Via environment variables (please use PowerShell syntax for Windows PowerShell): 
# Required
export RUNTIME=local

# Optional but recommended
# The agent works in /workspace by default, so mount your project directory there
export SANDBOX_VOLUMES=/path/to/your/workspace:/workspace:rw
# For read-only data, use a different mount path
# export SANDBOX_VOLUMES=/path/to/your/workspace:/workspace:rw,/path/to/large/dataset:/data:ro
Via config.toml: 
[core]
runtime = "local"

[sandbox]
# The agent works in /workspace by default, so mount your project directory there
volumes = "/path/to/your/workspace:/workspace:rw"
# For read-only data, use a different mount path
# volumes = "/path/to/your/workspace:/workspace:rw,/path/to/large/dataset:/data:ro"
If SANDBOX_VOLUMES is not set, the runtime will create a temporary directory for the agent to work in.

​
Example Usage

Here’s an example of how to start OpenHands with the Local Runtime in Headless Mode: 
export RUNTIME=local
export SANDBOX_VOLUMES=/my_folder/myproject:/workspace:rw

poetry run python -m openhands.core.main -t "write a bash script that prints hi"

​
Use Cases

The Local Runtime is particularly useful for:
  • CI/CD pipelines where container-based sandboxing is not available.
  • Testing and development of OpenHands itself.
  • Environments where container usage is restricted (e.g. native Windows).
  • Running OpenHands inside a container without nested sandboxing (see below).

​
Running Without Sandbox Inside Docker

The standard OpenHands Docker image (docker.openhands.dev/openhands/openhands) does not include tmux, which is required for the Local Runtime. To use Local Runtime inside Docker, you need to use the Development workflow or build a custom image with tmux installed.
If you have a Docker image with tmux installed, you can run OpenHands without nested sandboxing: 
docker run -it --rm \
    -e RUNTIME=local \
    -e LOG_ALL_EVENTS=true \
    -v ~/.openhands:/.openhands \
    -v /path/to/your/workspace:/workspace \
    -p 3000:3000 \
    --name openhands-app \
    your-custom-openhands-image:tag
Key points:
  • -e RUNTIME=local: Runs without sandbox isolation
  • Mount your workspace directly with -v /path/to/your/workspace:/workspace
  • The agent executes commands directly inside the container
When using Local Runtime inside Docker, the agent operates within the container’s filesystem. Any files you want the agent to access should be mounted into the container.