GitHub - axon-core/axon: Run autonomous AI agents safely — at scale, in CI, on Kubernetes.

Axon

Run autonomous AI agents safely — at scale, in CI, on Kubernetes.

Axon is a Kubernetes controller that runs AI coding agents (like Claude Code) in isolated, ephemeral Pods with full autonomy. You get the speed of --dangerously-skip-permissions without the risk — and the ability to fan out hundreds of agents in parallel across repos and CI pipelines.

Demo

# 1. Initialize your config
$ axon init
# Edit ~/.axon/config.yaml with your token and workspace

# 2. Run a task against your repo
$ axon run -p "Fix the bug described in issue #42 and open a PR with the fix"
task/fix-issue-42-xyz created

# 3. Stream the logs
$ axon logs fix-issue-42-xyz -f
[init] model=claude-sonnet-4-20250514

--- Turn 1 ---
Let me investigate issue #42...
[tool] Bash: gh issue view 42

--- Turn 2 ---
I see the problem. The auth middleware does not handle expired tokens.
[tool] Edit

...

--- Turn 8 ---
PR created: https://github.com/your-org/repo/pull/123

[result] completed (8 turns, $0.12)

See Examples for a full autonomous self-development pipeline.

Why Axon?

AI coding agents are most powerful when they run fully autonomous — no permission prompts, no human in the loop. But on your laptop, that means the agent can touch your filesystem, network, and everything else on the host. And there's no easy way to fan out dozens of agents across repos or plug them into CI.

Kubernetes solves both problems at once. Inside a Pod, "dangerously skip permissions" isn't dangerous anymore — the agent gets full autonomy within an isolated, ephemeral container while the blast radius stays at zero for the host.

• Safe autonomy — agents run with --dangerously-skip-permissions inside isolated, ephemeral Pods. Full speed, zero risk to the host.
• Scale out — launch hundreds of agents in parallel across repositories. Kubernetes handles scheduling and resource management.
• CI-native — trigger agents from any pipeline. A Task is just a Kubernetes resource — create it with kubectl, Helm, Argo, or your own tooling.
• Observable — watch agents move through Pending → Running → Succeeded/Failed with kubectl.
• Simple — a handful of CRDs, one controller, zero dependencies beyond a running cluster.

How It Works

 Task: refactor auth ──┐                ┌──▶ Isolated Pod ──▶ Succeeded
                       ├──▶  Axon  ─────┼──▶ Isolated Pod ──▶ Succeeded
 Task: add tests ──────┤                └──▶ Isolated Pod ──▶ Failed
                       │
 Task: update docs ────┘

You apply a Task, Axon runs it as an isolated Job with --dangerously-skip-permissions, and tracks it through Pending → Running → Succeeded/Failed. Currently supported agents: Claude Code.

                    polls         new issues
 TaskSpawner ─────────────▶ GitHub Issues
      │        ◀─────────────
      │
      ├──creates──▶ Task: fix-bugs-1
      └──creates──▶ Task: fix-bugs-2

Quick Start

Prerequisites

• Kubernetes cluster (1.28+)
• kubectl configured

1. Install the CLI

go install github.com/axon-core/axon/cmd/axon@latest

2. Install Axon

3. Run Your First Task

axon init
# Edit ~/.axon/config.yaml with your token:
#   oauthToken: <your-oauth-token>

axon run -p "Create a hello world program in Python"
axon logs <task-name> -f

apiVersion: axon.io/v1alpha1
kind: Workspace
metadata:
  name: my-workspace
spec:
  repo: https://github.com/your-org/your-repo.git
  ref: main

apiVersion: axon.io/v1alpha1
kind: Task
metadata:
  name: hello-world
spec:
  type: claude-code
  prompt: "Create a hello world program in Python"
  credentials:
    type: oauth
    secretRef:
      name: claude-oauth
  workspaceRef:
    name: my-workspace

kubectl apply -f workspace.yaml
kubectl apply -f task.yaml
kubectl get tasks -w

Examples

Run against a git repo

Add workspace to your config:

# ~/.axon/config.yaml
oauthToken: <your-oauth-token>
workspace:
  repo: https://github.com/your-org/repo.git
  ref: main

axon run -p "Add unit tests"

Axon auto-creates the Workspace resource from your config.

Or reference an existing Workspace resource with --workspace:

axon run -p "Add unit tests" --workspace my-workspace

Create PRs automatically

Add a token to your workspace config:

workspace:
  repo: https://github.com/your-org/repo.git
  ref: main
  token: <your-github-token>

axon run -p "Fix the bug described in issue #42 and open a PR with the fix"

