Skip to content

How Lens Agents works#

Lens Agents is a control plane you install into your own Kubernetes cluster, plus a sandbox runtime it schedules onto that cluster. Nothing about an agent's work leaves your infrastructure unless a policy you wrote says it may.

Architecture#

graph TB
    subgraph cluster [Your Kubernetes cluster]
        subgraph platform [Platform server]
            api[REST API · MCP · Admin UI]
            policy[Policy engine]
            audit[Audit writer]
            llm[LLM proxy]
        end
        db[(PostgreSQL)]
        subgraph ns [Sandbox namespace]
            sb[Sandbox pod<br><i>supervisor · agent · egress proxy</i>]
        end
        api --- db
        api --> sb
    end

    clients[MCP clients · nexusctl · CI] --> api
    sb -->|governed egress| upstream[Your systems<br><i>Kubernetes · AWS · APIs · MCP servers</i>]
    llm --> models[Model providers<br><i>Bedrock · Foundry</i>]

Platform server#

One deployment, serving four surfaces on port 3002:

Surface Path Who uses it
Admin UI / Administrators
REST API /v1 nexusctl, CI, scripts
MCP endpoint /mcp AI tools and agents
Sandbox ingress *.<sandboxIngress.host> People reaching an agent's exposed port

It holds the identity model, resolves policies, writes the audit trail, provisions sandboxes, and proxies model calls. All four surfaces go through the same authentication, the same policy resolution, and the same audit writer — there is no side door.

Sandbox pods#

Each sandbox is a pod in a dedicated namespace, running three things:

  • The agent, as an unprivileged user, from whatever image you gave it.
  • A supervisor, which starts the agent, reports health, and services exec sessions.
  • An egress proxy, running as root, which owns the pod's nftables rules and terminates every outbound connection the agent makes.

The privilege split is the point: the component that enforces policy has privileges, and the component that is untrusted does not.

PostgreSQL#

Configuration, identity, policies, credentials, and the audit trail. Secrets are encrypted at rest with the install's encryption.key. The chart bundles an instance; point it at your own for production.

Cluster relay#

Clusters that agents should reach but the platform cannot dial — behind a firewall, in another network, on-prem — run a small relay that opens a reverse tunnel to the platform. No inbound ports, no VPN. See Kubernetes.

Request flow#

Follow one call — an agent asking GitHub for a pull request.

sequenceDiagram
    participant A as Agent
    participant P as Egress proxy
    participant N as Platform server
    participant U as api.github.com

    A->>P: GET /repos/acme/api/pulls (placeholder token)
    P->>P: Match domain against effective policy
    P->>N: Fetch credential for this domain
    N->>N: Check RBAC, resolve credential
    N-->>P: Real secret
    P->>P: Substitute into Authorization header
    P->>U: GET /repos/acme/api/pulls (real token)
    U-->>P: 200
    P->>N: Write audit event
    P-->>A: 200

Four things happened that the agent could not have influenced:

  1. The destination was checked. nftables gives the agent exactly one reachable address — the proxy. Anything the policy does not allow is refused, including DNS lookups for denied names.
  2. The credential was injected outside the agent. The agent's environment held a placeholder. The real secret was substituted at the network boundary and never existed in the agent's memory or filesystem.
  3. The request was inspected at HTTP level. Policies match on method and path, not hostname alone, so read-only access to an API is expressible.
  4. The event was recorded with actor, project, destination, result, and duration.

Model calls take the same shape through the LLM proxy, which additionally meters spend against limits and can mask PII before the prompt leaves your network.

Where agents can run#

The governance contract is the same in all three cases. What differs is where the agent's process lives.

Runs in a sandbox Connects over MCP Managed agent
Agent process In your cluster Wherever it already runs In your cluster
You supply An image An MCP client Configuration
Typical Autonomous agents, batch jobs, long-running workers Claude Code, Cursor, Claude Desktop, custom agents, CI Lens Prism
Start at Sandboxes MCP endpoint Managed agents

An agent connecting over MCP does not run unguarded: it gets a sandboxed toolbox in your cluster, and its work happens there under the same policy and audit as everything else.

Defense in depth#

No single control is load-bearing.

Layer Control
Identity Every actor — user, API token, sandbox — is a distinct principal with its own bindings.
Authorization Org, team, and project RBAC decide what a principal can see and change.
Policy Default-deny network, per-domain method and path rules, tool allowlists, managed-inference opt-in.
Isolation Unprivileged process, nftables lockdown, proxy-mediated egress, optional per-sandbox microVM.
Credentials Injected at the boundary, never present in the sandbox.
Spend Per-org, per-user, per-agent, and per-sandbox budget caps.
Audit Every API call, tool call, command, and proxy decision recorded — allowed and denied alike.

An agent that is compromised, jailbroken, or wrong is contained by the layers underneath it, none of which it can talk its way past.