Skip to content

Custom Resource Definitions

The Nimbus Custom Resource Definitions are used to define Nimbus agent resources. The relationship between the CRDs and their role in the system can be described by the following diagram.

flowchart TD
  AgentImage[AgentImage] -. builds optional image for .-> AgentDefinition

  AgentDefinition[AgentDefinition] -->|references| ContainerImage[(Container image)]
  AgentDefinition -->|references| AgentFile[AgentFile]
  AgentDefinition -->|references| AgentStorage[AgentStorage]
  AgentDefinition -->|references| AgentSecret[AgentSecret]

  AgentSecret -->|references| KubernetesSecret[(Kubernetes Secret)]
  AgentFile -->|rendered as| ConfigMap[(ConfigMap)]
  AgentStorage -->|realized as| PersistentVolumeClaim[(PersistentVolumeClaim)]

  AgentDeployment[AgentDeployment] -->|uses| AgentDefinition
  AgentDeployment -->|creates| RuntimeResources([K8S Resources])

  AgentTrigger[AgentTrigger] -->|invokes| AgentDeployment
  AgentTriggerTemplate[AgentTriggerTemplate] -->|defines| AgentTrigger
    AgentTimedTrigger -->|realized as| CronJob[(CronJob)]
  AgentTimedTrigger[AgentTimedTrigger] -->|references| AgentTriggerTemplate
  AgentWebhook[AgentWebhook] -->|references| AgentTriggerTemplate
  AgentWebhook -->|routes requests through| WebhookManager([Agent webhook manager])

  WebhookManager -->|creates| AgentTrigger
  CronJob -->|creates| AgentTrigger

AgentDefinition

An AgentDefinition is an abstract container definition. It is realized by an AgentDeployment. It is reusable and composable, defining how the agent should run.

Fields

Field Description
image OCI-compatible container image used to run the agent pod.
type Agent runtime type used by the controller to select runtime defaults; valid values are Pi, Acp, Web, and Unknown.
agentFile Map of AgentFile resource names to file paths where their contents should be mounted in the container.
agentStorage Map of AgentStorage resource names to directory paths where persistent volumes should be mounted in the container.
env Literal environment variables added to the agent container.
secretEnv List of AgentSecret references whose Kubernetes Secret data should be exposed as environment variables.
secretEnv[].name Name of an AgentSecret resource to inject into the deployment environment.
command Command array used to override the container image entrypoint.
args Argument array used to override the container image command.
stdin Whether the agent container should keep standard input open.
tty Whether the agent container should allocate a pseudo-TTY.
controlPort Agent container TCP port exposed through the control proxy for runtime interaction.
exposedPorts Additional agent container TCP ports exposed on the generated agent Service.
skills Skill URLs or shorthand skill references that should be initialized into the agent container.
Example 
apiVersion: crd.nimbus.io/v1alpha1
kind: AgentDefinition
metadata:
  name: agentdefinition-acp-opencode
spec:
  image: "registry.k8s.ellefsen.ninja/opencode-acp:latest"
  agentStorage:
    opencode-acp-storage: /home/opencode/workspace
    opencode-acp-config: /home/opencode/.opencode
  secretEnv:
    - name: agentsecret-sample
  type: Acp
  controlPort: 9000

AgentDeployment

An AgentDeployment is the realized form of an AgentDefinition, as either a Persistent or Triggerable agent. This object represents the deployable unit created in Kubernetes and resolved by the operator.

Fields

Field Description
agentDefinition Name of the AgentDefinition used to build runtime resources for this deployment.
triggerOnly Whether to skip the persistent agent deployment and run agents only when AgentTrigger resources are created.
identifier Stable identifier used to name and label generated runtime resources; generated by the controller if omitted.
sessionIdentifier Identifier used to label the current agent session; generated by the controller if omitted.
Example 
apiVersion: crd.nimbus.io/v1alpha1
kind: AgentDeployment
metadata:
  name: opencode-acp-persistent
spec:
  agentDefinition: agentdefinition-acp-opencode
  identifier: opencode-acp-ai

AgentFile

An AgentFile is plain text that can be mounted into an Agent by providing a mount point as part of the definition. AgentFile resources are used for injecting prompts, configuration, or any other managed plain text that needs to be exposed to an Agent.

Fields

Field Description
data Plain text file content stored in the generated ConfigMap and mounted into referencing agent containers.
Example 
apiVersion: crd.nimbus.io/v1alpha1
kind: AgentFile
metadata:
  name: system-prompt
spec:
  data: |
    You are a helpful assistant. You have access to a linux environment
    and can make use of the available terminal utilities to answer the user's
    prompt.

    This is a non-interactive environment. You must respond to the user with
    the final and complete answer and cannot prompt for additional information.

AgentImage

An AgentImage is a standalone component. It is used to create an OCI-compatible container image that is pushed to a configured container registry. AgentImage has a strict set of templated options used to build the image. The goal is to allow vetted image builds with some customization without requiring the user to provide their own image. An AgentImage is not required for an AgentDefinition; a definition can reference any container image.

Fields

Field Description
packages Operating system packages installed into the generated agent image.
user Container user used to run the agent process.
controlPort TCP port exposed by the agent process or Nimbus wrapper, defaulting to 9000.
installCommands Commands run during image build to install the agent software.
command Command array used to start the agent process in the generated image.
directories Directories created in the image before the agent process runs.
wrapped Whether Nimbus should wrap the agent process to expose stdio over the configured TCP port.
Example 
apiVersion: crd.nimbus.io/v1alpha1
kind: AgentImage
metadata:
  name: opencode-ai
