🙌 OpenHands: AI-Driven Development
docs: Add repository support and missing options to headless mode documentation (#9311)
Graham Neubig1ae1c16b26b8
diff --git a/docs/usage/how-to/headless-mode.mdx b/docs/usage/how-to/headless-mode.mdxindex a28d2b9450..9ac3968a91 100644--- a/docs/usage/how-to/headless-mode.mdx+++ b/docs/usage/how-to/headless-mode.mdx@@ -18,18 +18,47 @@ poetry run python -m openhands.core.main -t "write a bash script that prints hi"You'll need to be sure to set your model, API key, and other settings via environment variables[or the `config.toml` file](https://github.com/All-Hands-AI/OpenHands/blob/main/config.template.toml).-## With Docker+### Working with Repositories++You can specify a repository for OpenHands to work with using `--selected-repo` or the `SANDBOX_SELECTED_REPO` environment variable:++> **Note**: Currently, authentication tokens (GITHUB_TOKEN, GITLAB_TOKEN, or BITBUCKET_TOKEN) are required for all repository operations, including public repositories. This is a known limitation that may be addressed in future versions to allow tokenless access to public repositories.-To run OpenHands in Headless mode with Docker:+```bash+# Using command-line argument+poetry run python -m openhands.core.main \+ --selected-repo "owner/repo-name" \+ -t "analyze the codebase and suggest improvements"++# Using environment variable+export SANDBOX_SELECTED_REPO="owner/repo-name"+poetry run python -m openhands.core.main -t "fix any linting issues"-1. Set the following environment variables in your terminal:- - `SANDBOX_VOLUMES` to specify the directory you want OpenHands to access ([See using SANDBOX_VOLUMES for more info](../runtimes/docker#using-sandbox_volumes))- - `LLM_MODEL` - the LLM model to use (e.g. `export LLM_MODEL="anthropic/claude-sonnet-4-20250514"`)- - `LLM_API_KEY` - your API key (e.g. `export LLM_API_KEY="sk_test_12345"`)+# Authentication tokens are currently required for ALL repository operations (public and private)+# This includes GitHub, GitLab, and Bitbucket repositories+export GITHUB_TOKEN="your-token" # or GITLAB_TOKEN, BITBUCKET_TOKEN+poetry run python -m openhands.core.main \+ --selected-repo "owner/repo-name" \+ -t "review the security implementation"-2. Run the following Docker command:+# Using task files instead of inline task+echo "Review the README and suggest improvements" > task.txt+poetry run python -m openhands.core.main -f task.txt --selected-repo "owner/repo"+```++## With Docker++Set environment variables and run the Docker command:```bash+# Set required environment variables+export SANDBOX_VOLUMES="/path/to/workspace" # See SANDBOX_VOLUMES docs for details+export LLM_MODEL="anthropic/claude-sonnet-4-20250514"+export LLM_API_KEY="your-api-key"+export SANDBOX_SELECTED_REPO="owner/repo-name" # Optional: requires GITHUB_TOKEN+export GITHUB_TOKEN="your-token" # Required for repository operations++# Run OpenHandsdocker run -it \--pull=always \-e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.47-nikolaik \@@ -37,6 +66,8 @@ docker run -it \-e SANDBOX_VOLUMES=$SANDBOX_VOLUMES \-e LLM_API_KEY=$LLM_API_KEY \-e LLM_MODEL=$LLM_MODEL \+ -e SANDBOX_SELECTED_REPO=$SANDBOX_SELECTED_REPO \+ -e GITHUB_TOKEN=$GITHUB_TOKEN \-e LOG_ALL_EVENTS=true \-v /var/run/docker.sock:/var/run/docker.sock \-v ~/.openhands:/.openhands \@@ -45,15 +76,20 @@ docker run -it \docker.all-hands.dev/all-hands-ai/openhands:0.47 \python -m openhands.core.main -t "write a bash script that prints hi"```-> **Note**: If you used OpenHands before version 0.44, you may want to run `mv ~/.openhands-state ~/.openhands` to migrate your conversation history to the new location.++> **Note**: If you used OpenHands before version 0.44, run `mv ~/.openhands-state ~/.openhands` to migrate your conversation history.The `-e SANDBOX_USER_ID=$(id -u)` is passed to the Docker command to ensure the sandbox user matches the host user’s-permissions. This prevents the agent from creating root-owned files in the mounted workspace.-## Advanced Headless Configurations+## Additional Options-To view all available configuration options for headless mode, run the Python command with the `--help` flag.+Common command-line options:+- `-d "/path/to/workspace"` - Set working directory+- `-f task.txt` - Load task from file+- `-i 50` - Set max iterations+- `-b 10.0` - Set budget limit (USD)+- `--no-auto-continue` - Interactive mode-### Additional Logs+Run `poetry run python -m openhands.core.main --help` for all options, or use a [`config.toml` file](https://github.com/All-Hands-AI/OpenHands/blob/main/config.template.toml) for more flexibility.-For the headless mode to log all the agent actions, in the terminal run: `export LOG_ALL_EVENTS=true`+Set `export LOG_ALL_EVENTS=true` to log all agent actions.\ No newline at end of file