How to run Claude Code unattended on Kubernetes

How do I run Claude Code headless?

Run claude -p (headless mode) with the prompt, the tools it may use, and a permission mode that never waits for a person. It prints the result and exits 0 on success, non-zero on failure, so any scheduler can run it.

Cap every run. --max-turns and --max-budget-usd stop a run that loops or wanders before it becomes a surprise on the bill; the numbers in the examples are placeholders to size from your own attended runs.

The flags below come from Anthropic's headless and CLI reference docs. In -p mode with nobody attached, a permission prompt cannot be answered, so anything not allowed up front is denied. That is the behaviour you want in a batch job: unknown means no.

claude -p "Read TRIAGE.md and follow it. Write the result to out/report.md." \
  --permission-mode dontAsk \
  --allowedTools "Read,Grep,Glob,Edit" \
  --max-turns 40 \
  --max-budget-usd 5 \
  --output-format json

sourcesClaude Code docs: headless modeClaude Code docs: CLI referenceClaude Code docs: permissions

Which credentials does an unattended run use?

An API key or a long-lived token, injected as a secret, never a login in the image. ANTHROPIC_API_KEY works everywhere. A subscriber can run claude setup-token to get a one-year OAuth token for CI, exposed as CLAUDE_CODE_OAUTH_TOKEN.

Two catches from Anthropic's authentication and headless docs. Bare mode needs ANTHROPIC_API_KEY or an apiKeyHelper and does not read CLAUDE_CODE_OAUTH_TOKEN. And cloud provider credentials take precedence over both, so check which one actually authenticates the run.

sourcesClaude Code docs: authenticationClaude Code docs: headless mode

What are the options for running Claude Code unattended?

Five common shapes, as of October 2026. They differ in where the run lives, who picks the work, and whether a person can sign off mid-way.

sourcesClaude Code docs: RoutinesClaude Code docs: devcontainer

How do I run Claude Code as a Kubernetes Job?

Build a pinned image, store the key as a Secret, and run one Job per run with a locked-down pod. The manifests below are a working starting point; adjust the image, prompt and tools to your task.

