Skip to content

Install on Kubernetes#

Mirantis Agent Platform installs into your own Kubernetes cluster from a Helm chart published to GHCR as an OCI artifact. There is no hosted control plane to send workloads to: the platform server, the sandboxes it runs, the database, and the audit trail all stay inside your cluster.

helm install lens-agents oci://ghcr.io/lensapp/lens-agents \
  --set encryption.key="$(openssl rand -hex 32)" \
  --set config.publicUrl="https://agents.example.com" \
  --set sandboxIngress.host="sandboxes.example.com" \
  --set inference.openrouter.token="<openrouter-api-key>" \
  --wait --timeout 10m

That is a complete install. Everything below explains what those values do and what to change for production. The provider on the last line is the shortest one to start with; four others can replace it or join it.

Want to try it first?

The Quickstart (VM) walks the same install on one disposable cloud VM, on a public HTTPS address, with a first agent at the end. Come back here when you install for production. (To run it on your own machine instead, see On your laptop.)


Prerequisites#

Requirement Detail
Kubernetes A cluster you can install into, with a default storage class for the bundled database and sandbox volumes.
Helm v3.14 or later, for OCI charts and --reset-then-reuse-values.
Node kernel with nf_tables Sandboxes lock their network down with nftables. A node whose kernel lacks nf_tables runs the platform but fails every sandbox.
Outbound network access To pull images from GHCR, and to Lens Cloud for Lens ID sign-in.
A way to sign in Your own OIDC identity provider, or a Lens ID. Sign up for a Lens ID at app.k8slens.dev. See Activation and license.
An inference provider credential AWS Bedrock, Microsoft Foundry, OpenAI, an OpenRouter API key, or your own LiteLLM proxy. See Inference providers.

Managed cloud Kubernetes (EKS, AKS, GKE) and self-managed distributions carry nf_tables in their node kernels. Local clusters that run the node as a container on your host kernel — kind, Docker Desktop Kubernetes, minikube --driver=docker — also work. minikube's VM drivers ship an ISO kernel built without nf_tables and cannot run sandboxes.


Required values#

Three values are required, and one more decides whether agents can answer at all. The rest have workable defaults.

encryption.key#

A 64-character hex key used to encrypt secrets at rest — credentials, connector tokens, AWS keys. Generate one with openssl rand -hex 32.

Losing this key makes every stored secret unreadable. Store it the way you store any other root secret, and prefer handing the platform a Kubernetes Secret over passing the key on the command line:

kubectl create secret generic lens-agents-encryption \
  --from-literal=encryptionKey="$(openssl rand -hex 32)"

helm install lens-agents oci://ghcr.io/lensapp/lens-agents \
  --set encryption.existingSecret=lens-agents-encryption \
  --set config.publicUrl="https://agents.example.com"

encryption.existingSecretKey names the key inside that Secret and defaults to encryptionKey.

config.publicUrl#

The URL the platform answers on. It is not cosmetic — the platform builds OAuth redirect URLs and sandbox ingress URLs from it. Set it to the address users and agents will actually reach, including the scheme.

sandboxIngress.host#

The wildcard DNS parent for sandbox exposed ports. A sandbox that publishes a port becomes reachable at <slug>.<sandboxIngress.host>, so *.sandboxes.example.com must resolve to your ingress.

Leave it empty and sandboxes still run, but exposed ports resolve to no URL.

An inference provider#

Agents reach their model through the platform's managed inference proxy, which is what makes spending limits, PII masking, and per-call audit possible. An install with no provider configured comes up healthy and runs sandboxes, but no agent in it answers.

Configure at least one. The quickest route is an install-level token, which every organization can use unless inference.deploymentKeyFallback is false:

