Skip to content
Astromesh Astromesh

Astromesh Nexus

Astromesh Nexus is a Kubernetes operator that acts as the multi-tenant control plane for the Astromesh ecosystem. It provisions isolated tenants — one Kubernetes namespace each — deploys a dedicated astromesh-node instance per tenant, and synchronizes AI agents into those nodes through a single REST API.

External clients call the Nexus REST API; Nexus translates those calls into custom resources; reconcilers then drive the per-tenant nodes that actually run the agents.

What Nexus Is

Section titled “What Nexus Is”
  • A Kubernetes operator built with Kubebuilder v4 and controller-runtime.
  • A multi-tenant control plane that isolates each tenant in its own namespace.
  • A provisioner: it stands up an astromesh-node Deployment and Service per tenant.
  • An agent synchronizer: it registers and deploys agents to the right tenant node and tracks their status.
  • A REST API gateway (Gin, :8080) with dual authentication for interactive users and programmatic clients.

What Nexus Is NOT

Section titled “What Nexus Is NOT”
  • It is not the agent runtime. Agents execute inside astromesh-node (port 8000), not in Nexus.
  • It does not execute agents directly. Nexus turns API requests into custom resources and lets the node run them.
  • It is not a single-tenant tool. Its entire design centers on tenant isolation.

Ecosystem Role

Section titled “Ecosystem Role”

Nexus is the cloud control plane that the rest of the ecosystem deploys agents to. Cortex, Forge, and Leia all target Nexus, which fans agents out to per-tenant nodes. See the ecosystem overview for the full picture.

                         Kubernetes Cluster
  ┌───────────────────────────────────────────────────────────┐
  │  nexus-system namespace                                    │
  │   ┌─────────────────────────────────────────────────┐     │
  │   │ Nexus Control Plane                              │     │
  │   │  REST API (Gin :8080)   NexusTenantReconciler    │     │
  │   │  SQLite Store           NexusAgentReconciler     │     │
  │   └─────────────────────────────────────────────────┘     │
  │                                                            │
  │  tenant-a namespace          tenant-b namespace            │
  │   astromesh-node (:8000)      astromesh-node (:8000)       │
  │   agent-1, agent-2            agent-a                      │
  └───────────────────────────────────────────────────────────┘
        ▲
        │ POST /api/v1/agents  (X-API-Key / Bearer JWT)
   User / Cortex / Leia

Key Concepts

Section titled “Key Concepts”

Tenants

Section titled “Tenants”

A tenant is an isolated workspace. Creating one provisions a dedicated Kubernetes namespace and a per-tenant astromesh-node. Tenants are modeled by the NexusTenant CRD and carry a resourceQuota (max agents, CPU, memory).

Per-Tenant Node

Section titled “Per-Tenant Node”

Every tenant gets its own astromesh-node Deployment and Service inside its namespace, listening on port 8000 with health probes on /v1/health. Nexus records the node’s in-cluster endpoint on the tenant’s status.nodeEndpoint.

Agents

Section titled “Agents”

Agents are defined by the NexusAgent CRD, whose spec carries a full astromesh/v1 Agent spec as a pass-through. The NexusAgentReconciler registers and deploys each agent to its tenant’s node and reports phase, nodeAck, and lastSyncedAt.

Dual Authentication

Section titled “Dual Authentication”

The REST API accepts two credential types: a Bearer JWT (interactive sessions, optionally scoped with an X-Tenant-ID header) or an X-API-Key (programmatic, tenant-scoped). Auth and health routes are public; everything under /api/v1/* requires one of the two.

What’s Next

Section titled “What’s Next”
  • Architecture — control-plane components, reconcilers, and the two CRDs.
  • Quickstart — bootstrap Nexus on Kind and deploy your first agent.
  • API Reference — auth model, endpoints, and a curl walkthrough.