Welcome to Nimbus

Introduction

Nimbus is designed to be a platform that supports the deployment, management, and coordination of an "Agent" fleet by leveraging Kubernetes primitives to create a delivery platform that can scale to your needs by managing the lifecycle of multiple agents.

The platform is designed with the following goals:

1. Don't reinvent the wheel - Agent deployments are fundamentally coordinated OCI-compatible containers using known technologies running on Kubernetes to provide a well-understood deployment mechanism. Agents are containerized versions of well-known agent platforms (i.e. Codex, OpenCode, pi, etc.).
2. Defined Ownership - Authorisation, resource ownership, and access roles can be defined through an existing OIDC-compatible provider (or a custom IdP stack that supports OIDC).
3. Horizontal Scalability - Reduce single points of failure by leveraging Kubernetes to allow components to scale horizontally as demand grows over time.
4. Clear Operational Boundaries - Components have defined roles with clear interfaces.
5. Observability - Meaningful insights should be provided out of the box such that Agents can be effectively managed, controlled, and coordinated.

What Nimbus is not:

1. An Agent - Nimbus isn't an Agent (like Claude, OpenClaw, Codex, etc.)
2. An Agent Secrets Manager - Secrets management is best handled by a proper Secrets platform (i.e. Vault)

Nimbus builds on the strengths of well-established technologies to provide an abstraction layer that allows Agents to be defined, orchestrated, executed, and triggered.

Simplified High-Level Architecture

flowchart TD
    subgraph k8s[Kubernetes]
        direction TB

        subgraph backend[Backend Services]
            operator[Nimbus Operator]
        end

        subgraph frontend[Frontend Services]
            ui[Nimbus UI]
            api[Nimbus API]
        end

        k8sapi[Kubernetes API]
        cr@{ shape: procs, label: "**Nimbus CRs**<br/>AgentDefinition</br>AgentDeployment<br/>AgentStorage<br/>..."}
        k8sobj@{ shape: procs, label: "**K8S Objects**<br/>Deployment</br>ConfigMap<br/>Service<br/>Ingress</br>..."}
    end

    ui <-- Authorized API calls --> api

    api -- Create/Edit<br/>Nimbus CRs --> k8sapi
    operator <-- Watches</br>Nimbus CRs --> k8sapi
    operator <-- Reconciles --> cr
    operator <-- Produces --> k8sobj

Key Concepts

The core of the platform centers around a Kubernetes Operator (nimbus-operator) and a set of Custom Resource Definitions (CRDs) that act as an abstraction layer representing an agent deployment. It is the responsibility of nimbus-operator to reconcile the Custom Resources (CRs) into managed Kubernetes objects. The design abstracts away the need to create bespoke Deployments, Services, Ingresses, Pods, Jobs, CronJobs, etc. into a set of understandable concepts, leaning on Kubernetes to do the heavy lifting of running containers.

While the core mechanism for transforming Nimbus CRs into Kubernetes objects is the nimbus-operator, API access is provided by nimbus-api. The API layer provides a RESTful interface to the CRs while also providing access control, some input validation, and extra control flow for input/output operations. The nimbus-ui is a view on top of the API that provides a convenient way to visualise and interact with agent deployments. nimbus-ui does not provide any real application logic, but it does provide the interaction point for an external IdP provider to obtain authorisation tokens, which are in turn validated by nimbus-api on various API calls.

Components

The following components form part of the Nimbus platform and are used in various stages of the Agent lifecycle:

Component	Technology	Description
nimbus-operator	Golang Kubebuilder	Watches and resolves all Nimbus CRs and creates corresponding Kubernetes objects
nimbus-api	Golang	Provides the RESTful CRUD API layer and calls into Kubernetes to create, update, and delete Nimbus CRs. Also provides SSE events for Nimbus CR changes, log downloading for image builds, and runtime information for the agents.
nimbus-builder	Golang Docker	Provides a mechanism to build and push container images from a templated set of Dockerfiles, creating an easy and repeatable way to build an agent container image without fuss.
nimbus-ui	TypeScript Next.js	Provides a frontend to simplify and democratise the Nimbus CRs, with a user-friendly way to access and view logs, open a shell into the agent, test webhooks, and validate agent responses

When agents are running, they are deployed as a collection of related pods with a number of auxiliary components to aid in providing access. Each agent has its own set of independent supporting services in order to maintain a strict separation of resources.

Component	Technology	Description
nimbus-webhook-manager	Golang	An HTTP service that dynamically registers webhooks created for the agent
nimbus-ws-proxy	Golang	An HTTP service that exposes a set of WebSockets for low-level container access for the shell or control ports

There are a number of supporting components also defined which are used for deployment or development:

Component	Technology	Description
nimbus-helm	Helm chart	The Helm charts used to deploy the CRDs, RBAC rules, and Nimbus services
nimbus-auth	Tilt	A complete local development stack supporting auth, certificates, ingress, object storage, trust distribution, and LLM API access.

Custom Resources

The core infrastructural components are the Nimbus CRDs. The CRDs provide an abstraction for the lifecycle of an agent and a convenient way to manage a number of Kubernetes resources without the user needing to specifically manage or have access to a K8S cluster. The CRDs that are managed by Nimbus are:

Custom Resource	Description
AgentDefinition	The AgentDefinition is a high-level outline of an agent that includes what should be run, what files or secrets should be linked, and what ports are exposed.
AgentDeployment	The AgentDeployment renders the AgentDefinition into a set of managed Kubernetes objects (Deployments, Service, Ingress, etc.). The K8S objects are owned by the AgentDeployment. Deployments can be persistent or on-demand.
AgentFile	The AgentFile stores file content that can be rendered into a generated ConfigMap and mounted into agent containers that reference it.
AgentImage	The AgentImage defines how to build or describe an agent container image, including packages, install commands, runtime commands, directories, users, control ports, and whether the process is wrapped by the Nimbus proxy.
AgentSecret	The AgentSecret is a Nimbus-level reference to an existing Kubernetes Secret in the same namespace. It allows agent definitions or deployments to link secrets without embedding secret data directly.
AgentStorage	The AgentStorage describes persistent storage for agents, including the requested PVC size, storage class, and access mode. It can also represent system-managed storage created for agent requirements such as bootstrapped skills.
AgentTrigger	The AgentTrigger sends a prompt, and optionally a payload, to a target AgentDeployment. It represents a concrete request for an agent to do work.
AgentTriggerTemplate	The AgentTriggerTemplate stores a reusable AgentTrigger spec. Webhooks, timed triggers, or other callers can use it to create AgentTrigger resources consistently.
AgentTimedTrigger	The AgentTimedTrigger schedules trigger creation using a cron expression. When enabled, it creates AgentTrigger resources from an AgentTriggerTemplate on the configured schedule.
AgentWebhook	The AgentWebhook exposes an HTTP route and method that can create AgentTrigger resources from an AgentTriggerTemplate. It can optionally require a bearer access token.
Settings	The Settings resource stores operator-level configuration values such as component images, ingress settings, certificate-manager integration, and builder registry options.