The gh CLI and GITHUB_TOKEN are available inside the agent container, so the agent can push branches and create PRs autonomously.

Auto-fix GitHub issues with TaskSpawner

Create a TaskSpawner to automatically turn GitHub issues into agent tasks:

apiVersion: axon.io/v1alpha1
kind: TaskSpawner
metadata:
  name: fix-bugs
spec:
  when:
    githubIssues:
      labels: [bug]
      state: open
  taskTemplate:
    type: claude-code
    workspaceRef:
      name: my-workspace
    credentials:
      type: oauth
      secretRef:
        name: claude-credentials
    promptTemplate: "Fix: {{.Title}}\n{{.Body}}"
  pollInterval: 5m

kubectl apply -f taskspawner.yaml

TaskSpawner polls for new issues matching your filters and creates a Task for each one.

Autonomous self-development pipeline

This is a real-world TaskSpawner that picks up every open issue, investigates it, opens (or updates) a PR, self-reviews, and ensures CI passes — fully autonomously. When the agent can't make progress, it labels the issue axon/needs-input and stops. Remove the label to re-queue it.

 ┌──────────────────────────────────────────────────────────────────┐
 │                        Feedback Loop                             │
 │                                                                  │
 │  ┌─────────────┐  polls  ┌────────────────┐                     │
 │  │ TaskSpawner │───────▶ │ GitHub Issues  │                     │
 │  └──────┬──────┘         │ (open, no      │                     │
 │         │                │  needs-input)  │                     │
 │         │ creates        └────────────────┘                     │
 │         ▼                                                       │
 │  ┌─────────────┐  runs   ┌─────────────┐  opens PR   ┌───────┐ │
 │  │    Task     │───────▶ │    Agent    │────────────▶│ Human │ │
 │  └─────────────┘  in Pod │   (Claude)  │  or labels  │Review │ │
 │                          └─────────────┘  needs-input└───┬───┘ │
 │                                                          │     │
 │                                           removes label ─┘     │
 │                                           (re-queues issue)    │
 └────────────────────────────────────────────────────────────────┘

See self-development/axon-workers.yaml for the full manifest.

The key pattern here is excludeLabels: [axon/needs-input] — this creates a feedback loop where the agent works autonomously until it needs human input, then pauses. Removing the label re-queues the issue on the next poll.

Features

Use Cases

• Hands-free CI — let an autonomous agent generate, refactor, or fix code as a pipeline step, with no permission prompts blocking the run.
• Batch refactoring at scale — spin up dozens of agents in parallel to apply the same prompt across microservices, each safely isolated in its own Pod.
• Scheduled maintenance — pair with a CronJob or workflow engine to run recurring code-health agents on a schedule.
• Developer self-service — expose agent execution through an internal portal so any developer can run a fully autonomous AI agent without local setup.
• AI in your internal platform — embed Axon as the execution layer for AI-powered features in your developer platform.

Reference

# ~/.axon/config.yaml
oauthToken: <your-oauth-token>
# or: apiKey: <your-api-key>
model: claude-sonnet-4-5-20250929
namespace: my-namespace

workspace:
  name: my-workspace

workspace:
  repo: https://github.com/your-org/repo.git
  ref: main
  token: <your-github-token>  # optional, for private repos and gh CLI

# Install axon into a cluster
axon install

# Initialize a config file
axon init

# Run a task
axon run -p "Refactor auth to use JWT"

# Run against a git repo (requires a Workspace resource)
axon run -p "Add unit tests" --workspace my-workspace

# Override config file defaults with CLI flags
axon run -p "Fix bug" --secret other-secret --credential-type api-key

# List tasks
axon get tasks

# List task spawners
axon get taskspawners

# View logs (follow mode)
axon logs my-task -f

# Delete a task
axon delete my-task

# Uninstall axon from the cluster
axon uninstall

Uninstall

Development

Build, test, and iterate with make:

make update             # generate code, CRDs, fmt, tidy
make verify             # generate + vet + tidy-diff check
make test               # unit tests
make test-integration   # integration tests (envtest)
make test-e2e           # e2e tests (requires cluster)
make build              # build binary
make image              # build docker image

Roadmap

• Task dependencies — chain tasks so one waits for another to finish before starting, enabling agent pipelines in pure Kubernetes.

 Task: scaffold service ──▶ Task: write tests ──▶ Task: generate docs

Contributing

1. Fork the repo and create a feature branch.
2. Make your changes and run make verify to ensure everything passes.
3. Open a pull request with a clear description of the change.

For significant changes, please open an issue first to discuss the approach.

License

Business Source License 1.1