Skip to content

Sandbox Isolation#

Lens Agents runs sandboxed workloads using a shared security harness built on Linux kernel primitives. The harness is the same across deployments; what varies is what runs inside and how the container lifecycle is managed.

Two deployment shapes#

The sandbox ships in two forms that share the same security harness (privilege drop, iptables, proxy, CA, credential injection).

Shell sandbox — a platform-provisioned container that executes tool calls on behalf of an agent running elsewhere. Used in Mode 1. Lens Agents provisions it on demand, injects credentials, and recycles it on idle. The image is predefined by the platform (default: a shared image with common CLI tools pre-installed).

Agent sandbox — a minimal runtime packaged alongside the agent in a custom container image. Used in Mode 2. The operator owns the image, the tooling installed in it, the workspace layout, and the lifecycle. The same security harness still applies — privilege drop, iptables, proxy, credential injection — regardless of what else is in the image.

The isolation layers below apply to both. Where the behavior differs between the two shapes, it's called out.

Four isolation layers#

Layer 1: User privilege dropping#

Agent processes run as an unprivileged sandbox user via setuid/setgid. All supplemental groups are dropped. Once privileges are dropped, the process cannot escalate — there is no return to root.

Layer 2: Kernel-level network isolation#

iptables rules installed per sandbox user:

  • Loopback (lo interface) — allowed
  • Established/related connections — allowed (conntrack module)
  • All other outbound traffic — rejected with icmp-port-unreachable
  • Both IPv4 and IPv6 hardened

The sandbox user can only reach localhost. All external traffic must pass through the local proxy.

Layer 3: Proxy-mediated egress#

A proxy inside the sandbox intercepts all outbound traffic. The proxy runs as root (it manages the iptables rules from Layer 2). The agent runs as the unprivileged sandbox user. This is a deliberate privilege split: the enforcement component needs elevated privileges, but the untrusted component — the agent — never has them.

The proxy enforces:

  • Domain matching — matches destination domain against policy rules (first-match-wins)
  • Actions — platform (route through Lens Agents for credential injection), direct (allow without interception), deny (reject)
  • HTTP-level restrictions — per-domain rules for specific HTTP methods and URL paths
  • Domain allowlisting — with wildcard support
  • TLS interception — via ephemeral per-sandbox CA for credential injection on governed domains
  • Default action: deny — anything not explicitly allowed is blocked

Layer 4: Privilege-dropped workspace#

The agent (or tool-execution subprocess) runs with the unprivileged sandbox user's view of the filesystem — no elevated access to host mounts, no ability to write outside the workspace directory.

Workspace persistence is a deployment decision, not a property of the sandbox binary:

  • Shell sandbox — workspace persists for the session and is cleaned when the platform recycles the container. Agent state that matters — memory, configuration, conversation history — is stored at the platform level, not in the sandbox.
  • Agent sandbox — persistence follows whatever the operator configures (Docker volumes, Kubernetes PVCs, or nothing). The sandbox binary doesn't impose a lifecycle; the embedded container's own runtime does.

Lifecycle and idle shutdown#

Separate from the isolation layers above, platform-managed sandboxes also shut down after 30 minutes of inactivity (configurable). This is operational hygiene, not an isolation control — the layers above already contain the agent; idle shutdown just bounds the exposure window if something does go wrong.

Idle shutdown applies to the shell sandbox and to platform-hosted agent sandboxes. Self-hosted agent sandboxes (embedded in your own image, running without a live platform connection) have no built-in idle shutdown; lifecycle is whatever the operator or container runtime imposes.

Credential injection#

Credentials never exist in the agent's environment. They are resolved at the platform level and injected via the proxy using TLS interception. The proxy generates an ephemeral certificate per sandbox, intercepts outbound HTTPS traffic to governed domains, injects credential headers, and forwards the request — the agent never sees the raw secrets.

For the full credential injection mechanism including Kubernetes JWT handling, AWS STS, and ephemeral CA details, see Credential Injection.

What the sandbox does not include#

The sandbox does not apply syscall filtering (seccomp profiles). Isolation relies on privilege dropping (Layer 1) and kernel-level network isolation (Layer 2). Agents run as unprivileged users with all supplemental groups dropped, and can only reach the local proxy — but they can still invoke any syscall available to an unprivileged user.

For environments requiring syscall-level restrictions, deploy the sandbox inside a MicroVM where the hypervisor provides an additional isolation boundary.

Runtime agnostic#

The sandbox binary uses Linux kernel primitives (iptables, setuid/setgid), not container-specific features. It works in:

  • Docker containers — default deployment for the CLI tool and cloud platform
  • MicroVMs — for environments requiring VM-level isolation (stronger host boundary)
  • Bare metal — any Linux environment where the binary can run

The same isolation layers apply regardless of runtime. The runtime determines the host isolation boundary — a MicroVM provides a stronger boundary than a Docker container — but the agent-level security (network isolation, credential injection, policy enforcement) is identical.

Tooling in the sandbox image#

Shell sandbox image — the default platform image ships with CLI tools for common automation tasks:

aws, kubectl, gh, jq, yq, ripgrep, webfetch, git, curl, make, gcc, mise

Additional tools can be installed at runtime via mise (runtime version manager).

Agent sandbox image — the operator's choice. The agent sandbox runtime is deliberately minimal and is packaged in a custom image alongside the agent and whatever tooling the agent needs. The security harness applies regardless of what else is in the image.

Local vs. platform-managed sandboxes#

Both the shell sandbox and the agent sandbox can be run locally (on the user's machine via the CLI, or self-hosted) or managed by the Lens Agents platform. The sandbox binary and its isolation layers are identical; what differs is the surrounding platform services.

Local sandbox Platform-managed sandbox
Policy enforcement Same Same
Credential injection Same Same
Network isolation Same Same
Audit trail Local only Platform-level (centralized)
Spending controls Not available Available (LLM proxy)
Identity management Locally configured Platform-managed (tokens, SSO)
Host isolation Depends on runtime (Docker, MicroVM) Managed infrastructure

A local sandbox provides the same agent-level security but not the same platform-level features. This is the expected tradeoff for local or self-managed execution.