Provider Minimum values What it serves
OpenRouter inference.openrouter.token Roughly 400 models from around 60 vendors, on either wire format. No cloud account, IAM role, or region to decide first.
AWS Bedrock inference.bedrock.token, or nothing at all where the platform's service account assumes an IAM role Claude. A token also exposes Bedrock Mantle, which serves Claude and GPT off the same key.
Microsoft Foundry inference.azure.baseUrl and inference.azure.token Claude and GPT from one resource and key.
OpenAI inference.openai.token GPT. inference.openai.baseUrl points the backend at any OpenAI-compatible endpoint instead.
LiteLLM inference.litellm.baseUrl and inference.litellm.token The models your own LiteLLM proxy routes, on either wire format.

Every provider also accepts its token from a Kubernetes Secret, which is what to do outside a first install:

kubectl create secret generic lens-agents-openrouter \
  --from-literal=NEXUS_OPENROUTER_TOKEN="<openrouter-api-key>"

helm upgrade lens-agents oci://ghcr.io/lensapp/lens-agents \
  --reset-then-reuse-values \
  --set inference.openrouter.existingSecret=lens-agents-openrouter

--reset-then-reuse-values is what keeps the values you already set, and it also takes the chart default for any value your release does not have yet, such as a value a newer chart adds. Without it, Helm resets every value this command does not name back to the chart default, encryption.key included. Do not use --reuse-values: it skips the new defaults, so an upgrade to a chart that adds a value can fail.

Providers are independent of each other. Set the values for any combination in one install, or add a provider later with a helm upgrade --reset-then-reuse-values that names its values, as above. The platform reads them at startup, so the upgrade restarts its pod.

Install-level tokens are optional. Helm owns the endpoints: Bedrock, Bedrock Mantle, OpenAI, and OpenRouter are always served, and Microsoft Foundry and LiteLLM once their baseUrl is set. A served backend with no install-level token can be used only by an organization whose org admin has added its own key on the Inference Keys page. Native Bedrock is the exception: with no token, it uses the platform's AWS credentials, unless inference.deploymentKeyFallback is false. See Per-organization keys.

Configuring a provider makes it available. A policy has to enable managed inference and name that provider before any sandbox can use it. Inference providers covers all six backends, which variables each one sets in a sandbox, and why a sandbox allowed to dial a provider host directly is metered by nothing.

config.ownerEmails#

Not required, and worth setting before anyone signs in.

Value Default Purpose
config.ownerEmails [] The people who run this installation, by email. Empty names no owners, which leaves organization creation open to anyone who can sign in.
--set 'config.ownerEmails={ops@acme.com,admin@acme.com}'

Name owners and only they may create organizations; everyone else joins one by invitation, and a signed-in person with no organization, no invitation, and no right to create one is refused rather than given an account. Behind a corporate identity provider that is the difference between your platform team having accounts and your whole company having them. See Installation owners for the admission rules and the IdP claim it depends on.


Database#

The chart bundles PostgreSQL 17 and enables it by default. That is fine for evaluation and small installs, but the bundled instance ships with a default password and a single 8Gi volume.

For production, point the platform at a database you operate:

kubectl create secret generic lens-agents-db \
  --from-literal=DATABASE_URL="postgres://user:pass@db.example.com:5432/lens_agents"

helm upgrade --install lens-agents oci://ghcr.io/lensapp/lens-agents \
  --set postgresql.enabled=false \
  --set externalDatabase.existingSecret=lens-agents-db \
  ...

To keep the bundled database but harden it, set postgresql.auth.password, size postgresql.persistence.size, and name a postgresql.persistence.storageClass that your cluster backs up.


Ingress#

The platform listens on port 3002 behind a ClusterIP service. Expose it with the chart's ingress, a Gateway API HTTPRoute, or your own resource in front of the service.

--set ingress.enabled=true \
--set ingress.className=nginx \
--set ingress.hosts[0].host=agents.example.com \
--set ingress.tls[0].secretName=lens-agents-tls \
--set ingress.tls[0].hosts[0]=agents.example.com

Set httpRoute.enabled=true with httpRoute.parentRefs instead if you run Gateway API.

Sandbox exposed ports need a second, wildcard route for *.<sandboxIngress.host> pointing at the same service. The platform resolves the sandbox from the subdomain and enforces the port's auth mode before proxying.

