User Examples

Always running agent

Sam wants to deploy a persistent agent running OpenClaw and access it via the mechanisms Nimbus provides.

Sam creates two AgentFiles, which will be used to store the OpenClaw configuration, and another to store the OpenClaw AGENTS.md file. Sam decides to manually deploy the Custom Resources to create the object. They could have just as easily performed this task using nimbus-ui without having to manually construct the YAML:

Note

Setting up the CRs is not advisable; this is purely to demonstrate the underlying concepts. Agent creation with nimbus-ui via nimbus-api is the correct approach. The Quick Create Wizard is designed to simplify these agent creation steps.

Example

openclaw-config.yamlopenclaw-agent-md.yaml

apiVersion: crd.nimbus.io/v1alpha1
kind: AgentFile
metadata:
   name: openclaw-config
spec:
   data: |
      {
         "gateway": {
            "mode": "local",
            "bind": "lan",
            "port": 18789,
            "auth": {
               "mode": "token"
            },
            "controlUi": {
               "enabled": true,
               "allowedOrigins": [
                  "https://openclaw-sam.web.int.ellefsen.ninja"
               ]
            }
         },
         "models": {
            "providers": {
               "nimbus": {
                  "baseUrl": "http://litellm.llm.svc.cluster.local:4000/v1",
                  "apiKey": "${OPENAI_API_KEY}",
                  "api": "openai-completions",
                  "models": [
                     {
                        "id": "openrouter/openrouter/free",
                        "name": "Openrouter Free"
                     }
                  ]
               }
            }
            }, 
            "agents": {
            "defaults": {
               "workspace": "~/.openclaw/workspace",
               "model": {
                  "primary": "nimbus/openrouter/openrouter/free"
               }
            },
            "list": [
               {
                  "id": "default",
                  "name": "OpenClaw Assistant",
                  "workspace": "~/.openclaw/workspace"
               }
            ]
         },
         "cron": { "enabled": false }
      }

apiVersion: crd.nimbus.io/v1alpha1
kind: AgentFile
metadata:
   name: openclaw-agents-md
spec:
   data: |
      You are SamBot and you are an agent!

Sam creates two AgentSecret objects, one that will be used to reference the API keys for the LLM and another that will contain the gateway token for OpenClaw.

Example

openclaw-api-secret.yamlopenclaw-gateway-token.yaml

apiVersion: v1
kind: Secret
metadata:
   name: virtual-api-secret
type: Opaque
stringData:
   OPENAI_API_KEY: "sk-1234"
   OPENAI_BASE_URL: "http://litellm.llm.svc.cluster.local:4000/v1"
---
apiVersion: crd.nimbus.io/v1alpha1
kind: AgentSecret
metadata:
   name: openclaw-api-secret
spec:
   secretRef:
      name: virtual-api-secret

apiVersion: v1
kind: Secret
metadata:
   name: openclaw-token-secret
type: Opaque
stringData:
   OPENCLAW_GATEWAY_TOKEN: "57724cb3-de07-4ba7-9851-7b7c0ac915d9"
---
apiVersion: crd.nimbus.io/v1alpha1
kind: AgentSecret
metadata:
   name: openclaw-gateway-token
spec:
   secretRef:
      name: openclaw-token-secret

Sam knows there will be persistent storage required so they create AgentStorage that will be used for the workspace.

Example

openclaw-storage.yaml

apiVersion: crd.nimbus.io/v1alpha1
kind: AgentStorage
metadata:
   name: openclaw-storage
spec:
   size: "1Gi"

Sam then defines the AgentDefinition, which will tell Nimbus how they want the agent to be constructed when it is deployed. Sam decides to use the official OpenClaw container image for this definition:

Example

openclaw-definition.yaml

apiVersion: crd.nimbus.io/v1alpha1
kind: AgentDefinition
metadata:
   name: openclaw-bot
spec:
   image: "ghcr.io/openclaw/openclaw:slim"
   type: Web
   agentFile:
      openclaw-config: /home/node/.openclaw/openclaw.json
      openclaw-agents-md: /home/node/.openclaw/workspace/AGENTS.md
   agentStorage:
      openclaw-storage: /home/node/.openclaw/workspace
   secretEnv:
      - name: agentsecret-openai-sample
      - name: openclaw-gateway-token
   controlPort: 18789

Finally Sam creates the AgentDeployment which will build the persistent deployment

Example

openclaw-deployment.yaml

apiVersion: crd.nimbus.io/v1alpha1
kind: AgentDeployment
metadata:
   name: openclaw-bot
spec:
   agentDefinition: openclaw-bot
   identifier: openclaw-sam

Once the deployment is applied, Nimbus will go ahead and roll out the Agent Stack based on Sam's definitions. OpenClaw has an opinionated setup, but as long as there is persistent storage, configuration items will persist across container restarts. nimbus-ui provides a convenient way to access the pod shell, pod logs, and the OpenClaw control UI.

Shell Access

Web Redirect

OpenClaw Control UI

On-demand review agent

Sam wants to deploy a managed agent on Nimbus in order to automatically trigger a code review when a PR is created.
Sam decides that they need a few different objects to achieve this:
1. An agent that is running on the Nimbus platform.
2. A trigger that can be fired when a webhook comes in.
3. Persistent scratch storage space for the agent to use to download the repo in question.
4. A system prompt that the agent can use to understand what work it needs to do.
5. A set of skills that the agent needs to be bootstrapped into the agent.
Sam accesses the nimbus-ui and creates the following items:
1. Sam defines the system prompt and stores it as an AgentFile.
2. Sam allocates some storage, which is created using an AgentStorage resource.
3. Sam decides they need extra packages in the container, so they create an AgentImage to build a new agent container (however, a pre-existing image could also be used).
4. Sam defines the secrets that this agent will need (for example, an API key). They create an AgentSecret to link the secret in Kubernetes to what will be used by the agent container.
5. Sam defines their AgentDefinition, which links the AgentFile to a known mount point, the AgentSecret to the environment variables used by the agent, the AgentStorage to a mount point in the container, and marks it as a "trigger only" agent, along with any skills that should be bootstrapped into the container.
6. Sam then defines an AgentTriggerTemplate, which describes how the agent should be invoked when a webhook request comes in.
7. Sam lastly defines the AgentWebhook, specifying the route, method, and authentication token that should be used when the webhook is called.
Sam is then provided a system-created URL for their webhook, which can be used directly in the upstream service to trigger the agent.

In the backend, the following actions are taken by the operator when it is reconciling Sam's objects:

The AgentFile content gets rendered into a ConfigMap.
The AgentStorage gets rendered into a PersistentVolume.
The AgentImage invokes the nimbus-builder, which builds and pushes the image to the system-configured registry.
The AgentSecret validates that the referenced Secret exists and persists the reference.
The AgentDefinition validates that all the referenced objects exist in the system.
The AgentDeployment gets rendered into a Deployment, Service, and Ingress, which starts the nimbus-webhook-manager for this deployment.
The AgentTriggerTemplate is validated against the existing objects in the system.
The AgentWebhook is validated, and the nimbus-webhook-manager dynamically creates the routes and starts listening for requests.

When a webhook request comes in, the nimbus-webhook-manager will:

Validate that the route is known for the agent.
Use the AgentTriggerTemplate to create an AgentTrigger.
The AgentTrigger is then resolved into a Job, which starts the agent container and executes the prompt defined in the template.