add claude agent step docs

dictionary-octopus.txt

@@ -52,6 +52,7 @@ Blkio
 bootstrap
 bootstrapped
 bootstrapper
+bubblewrap
 bufio
 buildevent
 buildinfo
@@ -69,6 +70,7 @@ choco
 cicd
 CIFS
 classiclink
+ClaudeCodeBehaviour
 clientcertificate
 cloudapi
 cloudapp
@@ -131,6 +133,7 @@ Djava
 Dockerfiles
 dockerhub
 Domainname
+dontAsk
 DONTVALIDATEPATH
 dotmemory
 dotnetcore
@@ -156,6 +159,7 @@ environmentids
 eprintfn
 esac
 exfiltrate
+exfiltration
 expressjs
 externalgroups
 externalusers
@@ -239,6 +243,7 @@ ITSM
 javac
 jdbc
 jjones
+journalctl
 jsondecode
 JSSE
 jwks
@@ -292,6 +297,7 @@ minifier
 minlevel
 MITM
 Mkto
+modelcontextprotocol
 Moines
 mozjpeg
 mozroots
@@ -480,6 +486,8 @@ Runspace
 runtimes
 sakila
 SAMEORIGIN
+sandboxed
+sandboxing
 Schannel
 SCIM
 scopeduserroles
@@ -581,6 +589,7 @@ undeployed
 undeploying
 uniquestring
 Unmarshal
+unsandboxed
 updateprogress
 upgradeavailability
 upgradelog
@@ -614,6 +623,7 @@ WEBSVR
 westeurope
 WFLYCTL
 WFLYUT
+wildcarded
 Wildfly
 windir
 windowsfeatures

public/docs/img/octopus-ai/claude-agent-step/auto-mode-config.png.json

@@ -0,0 +1 @@
+{"width":1460,"height":1134,"updated":"2026-07-08T04:16:53.233Z"}

public/docs/img/octopus-ai/claude-agent-step/claude-usage-summary.png.json

@@ -0,0 +1 @@
+{"width":1444,"height":290,"updated":"2026-07-08T04:16:53.246Z"}

public/docs/img/octopus-ai/claude-agent-step/injection-check.png.json

@@ -0,0 +1 @@
+{"width":1460,"height":1434,"updated":"2026-07-08T04:16:53.270Z"}

public/docs/img/octopus-ai/claude-agent-step/mcp-server-drawer.png.json

@@ -0,0 +1 @@
+{"width":1944,"height":2148,"updated":"2026-07-08T04:16:53.292Z"}

public/docs/img/octopus-ai/claude-agent-step/security-section.png.json

@@ -0,0 +1 @@
+{"width":1460,"height":1548,"updated":"2026-07-08T04:16:53.327Z"}

public/docs/img/octopus-ai/claude-agent-step/skills-drawer.png.json

@@ -0,0 +1 @@
+{"width":1944,"height":1056,"updated":"2026-07-08T04:16:53.357Z"}

public/docs/img/octopus-ai/claude-agent-step/step-editor-prompt-and-settings.png.json

@@ -0,0 +1 @@
+{"width":1460,"height":1478,"updated":"2026-07-08T04:16:53.409Z"}

public/docs/img/octopus-ai/claude-agent-step/step-library-run-claude.png.json

@@ -0,0 +1 @@
+{"width":680,"height":440,"updated":"2026-07-08T04:16:53.437Z"}

public/docs/img/octopus-ai/claude-agent-step/task-log-streaming.png.json

@@ -0,0 +1 @@
+{"width":1710,"height":1002,"updated":"2026-07-08T04:16:53.462Z"}

public/docs/img/octopus-ai/claude-agent-step/transcript-permission.png.json

@@ -0,0 +1 @@
+{"width":1130,"height":328,"updated":"2026-07-08T04:16:53.486Z"}

src/pages/docs/octopus-ai/claude-agent-step/getting-started.md

