Add documentation for Runbook Agent access setting

src/pages/docs/octopus-ai/mcp/remote/index.md

@@ -1,7 +1,7 @@
 ---
 layout: src/layouts/Default.astro
 pubDate: 2026-08-17
-modDate: 2026-10-20
+modDate: 2026-10-26
 title: Octopus Remote MCP
 navTitle: Remote MCP
 navSection: Octopus Remote MCP
@@ -191,6 +191,8 @@ We plan to add OAuth authentication in a future release. Until then, AI assistan
 
 Octopus Remote MCP uses the same security boundary as the Octopus REST API. Permissions for the user or service account that owns the API key apply in the same way.
 
+To stop agents from running a runbook, use the runbook's [AI agent access](/docs/runbooks/runbooks-vs-deployments#ai-agent-access) setting. The MCP server returns no environments for a blocked runbook, so agents don't try runs that would fail.
+
 ## Turn off Remote MCP
 
 To turn off Remote MCP, go to **Configuration > Settings > MCP Controls**. Clear the **Enable Remote MCP** checkbox, then select **Save**.

src/pages/docs/octopus-ai/mcp/remote/use-cases.md

@@ -1,7 +1,7 @@
 ---
 layout: src/layouts/Default.astro
 pubDate: 2026-08-17
-modDate: 2026-08-17
+modDate: 2026-10-26
 title: Octopus Remote MCP use cases
 navTitle: Use cases
 description: Explore how Octopus Remote MCP helps teams track releases, diagnose failures, automate deployments, audit changes, and manage tenants.
@@ -43,7 +43,7 @@ Example prompts:
 - "Generate release notes for release 2.4.1 and attach them to the release."
 - "Run the Restart payment workers runbook in Production."
 
