AgentJob Reference - Nominos Documentation

Overview

An AgentJob (apiVersion: nominos.io/v1) describes one task for a coding agent: what to do, which repository to do it in, and how the agent should run. The nominos-core controller reconciles each AgentJob into a Kubernetes Job that clones the repo, runs the agent, pushes a branch, and (optionally) opens a pull request.

kubectl

kubectl get agentjobs
NAME                  PHASE       AGE   BRANCH                        COMMITS
update-dependencies   Completed   12m   nominos/update-dependencies   2

Spec Fields

Field	Type	Default	Description
`task`	TaskSpec	—	What the agent should do. Required.
`agent`	AgentSpec	—	Agent image, model, harness, and execution configuration.
`repository`	RepositorySpec	—	Git repository the agent works on.
`paused`	boolean	false	When true, the job stays in the Draft phase and is not scheduled.
`priority`	integer	0	Scheduling order — higher priority runs first.
`timeoutSeconds`	integer	3600	Maximum time the agent can run, in seconds.
`backoffLimit`	integer	3	Number of retries before the job is marked Failed.
`resources`	ResourceRequirements	—	Standard Kubernetes resource requests/limits for the agent pod.
`maxCostDollars`	string	—	Maximum spend in dollars for this job.
`interactionMode`	InteractionModeSpec	—	Checkpoint-based workflow configuration.

spec.task

Field	Type	Default	Description
`description`	string	—	Human-readable description of the task. Required.
`details`	string	—	Extended elaboration on the task.
`acceptanceCriteria`	string[]	—	Criteria for task completion.
`focusFiles`	string[]	—	Files the agent should focus on.
`context`	string	—	Additional context or instructions.

spec.agent

Field	Type	Default	Description
`image`	string	ghcr.io/johnhenry/nominos-agent:latest	Agent container image.
`model`	string	claude-sonnet-5	Model to use (e.g. claude-sonnet-5, claude-opus-5).
`harness`	enum: claude-code \| pi	claude-code	Coding-agent harness that executes the task. pi enables multi-model execution across providers.
`maxTurns`	integer	50	Maximum conversation turns.
`credentialsSecret`	string	nominos-credentials	Secret containing API credentials.
`zeroShot`	ZeroShotConfig	—	Multi-agent execution with blind validation. Sub-fields: isolation (none \| worktree \| docker, default none) and provider (claude \| openai \| gemini, default claude).
`interactive`	boolean	false	Chat mode — the agent completes the task, then stays alive for follow-up messages.
`imagePullSecrets`	string[]	—	Secret names for pulling private container images (e.g. from ghcr.io).

New: the harness field

Set spec.agent.harness: pi to execute the task with the pi coding agent instead of Claude Code. The pi harness is provider-agnostic, so you can pair it with non-Anthropic models via your own API keys. The default remains claude-code.

spec.repository

Field	Type	Default	Description
`url`	string	—	Repository URL (SSH or HTTPS). Required.
`baseBranch`	string	main	Branch to base work on.
`workBranch`	string	auto-generated	Branch name for the agent’s work.
`authSecret`	string	—	Secret containing an SSH key or token for git access.
`mergeBranch`	string	—	Branch to merge into baseBranch, producing real conflict markers for conflict-resolution jobs.
`createPR`	boolean	true	Create a pull request after pushing changes.
`autoMerge`	boolean	false	Enable auto-merge on the PR (requires branch protection rules).
`prLabels`	string[]	—	Labels to add to the PR.
`createDraftPR`	boolean	false	Create the PR as a draft.
`updateClaudeMd`	boolean	false	Instruct the agent to update CLAUDE.md with learnings.
`mergeStrategy`	enum: squash \| merge \| rebase	squash	How the PR should be merged.

spec.interactionMode

Field	Type	Default	Description
`mode`	enum: fire_and_forget \| checkpoints \| interactive \| batch_review	fire_and_forget	How the agent interacts with users during execution.
`modeConfigId`	string	—	Reference to a pre-configured mode config.
`checkpointTriggers`	enum[]	—	When checkpoints are created: before_commit, before_pr, on_error, on_ambiguity, on_scope_change, on_cost_threshold, on_time_threshold.

Status

Phases

Phase	Meaning
`Draft`	Job is paused (spec.paused: true), not scheduled.
`Pending`	Waiting to be scheduled.
`Queued`	Queued, waiting for resources.
`Running`	Agent is actively running.
`Paused`	Paused mid-execution.
`Merging`	Agent work done, PR created and waiting in a merge queue.
`Completed`	Completed successfully.
`Failed`	Failed after exhausting retries.
`Cancelled`	Cancelled by the user.

Status Fields

Field	Description
`phase`	Current phase (see table above).
`message`	Human-readable status message.
`harness`	Harness that actually executed the task, as reported by the runner.
`warnings`	Non-fatal issues (e.g. missing credentials, PR creation failed).
`startTime / completionTime`	When the job started and finished.
`retries`	Retry count so far.
`jobRef`	Reference to the underlying Kubernetes Job.
`workBranch / commits / commitSHA / filesChanged`	Git results: branch created, commit count, final SHA, changed files.
`pullRequestURL`	URL of the PR, if one was created.
`estimatedCostDollars / tokenUsage`	Estimated spend and input/output token counts.
`checkpoint`	Resume state after pod failure (last turn, restart count, ConfigMap ref).
`zeroShot`	Multi-agent execution state: phase, complexity, validators run/passed, iterations.
`chat`	Interactive-mode state: ready flag, message count, last message time.
`cr`	Continuation Record status: progress counts, key decisions, blockers, resume points.
`logs`	Agent logs, preserved after pod deletion.
`conditions`	Standard Kubernetes conditions.

Examples

Minimal job: fix a bug and open a PR

agentjob.yaml

apiVersion: nominos.io/v1
kind: AgentJob
metadata:
  name: fix-auth-bug
spec:
  task:
    description: "Fix the authentication bypass vulnerability in auth.go"
  repository:
    url: "https://github.com/org/repo"
    baseBranch: "main"
    createPR: true
    prLabels: ["security", "priority-high"]
  agent:
    model: "claude-sonnet-5"
    maxTurns: 50

Checkpointed job on the pi harness

agentjob-checkpoints.yaml

apiVersion: nominos.io/v1
kind: AgentJob
metadata:
  name: refactor-payment-service
spec:
  task:
    description: "Extract the payment retry logic into its own module"
    acceptanceCriteria:
      - "Existing tests still pass"
      - "Retry behavior is unchanged"
    focusFiles: ["internal/payments/"]
  repository:
    url: "https://github.com/org/payments"
    createDraftPR: true
  agent:
    harness: pi          # multi-model harness
    model: "claude-sonnet-5"
  timeoutSeconds: 5400
  maxCostDollars: "2.00"
  interactionMode:
    mode: checkpoints
    checkpointTriggers: [before_commit, before_pr]

With checkpointTriggers set, the agent pauses at each trigger and waits up to one hour for approval in the dashboard before continuing.