@@ -0,0 +1,158 @@
+---
+layout: src/layouts/Default.astro
+pubDate: 2026-07-07
+modDate: 2026-07-07
+title: Getting started with the Claude Agent Step
+navTitle: Getting Started
+navSection: Claude Agent Step
+description: Add the Run Claude Agent step to a deployment process or runbook, run it, and read the agent's output.
+navOrder: 1
+---
+
+The Claude Agent Step runs [Claude Code](https://code.claude.com/docs/en/overview) as a step in your deployment process or runbook. This page walks through adding the **Run Claude Agent** step to a process, running it, and reading what the agent did, then gives you two examples you can start from: a failure investigation and a pre-promotion smoke test.
+
+## Add a Run Claude Agent step
+
+Follow these steps to add the step to a deployment process or runbook and configure the prompt, credentials, and security controls it runs with.
+
+Before you begin, you'll need:
+
+- An [Anthropic API key](https://console.anthropic.com/), stored in Octopus as a **sensitive** project or library variable (for example `anthropic-api-key`). You reference it from the step as `#{anthropic-api-key}`. Storing it as a [sensitive variable](/docs/projects/variables/sensitive-variables) keeps it out of the task log.
+- The [Claude Code](https://code.claude.com/docs/en/setup) CLI on the `PATH` of whatever runs the step: a worker, a deployment target, or the Octopus Server if you run the step on the server. The step launches the `claude` executable as a child process.
+- If you pick the **Sandbox runtime** sandbox mode: the `srt` executable from Anthropic's [sandbox-runtime](https://code.claude.com/docs/en/sandboxing) on the `PATH`. The step checks the version and fails if it's missing or too old.
+
+To add and configure the step:
+
+1. Open your deployment process or runbook and select **Add step**.
+2. Search for `claude` and choose **Run Claude Agent** from the step library.
+
+   :::figure
+   ![The Run Claude Agent step card in the step library](/docs/img/octopus-ai/claude-agent-step/step-library-run-claude.png)
+   :::
+
+3. In **Prompt**, describe the task in plain language, the way you would prompt Claude Code. The prompt can use Octopus variables (for example `#{Octopus.Environment.Name}`), which are substituted before the agent runs. Be specific about what you want the agent to do and what "success" looks like.
+4. In **Claude Settings**, set **API Key** to a reference to your sensitive variable, for example `#{anthropic-api-key}`.
+5. Optionally, set **Model Version** to a model such as `claude-opus-4-8` or `claude-haiku-4-5`, or leave it blank to use the Claude Code CLI's current default. The **Effort** setting trades thoroughness against cost and latency; leave it blank to use the default.
+
+   :::figure
+   ![The Run Claude Agent step editor showing the Prompt and Claude Settings sections filled in](/docs/img/octopus-ai/claude-agent-step/step-editor-prompt-and-settings.png)
+   :::
+
+6. In **Security**, select a **Sandboxing** mode. You must pick one of the three values to save the step:
+   - **Bash sandbox** uses Claude Code's built-in sandbox. It confines the agent's `Bash` commands, but file operations and hooks still run on the host.
+   - **Sandbox runtime** runs the whole agent process inside Anthropic's `sandbox-runtime`, for stronger, whole-process isolation.
+   - **None** applies no sandboxing. The agent runs with the same permissions as the account running the step (the Tentacle/Kubernetes Agent service account). We don't recommend it unless you have your own isolation around the worker.
+
+   For a first run on a Linux worker, **Sandbox runtime** is the safest starting point. Each mode and how to configure it is covered in [Security & Compliance](/docs/octopus-ai/claude-agent-step/security-and-compliance#sandboxing).
+
+   :::div{.warning}
+   The **Bash sandbox** and **Sandbox runtime** modes are supported on Linux (and WSL2) workers. They aren't available on Windows workers. If you're evaluating the step on a Windows worker, use **None** and rely on isolation such as the account Tentacle runs under.
+   :::
+
+7. Select a **Permission Mode**. For your first run, select **dontAsk mode**. The step runs non-interactively, with no way to approve an action mid-run, so `dontAsk` is the standard choice: the agent may use any tool you allow and is denied everything else. The other option, Auto mode (a mode that uses a classifier model to determine whether to run a tool), is covered in [Security & Compliance](/docs/octopus-ai/claude-agent-step/security-and-compliance#tool-permissions).
+8. In **Tool Permissions**, list the tools the agent needs, one per line. For example:
+
+   ```text
+   Read
+   Glob
+   Bash(pwd)
+   Bash(ls *)
+   ```
+
+   Start with minimal permissions and add to it as you learn what the agent needs.
+9. Optionally, under **Agent Capabilities**, add **Skills** or **MCP** servers. See [Extending the Claude Agent Step](/docs/octopus-ai/claude-agent-step/tools).
+10. Under **Additional Configuration Options**, set a **Turn Limit** to cap how many turns the agent can take before the step stops. One turn is a single request/response cycle with the model. The default is 10.
+11. Optionally, set a **Maximum Budget** as a spend cap in USD. Leave it blank for no limit.
+12. Leave **Prompt Injection Check** switched on. Before the agent runs, Octopus screens the prompt, deployment variables, MCP configuration, and skills with a fast model (`claude-haiku-4-5` by default) and blocks the step if it detects an injection attempt.
+13. Save the step.
+
+The **Run Claude Agent** step appears in your deployment process or runbook, ready to run.
+
+## Run the step
+
+A Run Claude Agent step runs like any other step. Run the process that contains it, then watch what the agent does in the task log.
+
+To run the step and watch its output:
+
+1. Create a release and deploy it, as you would for any other step.
+2. Open the task and expand the step in the **task log**. While the step runs, the agent streams its output in real time. At the default log level you see the agent's narration and its final answer.
+3. To also see the agent's thinking, each tool call, and the exact command Octopus ran, switch the log to verbose (or download the raw log).
+
+:::figure
+![The task log showing the Claude agent streaming its output](/docs/img/octopus-ai/claude-agent-step/task-log-streaming.png)
+:::
+
+When the task finishes, the step's log ends with its usage lines and `Claude Code invocation complete.`, and the task page shows a **Claude Usage Summary** panel.
+
+## Run outputs
+
+Every completed run leaves the following outputs on the task page.
+
+| Output | Where it appears | What it contains |
+| --- | --- | --- |
+| Task log | The step's section of the task log | The agent's streamed narration and final answer. The verbose level adds its thinking and each tool call. |
+| Claude Usage Summary | A panel on the task page | Each Claude step with its model, token count, cost, and any budget cap, plus a total. Use it to keep an eye on what a run costs. |
+| Artifacts | The task's artifacts | Files the agent attached using the built-in `octopus-artifacts` skill, ready to download. See [Built-in skills](/docs/octopus-ai/claude-agent-step/tools#built-in-skills). |
+| Transcript | Stored on the Octopus Server, gated behind a dedicated permission | The full, verbose session, recorded for auditing. See [Security & Compliance](/docs/octopus-ai/claude-agent-step/security-and-compliance) for who can read it and how. |
+
+:::figure
+![The Claude Usage Summary panel on the task page](/docs/img/octopus-ai/claude-agent-step/claude-usage-summary.png)
+:::
+
+## Investigate a failed deployment
+
+When a deployment fails, the fastest first responder is one that's already there. Add an agent step that runs only when an earlier step fails, and it attaches a first-pass diagnosis to the failed task, while the deployment is still in its failed state, instead of waiting for someone to start digging.
+
+To add an automatic failure investigation to a deployment process:
+
+1. Add a **Run Claude Agent** step to your deployment process (see [Add a Run Claude Agent step](#add-a-run-claude-agent-step)).
+2. Set the step's [run condition](/docs/projects/steps/conditions#run-condition) to **Only if the previous step failed**.
+3. Set the **Prompt** to:
+
+   ```text
+   A previous step in this deployment has failed. Investigate the cause.
+
+   Read ./deployment-variables.json to learn which project, environment, and
+   release was being deployed. Then inspect the deployed infrastructure to work
+   out why it failed: check whether the service is healthy, read the most recent
+   application and container logs, and check the status of the pods or processes
+   that were meant to be running.
+
+   Report the single most likely root cause and the specific evidence you found
+   for it. Do not attempt to fix anything.
+   ```
+
+4. Set **Permission Mode** to **dontAsk mode**.
+5. In **Tool Permissions**, allow only the read-only commands your investigation needs, for example `Read`, `Glob`, `Grep`, `Bash(cat *)`, `Bash(kubectl get *)`, `Bash(kubectl describe *)`, `Bash(kubectl logs *)`, and `Bash(curl *)`.
+6. Select **Sandbox runtime** as the sandbox mode on a Linux worker (or **None** while evaluating on Windows or macOS).
+
+:::div{.hint}
+Keep the allowlist to read-only tools. The prompt tells the agent not to change anything, but the allowlist helps to enforces that. With only read and query commands allowed, an agent that decides to "fix" the problem anyway is denied the tool it reaches for, and the step fails rather than making the outage worse. Match the list to how your infrastructure is inspected. For a virtual machine you might allow `Bash(systemctl status *)` and `Bash(journalctl *)` in place of the `kubectl` commands above.
+:::
+
+Because the step runs only on failure, the deployment still ends in a failed state, which is what you want: the agent explains the failure, it doesn't paper over it. Its summary appears in the task log next to the step that failed.
+
+## Smoke-test a service before promotion
+
+Before promoting a release, you want an agent to check that the deployed service is healthy, and to fail the step if it isn't so the promotion stops. By default an agent run always *succeeds* when the agent finishes normally, so the agent has to explicitly signal failure; the built-in `octopus-fail-deployment` skill handles this when your prompt states a failure condition.
+
+To add a smoke test to a deployment process:
+
+1. Add a **Run Claude Agent** step after the steps that deploy the service.
+2. Set the **Prompt** to:
+
+   ```text
+   Smoke-test the service that was just deployed. Send a request to its health endpoint
+   and check for an HTTP 200 response. If it does not return 200 after a couple of retries,
+   fail the deployment with a short reason describing what you saw.
+   ```
+
+3. Set **Permission Mode** to **dontAsk mode**.
+4. In **Tool Permissions**, allow `Bash(curl *)`, plus any other command your check needs.
+5. Select **Sandbox runtime** as the sandbox mode on a Linux worker.
+
+If the health check doesn't pass, the agent emits the failure tag from the `octopus-fail-deployment` skill in its final message, and Octopus fails the step and surfaces the agent's reason in the task log, stopping the promotion. Stating the failure condition in the prompt is enough. See [Built-in skills](/docs/octopus-ai/claude-agent-step/tools#built-in-skills) for how the skill works.
+
+:::div{.hint}
+As with any AI tool, the outcome of a check like this is not deterministic. Treat the agent's verdict as a helpful check, not a hard gate, and pair it with deterministic checks where the outcome matters. See [Limitations](/docs/octopus-ai/claude-agent-step#limitations) for more information.
+:::

src/pages/docs/octopus-ai/claude-agent-step/index.md

@@ -0,0 +1,40 @@
+---
+layout: src/layouts/Default.astro
+pubDate: 2026-07-03
+modDate: 2026-07-07
+title: How the Claude Agent Step works
+navTitle: Overview
+navSection: Claude Agent Step
+description: What the Claude Agent Step is, how it fits into a deployment, and the limits to plan around before you build on it.
+navOrder: 4
+---
+
+The Claude Agent Step runs [Claude Code](https://code.claude.com/docs/en/overview) (Anthropic's agentic developer tool) as a step in your deployment process or runbook. This page explains the step, both what it provides, and why it runs inside the deployment. When you're ready to add the step to a process, start with [Getting started with the Claude Agent Step](/docs/octopus-ai/claude-agent-step/getting-started).
+
+:::div{.warning}
+The Claude Agent Step is an **alpha** release. The configuration and behavior may change between releases, and we're actively looking for feedback on how you use it. Don't build critical, unattended automation on it yet.
+:::
+
+## The Claude Agent Step
+
+The Claude Agent Step runs an AI agent on a worker or deployment target, with access to your deployment's context. Understanding what the step provides, and what it deliberately leaves to you, helps you decide which jobs to hand the agent and how much access to grant it.
+
+Octopus already holds the two things an agent needs to be useful during a deployment: the *context* (the target, the variables, the release, and the logs and output of earlier steps) and *access* to your targets. Until now, using an AI agent against that context meant either wiring up an agent outside Octopus by hand, or running an unsandboxed script step with no scoping and no audit trail.
+
+The Claude Agent Step gives you a place to run an agent *inside* the deployment. You choose how much the agent can do, from a read-only investigation to running commands on the target, and you can sandbox the process so a mistake stays contained. Octopus hands the agent the deployment's context, so it knows which project, environment, and release it's working on. Every invocation of Claude streams to the task log, records its token usage and cost, and stores a full transcript you can review later.
+
+## Models and API keys
+
+The step brings no model of its own, you bring your own Anthropic API key and choose the Anthropic model based on your own requirements. Octopus doesn't proxy the model or add its own key. The step runs Claude Code specifically; there's currently no option to use a different provider, like Amazon Bedrock or Azure AI Foundry.
+
+Every run records its token usage and cost against the task, so you can see what each agent run costs.
+
+## Limitations
+
+- Claude only, bring your own key. The step runs the Claude Code CLI against your own Anthropic API key. There's no support for other model providers, and Octopus doesn't supply or proxy the model.
+- It runs non-interactively. There are no mid-run approval prompts. The agent runs with the tools you allowed and nothing else; if it tries to use a tool it wasn't allowed, that denial fails the step. Plan the permissions up front, or use Auto mode.
+- A run that "gives up" can still pass. Octopus fails the step only on concrete signals: a non-zero exit, a terminal status other than success (which covers hitting the turn limit or budget cap), a denied tool call, or the explicit failure tag from the `octopus-fail-deployment` skill. It doesn't judge whether the agent actually achieved your goal. An agent that concludes it can't do the task, but exits cleanly, looks the same as success. For outcomes that matter, back the agent with a deterministic check.
+- The sandbox modes are Linux/WSL2-only. Bash sandbox and Sandbox runtime run on Linux (and WSL2) workers. They aren't available on Windows. On other platforms you're limited to **None** plus whatever isolation you provide yourself.
+- The prompt injection check and Auto mode add cost and latency. The injection check runs a model over your context before every run. Auto mode runs a second classifier model to judge each action. API Costs associated with the prompt injection check are not included as part of the cost estimate, and aren't included when determining if the agent is going to exceed the set budget limit. The tokens used, however, are reported back and displayed.
+
+We'd love to hear how you use the step, what worked, and what you need next. Feedback during the alpha directly shapes what we build, so send it through your account team or [Octopus support](https://octopus.com/support).