From 1ae1c16b26b859c5d435b95cabbb640eb8c95e28 Mon Sep 17 00:00:00 2001
From: Graham Neubig <neubig@gmail.com>
Date: Sat, 28 Jun 2025 21:05:52 -0400
Subject: [PATCH] docs: Add repository support and missing options to headless
 mode documentation (#9311)

Co-authored-by: openhands <openhands@all-hands.dev>
Co-authored-by: Engel Nyst <enyst@users.noreply.github.com>
---
 docs/usage/how-to/headless-mode.mdx | 64 ++++++++++++++++++++++-------
 1 file changed, 50 insertions(+), 14 deletions(-)

diff --git a/docs/usage/how-to/headless-mode.mdx b/docs/usage/how-to/headless-mode.mdx
index 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
 
-To run OpenHands in Headless mode with Docker:
+You can specify a repository for OpenHands to work with using `--selected-repo` or the `SANDBOX_SELECTED_REPO` environment variable:
 
-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"`)
-
-2. Run the following Docker command:
+> **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.
 
 ```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"
+
+# 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"
+
+# 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 OpenHands
 docker 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