spec:
  packages:
    - npm
    - curl
    - ripgrep
    - fd
    - tmux
    - util-linux
    - python3
  installCommands:
    - npm install -g opencode-ai
  directories:
    - /home/agent/.config/opencode
  controlPort: 9000
  command:
    - opencode
    - serve
    - --port
    - "9000"
    - --hostname
    - 0.0.0.0

AgentSecret

An AgentSecret is a reference to a Kubernetes Secret. The secret must already exist, and the AgentSecret resource provides a reusable way to reference it from an AgentDefinition. Nimbus does not create secrets on its own. Secrets need to be injected into the namespace by a dedicated secrets management framework, such as Vault.

Fields

Field Description
secretRef Reference to an existing Kubernetes Secret in the same namespace.
secretRef.name Name of the Kubernetes Secret whose data should be made available through this AgentSecret.
Example 
apiVersion: v1
kind: Secret
metadata:
  name: test-api-secret
type: Opaque
stringData:
  TEST_API_KEY: "sk-1234"
---
apiVersion: crd.nimbus.io/v1alpha1
kind: AgentSecret
metadata:
  name: agentsecret-sample
spec:
  secretRef:
    name: test-api-secret

AgentStorage

An AgentStorage represents a block of persistent storage referenced by an AgentDefinition and mounted into the container when the deployment is rendered. It is realized as a Persistent Volume in Kubernetes.

Fields

Field Description
size Requested storage size for the generated PersistentVolumeClaim, such as 1Gi or 10Mi.
storageclass Kubernetes StorageClass name for the generated PersistentVolumeClaim; the cluster default is used if omitted.
readwritemany Whether the generated PersistentVolumeClaim should use ReadWriteMany; otherwise ReadWriteOnce is used.
systemManaged Indicates the volume was created by the controller for an internal requirement, such as bootstrapping skills.
Example 
apiVersion: crd.nimbus.io/v1alpha1
kind: AgentStorage
metadata:
  name: opencode-acp-storage
spec:
  size: "1Gi"
  readwritemany: false
---
apiVersion: crd.nimbus.io/v1alpha1
kind: AgentStorage
metadata:
  name: opencode-acp-config
spec:
  size: "10Mi"
  readwritemany: false

AgentTrigger

An AgentTrigger is a one-shot action executed against an Agent using the control mechanism it supports, if it exposes an appropriate control port and communication mechanism. The AgentTrigger is realized as a Job in Kubernetes and will either communicate with the agent via its control port, in the case of a Persistent deployment, or spawn an on-demand AgentDeployment to perform the task.

Fields

Field Description
agentDeployment Name of the AgentDeployment used to resolve where the trigger should run.
prompt Prompt text passed to the agent job or persistent agent when the trigger runs.
payload Optional payload text inserted into the prompt wherever the payload placeholder is used.
Example 
apiVersion: crd.nimbus.io/v1alpha1
kind: AgentTrigger
metadata:
  name: trigger-opencode-sample
spec:
  agentDeployment: opencode-acp-persistent
  prompt: |
    "Please answer the following question: {{ .Payload }}"
  payload: How many r's are in the word Strawberry?

AgentTriggerTemplate

An AgentTriggerTemplate is a reusable template for an AgentTrigger that is used by either an AgentTimedTrigger or an AgentWebhook. It is used to create repeatable AgentTrigger resources.

Fields

Field Description
template AgentTrigger spec used by webhook handling or other callers when creating triggers from this template.
template.agentDeployment Name of the AgentDeployment used by generated triggers.
template.prompt Prompt text used by generated triggers.
template.payload Optional payload text used by generated triggers.
Example 
apiVersion: crd.nimbus.io/v1alpha1
kind: AgentTriggerTemplate
metadata:
  name: agenttriggertemplate-sample
spec:
  template:
    agentDeployment: pi-dev-ai
    prompt: |
      "Please answer the following question: {{ .Payload }}"
    payload: How many r's are in the word Strawberry?

AgentTimedTrigger

An AgentTimedTrigger can be fired on a schedule defined by a CronSpec. It uses the referenced AgentTriggerTemplate to create the corresponding AgentTrigger. This is realized through a CronJob on Kubernetes.

Fields

Field Description
cronSpec Cron-formatted schedule that determines when this timed trigger fires.
agentTriggerTemplate Name of the AgentTriggerTemplate used to create AgentTrigger resources when the cron schedule fires.
enabled Whether the timed trigger is active; when disabled, the generated CronJob is suspended.
Example 
apiVersion: crd.nimbus.io/v1alpha1
kind: AgentTimedTrigger
metadata:
  name: agenttimedtrigger-sample
spec:
  cronSpec: "* * * * *"
  agentTriggerTemplate: agenttriggertemplate-sample
  enabled: false

AgentWebhook

An AgentWebhook provides a link between an HTTP route and an AgentTriggerTemplate. The agent-webhook-manager associated with the AgentDeployment is responsible for accepting the request and creating the AgentTrigger from the referenced AgentTriggerTemplate.

Fields

Field Description
route HTTP request path matched by this webhook.
method HTTP method accepted by this webhook; valid values are GET, POST, and PUT.
agentTriggerTemplate Name of the AgentTriggerTemplate used to create AgentTrigger resources for matching webhook requests.
accessToken Optional bearer token required for calls to the webhook endpoint.
Example 
apiVersion: crd.nimbus.io/v1alpha1
kind: AgentWebhook
metadata:
  name: agentwebhook-sample
spec:
  agentTriggerTemplate: agenttriggertemplate-payload-sample
  route: /agent/trigger
  method: GET
  accessToken: password-12345