1. 1

   Build the image

   Pin the Claude Code version you tested and turn off auto-update. Run as the non-root node user.

   FROM node:22-slim
   RUN apt-get update \
    && apt-get install -y --no-install-recommends git ca-certificates jq \
    && rm -rf /var/lib/apt/lists/*
   # Pin the version you tested. Never let a batch job auto-update.
   RUN npm install -g @anthropic-ai/claude-code@X.Y.Z
   ENV DISABLE_AUTOUPDATER=1
   USER node
   WORKDIR /home/node/work

2. 2

   Create the namespace and the secret

   Use a dedicated namespace for agent runs. Prefer one key per purpose so you can revoke it alone.

   kubectl create namespace agents
   kubectl -n agents create secret generic claude-api \
     --from-literal=api-key="$ANTHROPIC_API_KEY"

3. 3

   Write the Job

   No service-account token, non-root, every capability dropped, no retries, a hard deadline and automatic cleanup. An init container that clones the repo into the work volume is left out for brevity.

   apiVersion: batch/v1
   kind: Job
   metadata:
     name: claude-triage
     namespace: agents
   spec:
     backoffLimit: 0
     activeDeadlineSeconds: 3600
     ttlSecondsAfterFinished: 86400
     template:
       spec:
         restartPolicy: Never
         automountServiceAccountToken: false
         securityContext:
           runAsNonRoot: true
           runAsUser: 1000
           seccompProfile: { type: RuntimeDefault }
         containers:
           - name: claude
             image: registry.example.com/claude-runner:1.0.0
             args:
               - claude
               - -p
               - "Read TRIAGE.md and follow it. Write the result to out/report.md."
               - --permission-mode
               - dontAsk
               - --allowedTools
               - "Read,Grep,Glob,Edit"
               - --max-turns
               - "40"
               - --max-budget-usd
               - "5"
               - --output-format
               - json
             env:
               - name: ANTHROPIC_API_KEY
                 valueFrom:
                   secretKeyRef: { name: claude-api, key: api-key }
             securityContext:
               allowPrivilegeEscalation: false
               capabilities: { drop: ["ALL"] }
             volumeMounts:
               - { name: work, mountPath: /home/node/work }
         volumes:
           - name: work
             emptyDir: {}

4. 4

   Lock down the network

   Deny all ingress and allow only DNS and HTTPS out. A plain NetworkPolicy cannot filter by hostname; to allow only api.anthropic.com and your git host, use an egress proxy or a CNI with FQDN policies.

   apiVersion: networking.k8s.io/v1
   kind: NetworkPolicy
   metadata:
     name: claude-runs
     namespace: agents
   spec:
     podSelector: {}
     policyTypes: [Ingress, Egress]
     ingress: []
     egress:
       - ports:
           - { protocol: UDP, port: 53 }
           - { protocol: TCP, port: 53 }
       - ports:
           - { protocol: TCP, port: 443 }

5. 5

   Schedule it

   Wrap the same spec in a CronJob. concurrencyPolicy Forbid stops a slow run from overlapping the next one.

   apiVersion: batch/v1
   kind: CronJob
   metadata:
     name: claude-nightly
     namespace: agents
   spec:
     schedule: "0 3 * * *"
     concurrencyPolicy: Forbid
     jobTemplate:
       spec:
         # same spec as the Job above

6. 6

   Read the result

   With --output-format json the pod log ends with one JSON object: the result, the session id and the cost. Ship logs to your log stack before the TTL removes the pod.

   kubectl -n agents logs job/claude-triage | tail -n 1 | jq '.result, .total_cost_usd'

sourcesClaude Code docs: setupClaude Code docs: network accessKubernetes docs: JobsKubernetes docs: network policies

How do I keep an unattended Claude Code run safe?

Treat the pod as untrusted: it runs code an AI chose. Anthropic's devcontainer docs warn that a container is not full protection, that credentials in ~/.claude can be exfiltrated, and that --dangerously-skip-permissions is rejected when the CLI runs as root.

1. Allow tools explicitly. Prefer dontAsk with a short allow list over bypassPermissions, which Anthropic says to use only in isolated containers or VMs.
2. No service-account token: automountServiceAccountToken: false.
3. Non-root, all capabilities dropped, no privilege escalation, Pod Security restricted on the namespace.
4. A per-run or per-purpose secret, never your personal login.
5. Egress only to the model API, your git host and package registries the task needs.
6. A deadline on every run, and no automatic retries of a half-done change.
7. Push to a branch for review, not straight to main.

sourcesClaude Code docs: devcontainerClaude Code docs: permissions

What does a plain Kubernetes Job not give you?

The pod is the easy part. A Job runs one prompt; it does not know which task is next (a work pool answers that), what process the task follows, where a person must decide, or how to pick up where a failed run stopped.

How does ConvOps run Claude Code on Kubernetes?

Every isolated ConvOps run is its own Kubernetes Job: a fresh pod with the task volume, a secret made for this run and masked in logs, and the MCP servers the environment names as native sidecars. The pod has no service-account token, runs non-root with capabilities dropped under Pod Security restricted, and sits behind a NetworkPolicy with no ingress and limited egress.

The run follows the task's workflow one step at a time. A gate that needs a person holds the work until a person approves. Each executor has a time limit (4 hours by default) and the work resumes on the same volume. You can Stop any run. The work is pushed as a fast-forward or to a task branch, and a failed run keeps its commits on a rescue branch. When the pod is gone, the run record stays: tokens, model split, cost, turns, duration and the error class. Claude Code and OpenCode are supported today. Enterprise customers self-host the whole system on their own cluster with one Helm chart.

1. 1

   Self-host on your cluster (Enterprise)

   One chart, one values file for the run namespace, posture, network policy, time limit and model credentials.

   helm install convops convops/convops -n convops -f values.yaml

2. 2

   Or bridge your own Job to ConvOps

   Keep the Job above and let it take work from a ConvOps pool. Give it an API key through a variable whose name is not a credential name; Claude Code expands those in .mcp.json, and reads credential-named ones as empty.

   {
     "mcpServers": {
       "convops": {
         "type": "http",
         "url": "https://mcp.convops.app/",
         "headers": { "Authorization": "Bearer ${CONVOPS_TOKEN}" }
       }
     }
   }

3. 3

   Prompt the run to follow the workflow

   The agent claims the next task, works the current step and advances. When a step needs judgment it marks the task blocked and stops, and a person picks it up.

   claude -p "Call pools_next for the pool nightly-fixes. Work the task by
   following its workflow: read the current step, do it, call workflow_advance.
   If a step needs human judgment, set the task to blocked with the reason and stop." \
     --mcp-config .mcp.json \
     --permission-mode dontAsk \
     --allowedTools "Read,Grep,Glob,Edit,Bash(npm test *),mcp__convops"

sourcesClaude Code docs: MCP

When should Claude Code run unattended at all?

When the process has been run attended enough times that you trust it, and the steps that still need a person are gates rather than habits. Start with approvals on every step. As trust grows, let the work run on its own.

Frequently asked questions