-Operations that make changes run with the permissions of the API key used to connect the assistant. Use a dedicated [Agent Service Account](/docs/security/users-and-teams/service-accounts#agent-service-accounts) and grant it only the permissions it needs.
+Operations that make changes run with the permissions of the API key used to connect the assistant. Use a dedicated [Agent Service Account](/docs/security/users-and-teams/service-accounts#agent-service-accounts) and grant it only the permissions it needs. To stop agents from running a sensitive runbook, use the runbook's [AI agent access](/docs/runbooks/runbooks-vs-deployments#ai-agent-access) setting.
 
 ## Operational oversight
 

src/pages/docs/runbooks/config-as-code-runbooks.md

@@ -1,7 +1,7 @@
 ---
 layout: src/layouts/Default.astro
 pubDate: 2024-11-24
-modDate: 2026-10-13
+modDate: 2026-10-26
 title: Config as Code runbooks
 description: Details about using configuration as code with runbooks.
 navOrder: 20
@@ -83,6 +83,12 @@ Assuming your default branch is protected, this means that your old 'published'
 
 💡 If you are using Octopus's built in roles, keep these permissions in mind when moving your draft runbooks out of the 'migrated-drafts/' folder and consider storing these runbooks on a non-default branch.
 
+## AI agent access
+
+A runbook's [AI agent access](/docs/runbooks/runbooks-vs-deployments#ai-agent-access) setting is stored in its OCL file, so it can differ between branches and commits. Octopus only writes `agent_access` to the file when the runbook blocks agents, so saving a runbook that lets agents run it doesn't change its OCL file.
+
+When an AI agent runs a Config as Code runbook, Octopus checks the setting in the version being run. An agent can still run a blocked runbook from a branch, tag, or commit where the setting lets agents run it. Protect your default branch so changes to the setting go through your usual review process.
+
 ## Snapshots vs commits
 
 Another exciting thing about CaC Runbooks is that every revision to your runbook process, settings and variables is captured in your commit history. This means that you can now re-run any previous version of your runbook without the need for snapshots.

src/pages/docs/runbooks/runbook-permissions/index.md

@@ -1,7 +1,7 @@
 ---
 layout: src/layouts/Default.astro
 pubDate: 2023-01-01
-modDate: 2026-08-17
+modDate: 2026-10-26
 title: Runbooks permissions
 description: Permissions are available to help you manage access to Runbooks.
 navOrder: 20
@@ -25,6 +25,10 @@ Permissions are available to help you manage access to Runbooks, these include:
 
 You can limit your teams ability to create runbooks by disabling these permissions.
 
+:::div{.hint}
+To stop AI agents from running a runbook, use the runbook's [AI agent access](/docs/runbooks/runbooks-vs-deployments#ai-agent-access) setting. It works alongside these permissions and only restricts agents.
+:::
+
 There are roles we include out-of-the-box to encapsulate these new permissions:
 
 | Role | Description |

src/pages/docs/runbooks/runbooks-vs-deployments/index.md

@@ -1,7 +1,7 @@
 ---
 layout: src/layouts/Default.astro
 pubDate: 2023-01-01
-modDate: 2023-10-04
+modDate: 2026-10-26
 title: Runbooks vs Deployments
 description: Describing the differences between a deployment and a runbook.
 navOrder: 10
@@ -34,7 +34,7 @@ A [project's variables](/docs/projects/variables) are shared between the deploym
 
 In Octopus 2020.2 and earlier, runbooks could be executed against any environment for which the user had an appropriately scoped `RunbookRunCreate` permission.
 
-From **Octopus 2020.3**, it's also possible to choose which environments a runbook can be run in by selecting this from the *Run settings* in **Runbook ➜ Settings**:
+From **Octopus 2020.3**, it's also possible to choose which environments a runbook can be run in by selecting this from the *Run Settings* in **Runbook ➜ Settings**:
 
 :::figure
 ![Runbook environments choice](/docs/img/runbooks/runbooks-vs-deployments/runbook-runsettings-environments.png)
@@ -50,9 +50,43 @@ You can select the runbook to run in:
 In Octopus 2020.2 and earlier, if you need to restrict the environment that a runbook can be executed in, you can achieve this by adding an [Environment run condition](/docs/projects/steps/conditions/#environments) in each step of the runbook process.
 :::
 
+### AI agent access
+
+AI agent access controls whether AI agents can run a runbook. Use it to keep agents away from sensitive runbooks, such as ones that change production infrastructure, while still letting them run routine ones.
+
+The setting sits below **Environments** in the *Run Settings* of **Runbook ➜ Settings**:
+
+:::figure
+![The AI agent access setting on the runbook settings page, with the options AI agents can run this runbook and AI agents can't run this runbook](/docs/img/runbooks/runbooks-vs-deployments/runbook-runsettings-ai-agent-access.png)
+:::
+
+You can choose:
+
+- **AI agents can run this runbook** (the default)
+- **AI agents can't run this runbook**
+
+Blocking only applies to runs started with an AI agent's credentials: an [agent API key](/docs/api/authentication/create-an-api-key#creating-an-agent-api-key) or an [agent service account](/docs/security/users-and-teams/service-accounts#agent-service-accounts). This includes agents using the [Octopus MCP server](/docs/octopus-ai/mcp), and [webhook triggers](/docs/runbooks/webhook-runbook-trigger#authentication) called with an agent API key. Runs started by users, scheduled triggers, and webhook triggers that use a shared secret aren't affected.
+
+When a runbook is blocked, Octopus rejects an agent's run with an error before the run starts. Agents also see an empty list of environments for the runbook, so they don't try runs that would fail.
+
+AI agent access adds to [runbook permissions](/docs/runbooks/runbook-permissions) rather than replacing them.
+
+Agents can change the setting to block themselves, but they can't change it back. To let agents run it again, a user or a non-agent service account needs to change the setting. In the API, the setting is the runbook's `AgentAccess` property, set to `Allowed` or `Blocked`. If you leave `AgentAccess` out when you modify a runbook, Octopus keeps its current value.
+
+:::div{.warning}
+AI agent access is an advisory control. It stops agents from running a runbook directly, but it isn't a security boundary. Agents can get around it:
+
+- An agent that can edit the runbook can still change its other settings, such as its environments.
+- An agent can create a [scheduled trigger](/docs/runbooks/scheduled-runbook-trigger) or a shared-secret [webhook trigger](/docs/runbooks/webhook-runbook-trigger) that runs the runbook. These runs use the Octopus system user, so they aren't blocked.
+- Octopus checks the setting when it creates a run. Runs an agent queued before the runbook was blocked still start, including runs scheduled for later.
+- For [Config as Code runbooks](/docs/runbooks/config-as-code-runbooks#ai-agent-access), an agent can run from a branch or commit where the setting still lets agents run the runbook.
+
+For runbooks you want to protect, don't give agents permission to edit runbooks (`RunbookEdit`) or triggers (`TriggerCreate` and `TriggerEdit`).
+:::
+
 ## Retention policy
 
-Project [Lifecycles](/docs/releases/lifecycles) and their retention policies do not apply to runbooks (only deployments). From **Octopus 2020.3**, it's possible to set a retention policy for a runbook by selecting this from the *Run settings* in **Runbook ➜ Settings**:
+Project [Lifecycles](/docs/releases/lifecycles) and their retention policies do not apply to runbooks (only deployments). From **Octopus 2020.3**, it's possible to set a retention policy for a runbook by selecting this from the *Run Settings* in **Runbook ➜ Settings**:
 
 :::figure
 ![Runbook retention policies](/docs/img/runbooks/runbooks-vs-deployments/runbook-runsettings-retention.png)
@@ -86,3 +120,7 @@ Runbooks are similar to deployments in that they also take a copy of the process
 **Package versions are included in a snapshot**
 Similar to releases, the version of any packages that are used in the runbook are also snapshotted. This means if a newer version of the package is uploaded, and you wish to use it in your runbook, you will need to create a new snapshot of the runbook.
 :::
+
+## Version notes
+
+- AI agent access for runbooks is available from Octopus **2026.4.9164**.

src/pages/docs/runbooks/webhook-runbook-trigger/index.md

@@ -1,7 +1,7 @@
 ---
 layout: src/layouts/Default.astro
 pubDate: 2026-08-06
-modDate: 2026-08-06
+modDate: 2026-10-26
 title: Webhook runbook triggers
 description: Webhook runbook triggers let an external system run a runbook by sending an HTTP request to Octopus.
 navOrder: 45
@@ -116,6 +116,7 @@ The runbook run is created as the owner of the API key, which means:
 
 - The key's owner needs the `RunbookRunCreate` [permission](/docs/runbooks/runbook-permissions) for the project, and for every environment and tenant the trigger targets.
 - The run appears in the audit log and task list as being run by that user, rather than by the Octopus system user.
+- If the key is an [agent API key](/docs/api/authentication/create-an-api-key#creating-an-agent-api-key), or belongs to an agent service account, the run is an agent run, and the runbook's [AI agent access](/docs/runbooks/runbooks-vs-deployments#ai-agent-access) setting applies.
 
 We recommend using a [service account](/docs/security/users-and-teams/service-accounts) scoped to only what the runbook needs, rather than a key belonging to a person.
 

src/pages/docs/security/users-and-teams/service-accounts.md

@@ -1,7 +1,7 @@
 ---
 layout: src/layouts/Default.astro
 pubDate: 2023-01-01
-modDate: 2026-06-19
+modDate: 2026-10-26
 title: Service accounts
 description: Creating Service Accounts to provide individual services with the least privileges required for the tasks they will perform.
 navOrder: 2
@@ -56,7 +56,7 @@ Once you have created an [Octopus API key](/docs/api/authentication/create-an-ap
 
 If you're connecting an AI agent to Octopus—such as the [Octopus MCP server](/docs/octopus-ai/mcp) or any other automated tooling that runs without a human user session—create an **Agent Service Account** rather than a regular service account. Agent service accounts are a dedicated identity type for AI agents, and they're labeled as such across the product, making agent activity easy to identify and audit.
 
-Any API key created under an agent service account is automatically treated as an agent key. This means you can filter for agent activity separately from human activity in the [audit log](/docs/security/users-and-teams/auditing) and on the **API Keys** page.
+Any API key created under an agent service account is automatically treated as an agent key. This means you can filter for agent activity separately from human activity in the [audit log](/docs/security/users-and-teams/auditing) and on the **API Keys** page. It also means a runbook's [AI agent access](/docs/runbooks/runbooks-vs-deployments#ai-agent-access) setting applies to any runbook run the account starts.
 
 To create an agent service account: