Agent Configuration

Agent centralizes execution environment configuration:

apiVersion: kubeopencode.io/v1alpha1
kind: Agent
metadata:
  name: default
spec:
  profile: "Default development agent with org standards and GitHub access"
  agentImage: ghcr.io/kubeopencode/kubeopencode-agent-opencode:latest
  executorImage: ghcr.io/kubeopencode/kubeopencode-agent-devbox:latest
  attachImage: ghcr.io/kubeopencode/kubeopencode-agent-attach:latest
  workspaceDir: /workspace
  command: ["opencode", "serve"]
  port: 4096
  serviceAccountName: kubeopencode-agent

  # Additional ports (DinD, VS Code, etc.)
  extraPorts:
    - name: docker
      port: 2375
      targetPort: 2375
      protocol: TCP

  # Default contexts for all tasks (inline ContextItems)
  contexts:
    - type: Text
      text: |
        # Organization Standards
        - Use signed commits
        - Follow Go conventions

  # Skills from external Git repos
  skills:
    - name: team-skills
      git:
        repository: https://github.com/my-org/ai-skills.git
        ref: main
        path: skills/

  # OpenCode plugins (installed via npm at pod startup)
  plugins:
    - name: cc-safety-net
    - name: "@nicholasgriffintn/opencode-plugin-otel"
      options:
        endpoint: "http://otel-collector:4318"

  # OpenCode configuration (inline YAML object)
  config:
    $schema: https://opencode.ai/config.json
    model: google/gemini-2.5-pro
    small_model: google/gemini-2.5-flash

  # Credentials (secrets as env vars or file mounts)
  credentials:
    - name: github-token
      secretRef:
        name: github-creds
        key: token
      env: GITHUB_TOKEN

    - name: ssh-key
      secretRef:
        name: ssh-keys
        key: id_rsa
      mountPath: /home/agent/.ssh/id_rsa
      fileMode: 0400

  # Custom CA certificates
  caBundle:
    configMapRef:
      name: corporate-ca-bundle
      key: ca-bundle.crt

  # HTTP/HTTPS proxy
  proxy:
    httpProxy: "http://proxy.corp.example.com:8080"
    httpsProxy: "http://proxy.corp.example.com:8080"
    noProxy: "localhost,127.0.0.1,.svc,.cluster.local"

  # Private registry authentication
  imagePullSecrets:
    - name: my-registry-secret

  # Task concurrency control
  maxConcurrentTasks: 3
  quota:
    maxTaskStarts: 20
    windowSeconds: 3600

  # Shareable terminal link
  share:
    enabled: true
    expiresAt: "2026-12-31T23:59:59Z"
    allowedIPs:
      - "10.0.0.0/8"

  # Pod-level customization
  podSpec:
    labels:
      team: platform
    runtimeClassName: sysbox
    securityContext:
      runAsNonRoot: true
      allowPrivilegeEscalation: false
    extraEnv:
      - name: NODE_OPTIONS
        value: "--max-old-space-size=4096"
    extraVolumes:
      - name: docker-sock
        hostPath:
          path: /var/run/docker.sock
    extraVolumeMounts:
      - name: docker-sock
        mountPath: /var/run/docker.sock

Field Reference

Core Fields

Field	Type	Default	Description
`profile`	string	-	Brief human-readable summary (informational only)
`agentImage`	string	`ghcr.io/kubeopencode/kubeopencode-agent-opencode:latest`	OpenCode init container image
`executorImage`	string	`ghcr.io/kubeopencode/kubeopencode-agent-devbox:latest`	Main worker container image
`attachImage`	string	`ghcr.io/kubeopencode/kubeopencode-agent-attach:latest`	Lightweight image for Task Pods (agentRef mode)
`workspaceDir`	string	`/workspace`	Agent working directory
`command`	[]string	`["opencode", "serve"]`	Command to run in the worker container
`port`	int32	4096	OpenCode server port
`serviceAccountName`	string	-	Kubernetes ServiceAccount for the Agent pod

Context and Knowledge

Field	Type	Default	Description
`contexts`	[]ContextItem	-	Inline context definitions (Text, ConfigMap, Git, Runtime, URL). See Context System
`skills`	[]SkillSource	-	External SKILL.md sources from Git repos. See Skills

Configuration and Extensibility

Field	Type	Default	Description
`plugins`	[]PluginSpec	-	OpenCode plugins to install and load. See Plugins
`config`	*runtime.RawExtension	-	Inline OpenCode configuration (YAML/JSON object). Mutually exclusive with `configRef`
`configRef`	*OpenCodeConfigSource	-	Reference a ConfigMap or Secret containing the OpenCode config JSON. Mutually exclusive with `config`

Security and Authentication

Field	Type	Default	Description
`credentials`	[]Credential	-	Secrets mounted as env vars or file mounts. See Security
`caBundle`	*CABundleConfig	-	Custom CA certificates for TLS. See Enterprise
`proxy`	*ProxyConfig	-	HTTP/HTTPS proxy settings. See Enterprise
`imagePullSecrets`	[]LocalObjectReference	-	Private registry authentication

Concurrency Control

Field	Type	Default	Description
`maxConcurrentTasks`	*int32	-	Maximum number of Tasks running simultaneously. See Concurrency & Quota
`quota`	*QuotaConfig	-	Rate limiting for Task starts. See Concurrency & Quota

Persistence and Lifecycle

Field	Type	Default	Description
`persistence`	*PersistenceConfig	-	Session/workspace PVCs. See Persistence
`suspend`	bool	false	Scale Deployment to 0 replicas. See Persistence
`standby`	*StandbyConfig	-	Automatic suspend/resume lifecycle. See Persistence

Networking

Field	Type	Default	Description
`extraPorts`	[]ExtraPort	-	Additional Service/Deployment ports (DinD, VS Code, etc.)
`share`	*ShareConfig	-	Shareable terminal link. See Share Link

Pod Customization

Field	Type	Default	Description
`podSpec`	*AgentPodSpec	-	Pod-level customization (security, scheduling, volumes, etc.). See Pod Configuration
`templateRef`	*AgentTemplateReference	-	Inherit base config from an AgentTemplate. See Agent Templates

OpenCode Configuration

The config field allows you to provide OpenCode configuration as an inline YAML object:

apiVersion: kubeopencode.io/v1alpha1
kind: Agent
metadata:
  name: opencode-agent
spec:
  profile: "OpenCode agent with custom model configuration"
  agentImage: ghcr.io/kubeopencode/kubeopencode-agent-opencode:latest
  executorImage: ghcr.io/kubeopencode/kubeopencode-agent-devbox:latest
  workspaceDir: /workspace
  serviceAccountName: kubeopencode-agent
  config:
    $schema: https://opencode.ai/config.json
    model: anthropic/claude-sonnet-4-5
    small_model: anthropic/claude-haiku-4-5

The configuration is serialized to a config file inside the container and the OPENCODE_CONFIG environment variable is set automatically. See OpenCode configuration schema for available options.

External Configuration (configRef)

Alternatively, you can reference a ConfigMap or Secret containing the OpenCode config JSON using configRef. This is useful when you want to manage the config separately, share it across multiple Agents, or store sensitive values in Secrets:

From a ConfigMap:

apiVersion: kubeopencode.io/v1alpha1
kind: Agent
metadata:
  name: opencode-agent
spec:
  profile: "OpenCode agent with ConfigMap-based config"
  agentImage: ghcr.io/kubeopencode/kubeopencode-agent-opencode:latest
  executorImage: ghcr.io/kubeopencode/kubeopencode-agent-devbox:latest
  workspaceDir: /workspace
  serviceAccountName: kubeopencode-agent
  configRef:
    configMapRef:
      name: my-opencode-config
      # key defaults to "opencode.json" if omitted
---
apiVersion: v1
kind: ConfigMap
metadata:
  name: my-opencode-config
data:
  opencode.json: |
    {
      "$schema": "https://opencode.ai/config.json",
      "model": "anthropic/claude-sonnet-4-5",
      "small_model": "anthropic/claude-haiku-4-5"
    }

From a Secret (useful when the config contains sensitive values like API keys):

apiVersion: kubeopencode.io/v1alpha1
kind: Agent
metadata:
  name: opencode-agent
spec:
  profile: "OpenCode agent with Secret-based config"
  agentImage: ghcr.io/kubeopencode/kubeopencode-agent-opencode:latest
  executorImage: ghcr.io/kubeopencode/kubeopencode-agent-devbox:latest
  workspaceDir: /workspace
  serviceAccountName: kubeopencode-agent
  configRef:
    secretRef:
      name: my-opencode-config-secret
      # key defaults to "opencode.json" if omitted

configRef fields:

Field	Type	Default	Description
`configMapRef`	*OpenCodeConfigMapReference	-	Reference a ConfigMap containing the OpenCode config JSON. Mutually exclusive with `secretRef`
`secretRef`	*OpenCodeConfigSecretReference	-	Reference a Secret containing the OpenCode config JSON. Mutually exclusive with `configMapRef`

Nested reference fields (configMapRef / secretRef):

Field	Type	Default	Description
`name`	string	(required)	Name of the ConfigMap/Secret in the same namespace
`key`	string	`opencode.json`	Key in the ConfigMap/Secret containing the OpenCode config JSON

Note: config and configRef are mutually exclusive. The controller enforces this at reconcile time (since the config field uses x-kubernetes-preserve-unknown-fields, CRD-level CEL validation cannot reference it). If both are set, the Agent will fail to reconcile and no Deployment will be created.

Agent-Only Fields

The following fields can only be set on Agent (not on AgentTemplate):

Field	Description
`profile`	Human-readable agent summary
`port`	OpenCode server port
`persistence`	Session/workspace PVCs
`suspend`	Manual suspend flag
`standby`	Auto suspend/resume config
`share`	Shareable terminal link config
`templateRef`	Reference to AgentTemplate

See Agent Templates for merge behavior when using templateRef.

Field Reference​

Core Fields​

Context and Knowledge​

Configuration and Extensibility​

Security and Authentication​

Concurrency Control​

Persistence and Lifecycle​

Networking​

Pod Customization​

OpenCode Configuration​

External Configuration (configRef)​

Agent-Only Fields​