docs: update documentation for OpenHands v1.20.0

docs.json

@@ -317,6 +317,7 @@
           {
             "group": "Release Notes",
             "pages": [
+              "openhands/usage/agent-canvas/release-notes/v1.20.0",
               "openhands/usage/agent-canvas/release-notes/v1.19.0",
               "openhands/usage/agent-canvas/release-notes/v1.18.0",
               "openhands/usage/agent-canvas/release-notes/v1.17.0",

openhands/usage/agent-canvas/agent-profiles.mdx

@@ -38,6 +38,20 @@
 
 The LLM Model selector always remains visible in the chat launcher and allows you to select from any available LLM that the current Agent Profile supports. Once a conversation is started with an Agent Profile you are unable to switch to a different Agent Profile during the conversation.
 
+## Scope an Agent Profile's Secrets
+
+When the connected Agent Server advertises the `profile_secret_scope_v1` capability, the profile editor in `Settings > Agent` includes a **secret scope** picker for OpenHands and ACP profiles. Use it to control which saved secrets a profile can access:
+
+- **All** — the profile can access every saved secret (default for existing profiles).
+- **None** — the profile cannot access any saved secrets.
+- **Selected** — choose specific secret names from the list of saved secrets.
+
+Secret references that no longer exist (for example, a secret that was deleted after being selected) are preserved in the profile rather than silently removed. This prevents an unrelated edit from widening or narrowing the profile's secret access.
+
+Agent Server is the sole enforcement point for secret scoping. Canvas only stores the profile's secret scope selection; it does not perform client-side secret filtering.
+
+On Agent Servers that do not advertise `profile_secret_scope_v1`, the picker is hidden and profiles remain unrestricted.
+
 ## OpenHands Profiles
 
 Use an OpenHands profile when you want Agent Canvas to run the built-in OpenHands agent.
@@ -46,7 +60,7 @@
 
 ### Let the Agent Switch LLM Profiles
 
 The OpenHands profile editor includes a **"Let the agent switch LLM profiles"** toggle. When enabled, the agent is given the `SwitchLLMTool`, which lets it switch between available LLM profiles during a conversation. When disabled, the tool is removed from the agent's toolset.
 
 This toggle is version-gated: it appears only when the connected backend reports agent-server `1.31.0` or later. On older backends (for example, agent-server `1.29.0`–`1.30.x`) the toggle is hidden.
 

openhands/usage/agent-canvas/prebuilt-automations.mdx

@@ -3,9 +3,9 @@
 description: Get started quickly with a pre-built automation for common workflows.
 ---
 
 Agent Canvas ships with a set of pre-built automations for the most common agent workflows. Each one is a ready-to-use starting point — pick the one that fits your use case, connect it to the right backend, and you can have an automation running in minutes.
 
 ## Available Pre-built Automations
 
 | Automation | What It Does |
 |------------|-------------|
@@ -21,37 +21,50 @@
 
 In the `Automate` view, you can:
 
 - Browse existing automations
 - Inspect automation configuration and activity
 - Enable or disable automations
 - Edit an automation's LLM profile for future runs
 - Work with recommended automation flows
 
 ## How Creation Flows Usually Start
 
 The `Automations` view is mainly for browsing and managing automations that already exist.
 
 In practice, new automation setup starts in one of two ways:
 
 - From a conversation, where you ask OpenHands to `create an automation` for you
 - From a recommended automation flow in the `Automations` view
 
 For recommended automations that support a direct form setup, Agent Canvas checks the active backend's capabilities and any prerequisites, then guides you through the required input fields, a review step, and creation. If direct form setup is unavailable, it offers a conversation-assisted setup instead. Review the proposed configuration before creating an automation.
 
 Some catalog entries ship a **script bundle** — a packaged set of files that install as a deterministic automation — rather than a prompt-based preset. Script-bundle entries run their own logic for tasks like polling, deduplication, and fixed API calls, using the agent only for the parts that genuinely require judgment. When a catalog entry supports a bundle install, the setup form handles packaging and upload automatically; you just fill in the required fields.
 
 Catalog entries that accept repositories can also collect multiple repositories in a single field, so one automation can monitor several repos at once.
 
 For a detailed walkthrough, see [Creating Automations](/openhands/usage/automations/creating-automations).
 
 <Note>
   Some recommended automations depend on integrations that cannot be auto-installed as MCP servers on this backend (for example, Jira's HTTP/OpenAPI-only integration). These appear on the recommendation card with a `Needs external setup` label. The `MCPs to connect` count only covers integrations the install flow can connect automatically. You must configure externally-hosted integrations yourself before the automation can use them.
 </Note>
 
 Automations run against the active backend. Use [Manage Backends](/openhands/usage/agent-canvas/backends) to see and switch which backend your automations run on.
 
 ## Edit an Automation's LLM Profile
 
 Open an automation, select `Edit`, and use the `LLM profile` dropdown to change which saved profile future runs use. If an automation already has a profile, the edit dialog pre-selects it.
 
 Changing the LLM profile affects future automation runs. It does not rewrite previous run history.
+
+## Select an Agent Profile for an Automation
+
+When the active backend advertises agent-profile support, the automation setup and edit dialogs include an optional **agent profile** selector. Choose a saved agent profile to use for automation runs instead of the default agent.
+
+When a saved agent profile is selected:
+
+- The stable `agent_profile_id` identifies the profile sent to the backend.
+- The automation uses the selected agent profile instead of an LLM profile. Editing an automation clears any existing legacy model selection.
+
+If a previously selected agent profile has been deleted, it remains visible in the selector rather than silently switching to another profile. This lets you review the configuration before choosing a replacement.
+
+The agent profile selector appears only on backends that support agent profiles. On backends without agent-profile support, only the LLM profile dropdown is available.

openhands/usage/agent-canvas/release-notes/v1.20.0.mdx

@@ -0,0 +1,26 @@
+---
+title: Agent Canvas 1.20.0
+description: Release notes for Agent Canvas version 1.20.0
+---
+
+# Agent Canvas 1.20.0
+
+Released September 17, 2026.
+
+[View the full release on GitHub](https://github.com/OpenHands/OpenHands/releases/tag/v1.20.0).
+
+## Highlights
+
+- **Agent profile secret scoping** — Choose which saved secrets an agent profile can access (all, none, or selected names) from the profile editor in `Settings > Agent`. The control appears when Agent Server advertises the `profile_secret_scope_v1` capability. Deleted secret references are preserved rather than silently removed. See [Agent Profiles](/openhands/usage/agent-canvas/agent-profiles).
+- **Docker conversation runtime forwarding** — Canvas now forwards six conversation-runtime settings (runtime, image, memory, CPU, PID limits, startup timeout) to its bundled Agent Server when the operator explicitly sets them, enabling `OH_CONVERSATION_RUNTIME=docker` in local Canvas deployments. See [Environment Variables](/openhands/usage/environment-variables).
+- **Agent profile selection for automations** — Select a saved agent profile during automation setup and editing when the backend supports agent profiles. The selected profile is sent with `agent_profile_id` and replaces any legacy model selection. Unavailable selections remain visible. See [Pre-built Automations](/openhands/usage/agent-canvas/prebuilt-automations).
+
+## Maintenance
+
+- Mock-LLM test profiles are isolated from ambient secrets to avoid environment-dependent secret lookups in E2E tests.
+- Released agent runtime dependencies bumped: Agent Server 1.49.1, TypeScript client 1.49.1, Automation 1.13.1, Extensions 0.22.1.
+
+## Full Changelog
+
+- [GitHub release notes](https://github.com/OpenHands/OpenHands/releases/tag/v1.20.0)
+- [Compare v1.19.0 to v1.20.0](https://github.com/OpenHands/OpenHands/compare/v1.19.0...v1.20.0)

openhands/usage/environment-variables.mdx

@@ -36,7 +36,7 @@
 | `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
@@ -58,12 +58,12 @@
 | `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`) |
@@ -87,7 +87,7 @@
 | `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
@@ -110,8 +110,8 @@
 | `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 |
@@ -150,6 +150,23 @@
 |---------------------|------|---------|-------------|
 | `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 |
 |---------------------|------|---------|-------------|
@@ -172,7 +189,7 @@
 | `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. |
 
 <Warning>
   `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.
 </Warning>
 
 When running OpenHands with Docker, set this on the OpenHands server container:
@@ -193,7 +210,7 @@
 | `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