Documentation on simian-agent

Getting started

Mon, 01 Jan 0001 00:00:00 +0000

This walks from a fresh clone through your first directed-chaos fault, then through your first autonomous-mode plan. Assumes you have a Kubernetes cluster with Chaos Mesh installed and your kubeconfig points at it (cluster-admin or equivalent).

Build

make all

Produces bin/simian. The binary holds every subcommand (arena, sut, serve, chaos, plan).

Provision an arena and deploy a SUT

An arena is a namespace annotated simian.chaos/eligible="true" plus the RBAC needed for the controller’s chaos service account. A SUT is a System Under Test deployed into that arena (Online Boutique is the built-in default).

Design

Mon, 01 Jan 0001 00:00:00 +0000

Status: Draft, v1 scope. Related: requirements.md, roadmap.md. Supersedes the design portion of simian-agent.md. Requirement IDs (R-FOO-NN) reference requirements.md.

1. Architectural Overview

Simian is a single Go binary that ships as two Kubernetes workloads sharing one image. All fault sources — autonomous-mode plans and directed-mode MCP calls alike — funnel through one Fault Executor before any chaos resource is applied.

 +---------------------------+
 | LLM Provider |
 | (pluggable; Gemini v1) |
 +-------------+-------------+
 ^
 structured output | read-only context
 |
 +------------------------+ +-------------+-------------+ +-------------------------+
 | Topology Discoverer |--->| Plan Generator | | MCP Server (directed) |
 | (read-only K8s + mesh)| | (autonomous mode loop) | | - submit_fault |
 +------------------------+ +-------------+-------------+ | - clear_fault |
 | | - list_fault_catalog |
 | AttackPlan | - list_active_faults |
 v +-----------+-------------+
 +-------+--------+ |
 | | | FaultManifest
 | v v
 | +-----------------------------------+
 | | FAULT EXECUTOR |
 | | (1) schema validate |
 | | (2) safety validate |
 | | (3) audit pre-apply |
 | | (4) apply via driver |
 | | (5) lease + lifecycle |
 | | (6) audit post-apply |
 | +----------------+------------------+
 | |
 | +-------------+-------------+
 | v v
 | +---------------+ +---------------+
 | | Chaos Mesh | | Litmus driver |
 | | driver | | (workflows + |
 | | (dynamic CRD) | | probes) |
 | +-------+-------+ +-------+-------+
 | | |
 v v v
 +---------------------------------------------------------+
 | Eligible Target Namespaces |
 | (annotated; chaos SA RBAC-bound; SUT may be Simian- |
 | provisioned per provisioned posture) |
 +---------------------------------------------------------+
 |
 | observable effects, probe results
 v
 +---------------+---------------+
 | Scenario Exporter |
 | + Red Phone (incident pages) |
 +---------------+---------------+
 |
 v
 +---------------------------------------------+
 | External SRE agent / evaluation harness |
 +---------------------------------------------+

1.1 Component inventory

Component	Responsibility	Mode(s)
LLM Provider	Stateless completion API behind a pluggable interface; Gemini default	Both
Topology Discoverer	Read-only inspection of eligible namespaces	Autonomous
Plan Generator	LLM-driven `AttackPlan` synthesis; orchestrates the autonomous cycle	Autonomous
MCP Server	Directed-mode tool surface and read-only context tools used by the LLM	Both (caller-facing)
Fault Executor	Single chokepoint: validate → audit → apply → lease → audit. No bypass.	Both
Chaos Mesh driver	Dynamic-CRD apply for the full `chaos-mesh.org/v1alpha1` catalog	Both
Litmus driver	`ChaosEngine` / workflow apply; probe attachment; ChaosHub-sourced experiments	Both
Provisioner	Cluster-scoped: creates eligible namespaces, deploys SUT, manages chaos SA RoleBindings	Provisioned posture
Red Phone	Best-effort outbound natural-language incident pages	Both, optional
Scenario Exporter	Stable structured records of inputs/outputs per cycle, for external evaluation	Both
Lease Reaper	Background sweeper that clears any fault whose lease is stale or duration is exceeded	Both

2. Operating Modes

2.1 Directed mode

External caller (human, agent, CI)
 |
 | MCP: submit_fault(intent, targets, options)
 v
 MCP Server ──→ LLM.TranslateIntent(intent, catalog) ──→ FaultManifest
 | |
 | <───── FaultManifest ─────────┘
 v
 Fault Executor (validate → audit → apply → lease)
 |
 v
 returns {planID, faultUIDs[], status}

