Skip to content

🙌 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.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
+
+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 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