Value Default Purpose
config.maxHeaderBytes 32768 The largest request header block the platform accepts, from 16384 to 1048576 bytes. A value outside that range stops the server from starting.

A browser WebSocket carries its access token in Sec-WebSocket-Protocol, so headers outgrow Node's default of 16384 bytes. Raise the matching limit on an ingress controller in front to the same size, such as large-client-header-buffers on ingress-nginx.

The platform holds long-lived WebSocket connections

Sandbox tunnels, exec sessions, and the admin UI all use WebSockets. Configure your ingress with generous read and send timeouts, or exec sessions drop mid-command.


Event webhooks#

The platform can POST signed events to receivers you name: access.revoked within seconds of a person losing access to projects, spending_limit.threshold when an organization's spend nears or reaches an org-level spending limit, and sandbox.deleted when a sandbox is deleted. Every receiver gets every type, so a receiver answers 2xx to a type it does not handle. Webhooks are off while eventWebhooks.urls is empty.

kubectl create secret generic lens-agents-event-webhooks \
  --from-literal=secret="$(openssl rand -hex 32)"

helm upgrade lens-agents oci://ghcr.io/lensapp/lens-agents \
  --reset-then-reuse-values \
  --set 'eventWebhooks.urls={https://receiver.example.com/events}' \
  --set eventWebhooks.existingSecret=lens-agents-event-webhooks \
  --set eventWebhooks.existingSecretKey=secret
Value Default Purpose
eventWebhooks.urls [] Receivers: https, or http only to loopback or an in-cluster name (a single-label name, *.svc, or *.svc.cluster.local). No credentials or fragment in a URL, and each URL once.
eventWebhooks.secret (empty) HMAC-SHA256 signing key, at least 32 bytes. Required with urls. The chart stores it in the Secret <release>-event-webhooks.
eventWebhooks.existingSecret (empty) Secret holding the key instead of secret.
eventWebhooks.existingSecretKey EVENT_WEBHOOK_SECRET Key in that Secret.
eventWebhooks.timeoutMs 5000 How long one delivery attempt may take, in milliseconds, up to 30000.

The install fails when urls is set without a key. The server refuses to start on a URL it would not send to, a key shorter than 32 bytes, or a timeout above 30000.

Event types#

Each event is a JSON body. id, type, and occurredAt are on every event; the other fields depend on the type. Do not rely on the order of the fields.

access.revoked#

Sent when a person loses access to projects: removed from a project while not an org admin, removed from the organization, demoted from org admin, or the project or organization deleted. A role change that keeps access sends nothing, and so does a change to an API token.

{
  "id": "<event-uuid>",
  "type": "access.revoked",
  "occurredAt": "2026-10-15T09:14:22.000Z",
  "userSub": "<the person's OIDC subject>",
  "projectIds": ["<project-uuid>"]
}

One event names at most 1,000 projects; a larger loss is split into several events, each with its own ID. A retried event can arrive up to 24 hours late, after the person got access again, so remove only state created before occurredAt.

spending_limit.threshold#

Sent when an organization's spend reaches 80% or 100% of an org-level limit. Limits on a project, sandbox, agent, or user send nothing. Spend is checked about once a minute. Each threshold is sent once for each limit, period, and limit amount, and spend that passes 100% at once sends only 100. A new period, or a changed amount, sends them again.

{
  "id": "<event-uuid>",
  "type": "spending_limit.threshold",
  "occurredAt": "2026-10-28T16:02:00.000Z",
  "orgId": "<org-uuid>",
  "limitId": "<limit-uuid>",
  "period": "month",
  "threshold": 80,
  "limitCents": 500000,
  "spendCents": 401250,
  "periodStart": "2026-10-01T00:00:00.000Z",
  "periodEnd": "2026-11-01T00:00:00.000Z"
}

period is day, week, or month, threshold is 80 or 100, and periodEnd is when spend counts from zero again, also for a limit with a period anchor.

sandbox.deleted#

Sent when a sandbox is deleted, by a person or by the auto-delete timer, so a service that keeps state for a sandbox can remove it.

{
  "id": "<event-uuid>",
  "type": "sandbox.deleted",
  "occurredAt": "2026-11-09T12:00:00.000Z",
  "orgId": "<org-uuid>",
  "projectId": "<project-uuid>",
  "sandboxId": "<sandbox-uuid>"
}

The event confirms that the deletion was requested and the sandbox's record removed, not that its pod has stopped: the agent can still run for a short time after it. A delete that fails leaves the sandbox in error and sends nothing until a later delete succeeds. A project or organization cannot be deleted while it has sandboxes, so each sandbox sends its own event first. A sandbox ID is never used again, so a receiver can remove all it holds for sandboxId whenever the event arrives.

Signing and delivery#

X-Lens-Agents-Event-Id carries the event ID, and X-Lens-Agents-Signature carries t=<unix seconds>,v1=<hex>, where v1 is the HMAC-SHA256 of <t>.<raw body> under the key. t is new on each attempt. Check the signature over the raw body, and refuse a t more than five minutes off. Answer a bad signature or a stale t with 401, never 400: a 401 is retried, so a rotated key or a drifting clock loses no event.

Delivery is at least once, so deduplicate on the event ID. A receiver answers 2xx to accept. 400, 410, 413, and 422 drop the event; any other answer, a timeout, or a redirect, which is never followed, is retried after 10 seconds, doubling up to 10 minutes, for 24 hours. An event for a URL that is no longer in urls is dropped too. A dropped event is logged and counted in telemetry.

Upgrading from access webhooks#

Event webhooks were access webhooks before 0.35.0, and nothing is kept under the old names:

  • Values. Rename accessWebhooks to eventWebhooks; the keys are the same. The chart refuses to render while accessWebhooks is set.
  • Environment. ACCESS_WEBHOOK_URLS, ACCESS_WEBHOOK_SECRET, and ACCESS_WEBHOOK_TIMEOUT_MS are now EVENT_WEBHOOK_*. The server refuses to start while any old name is set, and names the one to use.
  • Secret. The chart's own Secret is now <release>-event-webhooks. With existingSecret, rename the key in your Secret to EVENT_WEBHOOK_SECRET or set existingSecretKey to the old one.
  • Receivers. Answer 2xx to types a receiver does not handle. access.revoked arrives as before, with the same headers and signature.

Events not yet sent are sent after the upgrade. During the rolling update, a change that revokes access and reaches a pod of the old version fails and can be made again. Rolling back to an earlier version needs the database migration rolled back too.


Sandbox runtime#

sandbox.provisioner and sandbox.k8s control how sandboxes are scheduled. sandbox.toolsCache controls how sandbox tools are downloaded.

Value Default Purpose
sandbox.provisioner kubernetes What each sandbox runs as: a pod, or an agent-sandbox Sandbox object. See Running sandboxes as agent-sandbox objects.
sandbox.k8s.cpu 500m Ceiling for a sandbox's CPU limit. A sandbox spec asking for more is rejected.
sandbox.k8s.memory 2Gi Ceiling for a sandbox's memory.
sandbox.k8s.cpuRequestRatio "1" Share of a sandbox's CPU limit that its pod requests, above 0 and at most 1, with up to six decimal places. Below 1, more sandboxes fit on a node and each can still use up to its limit; contention only throttles. Applies to pods created after the change.
sandbox.k8s.memoryRequestRatio "1" Share of a sandbox's memory limit that its pod requests, in the same range. A pod using more memory than it reserved is evicted first, which stops the sandbox, so lower it with care. Kata sizes its VM from the limit either way.
sandbox.k8s.runtimeClassName (empty) Runtime class for sandbox pods. Set it to a Kata Containers or gVisor class for per-sandbox microVM or user-space kernel isolation.
sandbox.k8s.agentVolumeStorageClass (cluster default) Storage class for persistent agent volumes.
sandbox.k8s.agentVolumeSize (empty: 10Gi) Size of a sandbox's persistent volume when its spec names none.
sandbox.k8s.disk (empty: agentVolumeSize) Ceiling for the volume size one sandbox may ask for. A larger request is rejected. Empty caps requests at the default size. The platform refuses to start when agentVolumeSize is above the ceiling, so raise both together.
sandboxNamespace.name <release>-sandbox Namespace sandboxes are created in.
sandbox.toolsCache.enabled true Send tool downloads through a shared HTTPS cache that allows only known download hosts. While the cache is not ready, a sandbox with tools does not start. false lets each sandbox download its tools directly, from any host.
sandbox.toolsCache.disk 20Gi Size of the cache's volume, on sandbox.k8s.agentVolumeStorageClass.
sandbox.toolsCache.extraHosts [] Download hosts to allow on top of the built-in ones. *.example.com matches subdomains.

Raise sandbox.k8s.cpu and sandbox.k8s.memory before running agents that build software or hold large working sets — the ceilings apply to every sandbox in the install.

sandbox.k8s.runtimeClassName is the single highest-value hardening step. Without it, sandboxes get privilege dropping, kernel-level network lockdown, and proxy-mediated egress, but share the node kernel. With a Kata runtime class, each sandbox gets its own kernel. See Sandbox isolation.

Running sandboxes as agent-sandbox objects#

sandbox.provisioner chooses what the platform creates for each sandbox.

Value Each sandbox is
kubernetes (default) One pod, which the platform creates and deletes itself.
kubernetes-agent-sandbox One kubernetes-sigs/agent-sandbox Sandbox object (agents.x-k8s.io/v1beta1). The agent-sandbox controller owns the pod.

The chart does not install the controller. Install it before you set the value, at the version this target was verified against:

kubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/v1.0.3/sandbox.yaml

helm upgrade lens-agents oci://ghcr.io/lensapp/lens-agents \
  --reset-then-reuse-values \
  --set sandbox.provisioner=kubernetes-agent-sandbox

The chart adds the RBAC rule the platform needs on sandboxes in agents.x-k8s.io. A stopped sandbox stays as a suspended Sandbox object you can inspect:

kubectl get sandboxes -n <sandbox-namespace>

Storage is unchanged on either target: the platform keeps its own volume claim per sandbox, so a stop, a restart, or a new revision keeps the data.

Stop every running sandbox before you change sandbox.provisioner

Both targets name the pod after the sandbox, so an object left by the other target blocks the new one. Moving back from kubernetes-agent-sandbox to kubernetes, also delete the suspended objects, because the controller keeps ownership of any pod with that name:

kubectl delete sandboxes -n <sandbox-namespace> --all

Verify the install#

kubectl rollout status deploy/lens-agents --timeout=5m
kubectl get pods
curl -fsS https://agents.example.com/health

/health answers {"status":"ok","version":"0.36.0"}, with the platform version, while the server can reach its database.

The platform serves three surfaces once it is up:

Surface Path Used by
Admin UI / Platform administrators
REST API /v1 nexusctl, scripts, CI
MCP endpoint /mcp Desktop AI tools and external agents
CLI installer /install.sh Anyone installing nexusctl

The OpenAPI document for the running version is served at /v1/openapi.json.

The installer and the binaries it downloads are unauthenticated by necessity — you hold no credentials until the CLI that obtains them exists. They serve a build matching this platform's version, so an air-gapped install needs no package registry.

A fresh install shows the Activate screen instead of a login until it is activated. Continue to Activation and license.


Upgrade#

helm upgrade lens-agents oci://ghcr.io/lensapp/lens-agents --reset-then-reuse-values --wait

Database migrations run at startup. Sandboxes keep running across a platform upgrade; they reconnect to the new server process when it is ready.


Sizing a production cluster, air-gapped installs, and hardened runtime classes are worth a conversation. Talk to us.