[rhysparry]

Background

Octopus now has several controls that restrict what AI agents can do with runbooks. Each control has its own docs. No page explains how the controls fit together. No page helps someone who needs to respond after an agent ran something they didn't expect.

• Linear: LEV-2025
• Intended direction: Slack

Results

Adds a guide page at /docs/octopus-ai/restricting-ai-agents. The page serves two readers:

• Someone who wants to restrict AI agents before anything goes wrong
• Someone whose agent ran something unexpected and who wants to stop it happening again

The page explains how Octopus identifies an AI agent and how to find an agent run in the audit log. It then covers least-privilege permissions and the three run controls. It says once that the controls are advisory and that permissions are the real boundary. OAuth for Remote MCP is rolling out now. The page treats OAuth connections as available.

Smaller changes:

• The policy examples page gains an example that blocks AI agent runbook runs.
• The auditing page now uses the real filter labels. It also says Octopus records a masked key for every API key, not only for agent API keys.
• The runbook permissions and Remote MCP pages link to the new page.

How to review this PR

Start with the new page. It follows the guide page standard in contributing/standards. The most useful feedback is on product accuracy and on whether the investigation path reads well.

Navigation paths use > as the standards ask. Most existing pages use ➜.

Reducing risk

• Site build passes
• Link crawl passes
• Anchors on every changed page checked
• UI labels and behavior checked against the Octopus Server source

🤖 Generated with Claude Code

🤖 Agent's description, endorsed by Rhys

[team-marketing-branch-protections]

Pull request environment is available at https://stoctodocspr3544.z22.web.core.windows.net/.

You can view the ephemeral environment status in Octopus Deploy.

This environment will be automatically deprovisioned when the pull request is closed, or after 7 days of inactivity.

[akirayamamoto]

Good idea linking the pages.

[akirayamamoto]

This document is very complete but also quite long. I think it is alright to merge as is but if you are keen check if there are ways to break it down.

[akirayamamoto]

Aneita asked in the showcase thread how to make AI agent runs include a manual intervention step. The existing "Require a manual intervention step" example is almost that already. Could we add a note under it?

To apply this only to runs started by an AI agent, add input.Actor.Type == "Agent" to the conditions.

That example also misses two cases. Worth adding these checks to its step match:

step.Enabled
step.IsRequired

Without	Someone can
step.Enabled	disable the step. It's still in Steps, but it doesn't run.
step.IsRequired	skip the step by name. SkippedSteps keeps whatever the caller sent, so a name never matches step.Id. A required step can't be skipped at all.

I'll raise the server side (turning names into IDs before policies run) separately.

[akirayamamoto]

What do you think about "Restricting and investigating AI agent activity"? The page covers both limiting agents and looking into runs they started, so the current title only covers half of it.

[rhysparry]

It's a bit wordy. Perhaps we could split the two, but there are definitely benefits to having a single page.

[akirayamamoto]

Heads up, not blocking. docs#3543 renames this section to "Block AI agents" to match the new UI copy. The anchor changes to #block-ai-agents, and "Agent Responses" / "respond" become "Block AI agents" / "action".

No need to wait for mine. Feel free to merge this as is, and I'll do the renaming on this page in docs#3543 once yours is in.