The caller can poll/stream status via get_fault_status(planID) or watch the Red Phone webhook for any pages emitted during the fault window. Directed mode is the integration path for upstream agents (Claude Code, ADK agents, internal tooling) and CI jobs.

Requirements

Mon, 01 Jan 0001 00:00:00 +0000

Status: Draft, v1 scope. Related: design.md, roadmap.md. Supersedes the requirements portion of simian-agent.md.

1. Objective & Scope

1.1 What Simian Agent is

Simian Agent is an open-source, AI-native chaos engineering orchestrator — a “Chaos Monkey for AI.” It exists to inject controlled, structurally meaningful failures into Kubernetes workloads so that downstream automated SRE agents can be exercised, evaluated, and improved.

It is not a generic chaos framework. Its differentiator is the dual operating model: it can be driven directly by an upstream caller through a standardized tool interface, and it can also operate fully autonomously — discovering topology, drafting an attack plan, and executing it under bounded safety constraints.

Roadmap

Mon, 01 Jan 0001 00:00:00 +0000

Status: Draft, v1 plan. M1 shipped 2026-05-12 (PR #1). M2 shipped 2026-05-12/14 (PRs #2, #5). M3 shipped 2026-05-14 (PRs #7, #8). Related: requirements.md, design.md. Supersedes the roadmap portion of simian-agent.md.

This roadmap lays out v1 in six milestones. Each milestone has a focused deliverable, a small set of public Go entrypoints, and a concrete acceptance demo. Milestones are sequenced as a vertical slice first (Milestone 1) then breadth and depth — every milestone produces a demoable system on top of the previous one. Cross-cutting work (observability, Helm chart) is interleaved — see the closing section.

DPv2-compatible chaos engines

Mon, 01 Jan 0001 00:00:00 +0000

Context

GKE Dataplane V2 (eBPF/Cilium) bypasses Chaos Mesh’s NetworkChaos because chaos-daemon installs tc/netem qdiscs that the eBPF datapath never traverses (refs: chaos-mesh#3302, cilium#19975 — both open since 2022, no fix in sight). All netem-family actions plus partition are silently no-ops on DPv2 nodes. This means our M3 acceptance bullet “autonomous loop generates and applies a NetworkChaos delay” can succeed at the API level but produce zero real network impact — the LLM and the audit log say “applied”, but the SUT’s metrics never twitch.

Deploying with Helm

Mon, 01 Jan 0001 00:00:00 +0000

The Helm chart in deploy/helm/simian/ runs the controller in-cluster. It pulls the image from ghcr.io/go-steer/simian-agent, published automatically by .github/workflows/release.yml on each v* tag push.

Install patterns

# Default install (uses Chart.AppVersion as the image tag).
helm upgrade --install simian deploy/helm/simian -n simian-system --create-namespace

# Pin a specific published tag.
helm upgrade --install simian deploy/helm/simian -n simian-system \
 --set image.tag=v0.1.3-dev

# Enable the M3 in-controller SUT path (required for `simian sut deploy --use-controller`).
helm upgrade --install simian deploy/helm/simian -n simian-system \
 --set sutInController.enabled=true

# Recommended starting point: layer the "fully-baked-defaults" overlay
# on top of the chart defaults. Pins a known-verified image tag, tightens
# the executor safety policy, leaves experimental features off. See
# examples/values-baked-defaults.yaml for what each value is doing and
# the maintenance contract.
helm upgrade --install simian deploy/helm/simian -n simian-system \
 --create-namespace \
 -f examples/values-baked-defaults.yaml

Ad-hoc dev images

For dev builds without cutting a release tag, push your own image:

Using the chaos engines

Mon, 01 Jan 0001 00:00:00 +0000

Simian ships three chaos engines. Each is a simian.ChaosDriver registered with the executor; the LLM sees all of them via the catalog mechanism and can pick whichever fits the plan.

Engine	What it does	When to use it
`chaos-mesh`	The full Chaos Mesh CRD catalog: PodChaos, StressChaos, IOChaos, TimeChaos, NetworkChaos, etc.	Default for non-network chaos. NetworkChaos is silently bypassed on GKE Dataplane V2 — see Known limitations.
`network-policy`	Standard `networking.k8s.io/v1` NetworkPolicy partitions (deny ingress / egress / both).	Network partition chaos on GKE DPv2 (or any cluster where NetworkChaos isn’t reliable). Partition only — no delay / loss / jitter.
`envoy-fault`	HTTP-layer delay + abort via an injected Envoy sidecar. Two kinds: `EnvoyHttpDelay`, `EnvoyHttpAbort`.	HTTP/gRPC delay or error injection on DPv2. Requires the SUT to be deployed with `--no-envoy-faults=false` (off by default — see Known limitations).

Directed-control patterns

All three engines accept the same simian chaos --engine ... --kind ... --spec '<inline JSON>' shape:

CLI reference

Mon, 01 Jan 0001 00:00:00 +0000

simian is a single binary with cobra subcommands. This page is generated from simian <cmd> --help output.

To get the most up-to-date reference for any single command, run it with --help:

simian --help
simian serve --help
simian chaos --help
simian sut deploy --help

Subcommand index

Subcommand	Purpose
`simian arena`	Manage chaos arena namespaces (create/destroy/describe). The arena is the namespace+RBAC unit of isolation for chaos.
`simian sut`	Manage Systems Under Test (deploy/destroy/list). Built-in SUT: Online Boutique.
`simian serve`	Run the controller: Fault Executor + MCP server + autonomous loop.
`simian chaos`	Submit a fault either as plain-text intent (LLM-translated) or as a hand-built FaultManifest (deterministic-control). Also list/clear active faults.
`simian plan`	Generate an `AttackPlan` against a real arena and emit it as JSON. Default `--dry-run=true` does not apply.
`simian evaluate`	Stub until M5 (scenario data export).

Common flag patterns

Eligibility

--eligible-namespace <ns> (repeatable, simian serve) overrides the default annotation-based lookup. Without it, the controller treats any namespace with simian.chaos/eligible="true" as eligible.

Helm values reference

Mon, 01 Jan 0001 00:00:00 +0000

The chart is at deploy/helm/simian/. Reference for every value lives in the chart’s values.yaml — that file has long inline comments explaining each setting and is the canonical source. This page summarizes by category.

For installs that want a known-good starting point rather than the chart defaults, layer the recommended overlay on top.

Image

Value	Default	Notes
`image.repository`	`ghcr.io/go-steer/simian-agent`	Published by the release workflow on every `v*` tag.
`image.tag`	`""` (falls back to `Chart.AppVersion`)	Pin explicitly for production so chart upgrades don’t silently change the running binary.
`image.pullPolicy`	`IfNotPresent`

Eligibility

Value	Default	Notes
`eligibleNamespaces`	`[]`	Static allowlist. When empty, the controller falls back to annotation-based lookup (`simian.chaos/eligible="true"`), which is the preferred mode for installations using `simian arena create`.

Provisioner subsystem (M2 Part A)

Value	Default	Notes
`provisioner.enabled`	`true`	Ships the `simian-provisioner` SA + ClusterRole + ValidatingAdmissionPolicy backstop. Disable for installs where arenas are managed by an operator using their kubeconfig (no in-cluster provisioner).

LLM provider

Value	Default	Notes
`llm.provider`	`gemini`	`gemini` or `stub`.
`llm.model`	`""` (default `gemini-2.5-pro`)
`llm.vertex.enabled`	`true`	Vertex via Workload Identity (production-recommended).
`llm.vertex.project`	`gke-demos-345619`	Replace for your install.
`llm.vertex.location`	`us-central1`
`llm.apiKey.enabled`	`false`	Alternative to Vertex; mounts a Kubernetes Secret.
`llm.apiKey.secretRef` / `secretKey`	`simian-llm` / `geminiApiKey`

Executor safety policy

Value	Default	Notes
`executor.durationCeiling`	`15m`	Hard cap per fault. Recommended overlay: `5m`.
`executor.permittedTiers`	`[namespace, node]`	Blast-radius tiers permitted. Recommended overlay: `[namespace]` (opt-in to node tier per install).
`executor.maxConcurrentFaults`	`0` (no cap)	Total leased faults across namespaces. Recommended overlay: `1`.
`executor.minCooldown`	`0s`	Per-namespace cooldown. Recommended overlay: `60s`.
`executor.recentFaultsCapacity`	`100`	Bounded ring backing the `get_recent_faults` MCP tool.

Topology + SUT

Value	Default	Notes
`topology.resync`	`30s`	Informer resync interval. Recommended overlay: `60s` for prod (lower API server load).
`sutInController.enabled`	`false`	Required for `simian sut deploy --use-controller` (the in-controller SUT path). Recommended overlay: `true`.
`sutInjection.envoyFaults`	`false`	Whether to inject the Envoy fault sidecar into SUT Deployments. Off by default because the iptables interception breaks gRPC kubelet probes — see Known limitations. Only enable for SUTs whose probes are HTTP-only or TCP-only.

Autonomous mode

Value	Default	Notes
`autonomous.enabled`	`false`	When true, the controller runs the autonomous planning loop.
`autonomous.namespaces`	`[]`	Required when `enabled: true`. Arena namespaces the loop targets.
`autonomous.cycleInterval`	`5m`	Recommended overlay: `10m` (slower; more time to observe).
`autonomous.maxFaultsPerCycle`	`3`	Recommended overlay: `1` (one fault per cycle to start).
`autonomous.maxSeverityPerCycle`	`namespace`	Highest blast tier the loop will apply.
`autonomous.hypothesisHint`	`""`	Optional soft preference passed to the LLM. Use this to bias toward newer engines (network-policy, envoy-fault).

MCP server

Value	Default	Notes
`mcp.port`	`8081`
`mcp.serviceType`	`ClusterIP`

Resources + security

Value	Default	Notes
`resources.requests.cpu` / `.memory`	`100m` / `128Mi`	Recommended overlay: `200m` / `256Mi`.
`resources.limits.cpu` / `.memory`	`500m` / `512Mi`	Recommended overlay: `1000m` / `1Gi` (prevents OOM during LLM bursts).
`podSecurityContext`	restricted-PSS-compatible	`runAsNonRoot: true`, `runAsUser: 65532`, `seccompProfile.type: RuntimeDefault`.

Known limitations

Mon, 01 Jan 0001 00:00:00 +0000

This page is the canonical place to land if a fault “applied successfully” but didn’t appear to do anything, or if a SUT pod refuses to come up after enabling Envoy injection.

GKE Dataplane V2 silently breaks Chaos Mesh’s NetworkChaos

Chaos Mesh installs a netem qdisc on the pod’s eth0, which we verified is present at the kernel level. But Dataplane V2 routes pod-to-pod traffic through eBPF maps that bypass the tc qdisc layer, so the latency / loss never gets applied. The Sent ... pkt counter on the qdisc stays flat. This is a Chaos Mesh + Cilium incompatibility, not a Simian bug.

Contributing

Mon, 01 Jan 0001 00:00:00 +0000

The canonical contributor guide lives at CONTRIBUTING.md in the repo root. It covers:

Reporting bugs and requesting features.
The PR workflow: branch from main, conventional-commits messages, DCO sign-off.
License headers (Apache 2.0; auto-checked by dev/tools/lint-go).
Test discipline — unit tests live next to the code (*_test.go); integration tests are gated by build tags; end-to-end acceptance plans live at the repo root as acceptance-mN.md.
The maintenance contract for examples/values-baked-defaults.yaml — every PR that adds a chart value, hardens an experimental feature, or surfaces a footgun MUST update that overlay in the same PR.

Project layout (high-level)

Directory	Purpose
`cmd/simian/`	CLI binary. Cobra subcommands: `arena`, `sut`, `serve`, `chaos`, `plan`, `evaluate`.
`pkg/`	Library packages: `arena/`, `audit/`, `catalog/`, `driver/{chaosmesh,networkpolicy,envoyfault}`, `executor/`, `lease/`, `llm/`, `loop/`, `mcp/`, `planner/`, `simian/`, `sut/`, `topology/`.
`api/v1alpha1/`	Typed CRDs / shared API structs.
`internal/testutil/`	Fakes and fixtures shared across test packages.
`deploy/`	Kubernetes manifests + Helm chart (`deploy/helm/simian/`).
`examples/`	Manifest fragments + the recommended Helm values overlay.
`dev/`	Local + CI tooling (run from here, don’t reinvent).
`docs/`	This site’s source (`docs/site/`) plus design / planning markdown.
`.github/workflows/`	Thin delegators to `dev/ci/presubmits/`.

Getting set up

git clone https://github.com/go-steer/simian-agent
cd simian-agent
make all # build + unit tests + lint
dev/tools/ci # full presubmit (format / vet / build / lint / mod-tidy / unit / vuln)

For the docs site itself: