Getting Started With The Claude Agent Step

The Claude Agent Step runs Claude Code 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, 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 keeps it out of the task log.
The Claude Code 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 on the PATH. The step checks the version and fails if it’s missing or too old.

To add and configure the step:

Open your deployment process or runbook and select Add step.
Search for claude and choose Run Claude Agent from the step library.
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.
In Claude Settings, set API Key to a reference to your sensitive variable, for example #{anthropic-api-key}.
Optionally, set Model Version to a model, like 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.
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.

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.
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 (which uses a classifier model to determine whether to run a tool), is covered in Security & Compliance.
In Tool Permissions, list the tools the agent needs, one per line. For example:
```
Read
Glob
Bash(pwd)
Bash(ls *)
```
Start with minimal permissions and add to them as you learn what the agent needs.
Optionally, under Agent Capabilities, add Skills, connect the Octopus MCP Server, or add Additional MCP Servers. See Extending the Claude Agent Step.
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.
Optionally, set a Maximum Budget as a spend cap in USD. Leave it blank for no limit.
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.
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:

Create a release and deploy it, as you would for any other step.
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.
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).

The task log showing the Claude agent streaming its output

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.
Transcript	Stored on the Octopus Server, gated behind a dedicated permission	The full, verbose session, recorded for auditing. See Security & Compliance for who can read it and how.

The Claude Usage Summary panel on the task page

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 use it to attach 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:

Add a Run Claude Agent step to your deployment process (see Add a Run Claude Agent step).
Set the step’s run condition to Only if the previous step failed.

Set the Prompt to:

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.

Set Permission Mode to dontAsk mode.
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 *).
Select Sandbox runtime as the sandbox mode on a Linux worker (or None while evaluating on Windows or macOS).

Keep the allowlist to read-only tools. The prompt tells the agent not to change anything, but the allowlist helps to enforce 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 failed step.

Smoke-test a service before promotion

Before promoting a release, you want an agent to check that the deployed service is healthy and 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 signal failure explicitly; 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:

Add a Run Claude Agent step after the steps that deploy the service.

Set the Prompt to:

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.

Set Permission Mode to dontAsk mode.
In Tool Permissions, allow Bash(curl *), plus any other command your check needs.
Select Sandbox runtime as the sandbox mode on a Linux worker.

If the health check doesn’t pass, the agent emits the octopus-fail-deployment failure tag 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 for how the skill works.

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 for more information.

Help us continuously improve

Please let us know if you have any feedback about this page.

Send feedback

Page updated on Thursday, July 9, 2026

Edit on GitHub