AI Agents

Unlike generic container runtimes or traditional "AI sandbox" products that primarily focus on filesystem and process isolation, Cordium treats AI agents as first-class infrastructure principals with identities, policies, sessions, scoped infrastructure access, and observable runtime behavior. A Cordium Workspace is not merely an isolated execution environment, but it also has a dedicated Octelium Session identity, policy-controlled access to infrastructure resources, network egress controls and full observability through OpenTelemetry-native auditing. This architecture allows AI agents to access infrastructure such as remote private resources behind NAT, LLM providers, and publicly protected SaaS resources such as SaaS APIs and databases without requiring direct distribution of long-lived and/or over-privileged credentials into the runtime environment.

note

You can use Octelium Agent Skills to teach AI coding agents (e.g. Claude Code, Codex, etc...) how to install and manage Cordium, create Workspace and Template configurations, and manage the underlying Octelium Users, Services and Policies. Simply describe what you want to do, and your agent can prepare the configuration and run the relevant CLIs for you. You can find the installation instructions here or via Ask AI → AI agent skills above.

The Problem with Existing Approaches

Most current AI-agent execution approaches rely on running the agent directly on developer laptops or CI runners, inside generic containers or ephemeral VMs, with infrastructure credentials injected directly into the environment, with broad API tokens or cloud credentials granted to the runtime, or with infrastructure-level isolation but no application-layer identity and authorization.

These approaches share a common failure mode: the runtime environment accumulates credentials in environment variables, shell history, mounted files, git credential stores, cloud SDK configurations, kubeconfigs, SSH keys, CI secrets, or application configuration files. AI agents can unintentionally leak such credentials through logs, generated code, prompts, telemetry, external API calls, or unintended tool invocations, and a prompt-injected agent can be instructed to do so deliberately.

Traditional container isolation does not solve the core access-control problem. A container with a mounted production credential effectively becomes a highly privileged execution environment regardless of how isolated the filesystem or kernel namespace may be. Most existing "AI sandbox" systems also lack a unified identity and policy model for infrastructure access, placing the authorization boundary at the credential itself rather than at the workload identity.

Identity-Based Agent Execution

Every Cordium Workspace receives its own Octelium Session identity. That identity becomes the security principal used for infrastructure access. Instead of distributing credentials into the Workspace, infrastructure access is mediated through Octelium's identity-aware proxies and secretless access architecture, totally out of reach of the Workspace. Inside the Workspace, agents use standard tools and protocols (e.g. curl, psql, ssh, kubectl, or an LLM SDK) without having to possess the upstream credentials used to authenticate against those resources. The Octelium identity-aware proxy, Vigil, injects the appropriate application-layer credentials dynamically based on the agent identity and context. The AI agent is allowed to perform an action because the Workspace identity is authorized to perform it, not because the runtime environment contains static credentials with broad privileges.

This means infrastructure access becomes policy-driven rather than credential-driven. Access scopes can be changed without rotating secrets or rebuilding environments. Different Workspaces running the same Template can receive different access levels based on identity and context. Compromised or misbehaving agents cannot extract credentials that were never present inside the runtime. This model extends naturally to HTTP APIs, LLM and MCP gateways, SSH, Kubernetes APIs, PostgreSQL, MySQL, mTLS-protected services, and any other application-layer protocol supported by Octelium's secretless access.

Here is an example of an Octelium LLM Service that exposes Anthropic's API to the Workspaces while the API key itself is stored as an Octelium Secret in the Cluster (read more about LLM Services here):

kind: Service
metadata:
  name: anthropic
spec:
  mode: LLM
  config:
    upstream:
      url: https://api.anthropic.com
    llm:
      protocol: ANTHROPIC
      auth:
        custom:
          header: x-api-key
          value:
            fromSecret: anthropic-api-key

An agent such as Claude Code running inside any authorized Workspace can now simply use ANTHROPIC_BASE_URL=http://anthropic with a placeholder API key that is never forwarded to Anthropic, while every inference request is authorized, rate-limited, and audited by Octelium (read the full example here). The same applies to databases, Kubernetes clusters, internal HTTP APIs and SSH servers (read more here).

note

You can read more detailed secretless access example guides for Octelium as an API gateway, AI gateway, MCP gateway, SaaS API gateway, and S3 gateway.

Every Workspace is owned by an Octelium User (read more here). AI agents that are driven by automation (e.g. a scheduler, a CI pipeline or an issue tracker webhook) are typically owned by a WORKLOAD User that authenticates to the Cluster via one of the following methods:

Authentication tokens.
OAuth2 client credentials.
Access tokens.
OIDC-based assertions, which can be used for secretless authentication from within GitHub Actions, Kubernetes clusters, cloud providers, etc...

Here is an example of such a WORKLOAD User whose access is restricted to the pg-staging Service of the payments Namespace and to the anthropic LLM Service (read more about Octelium Policies here):

kind: User
metadata:
  name: triage-agent
spec:
  type: WORKLOAD
  groups: ["agents"]
  authorization:
    inlinePolicies:
      - spec:
          rules:
            - effect: ALLOW
              condition:
                any:
                  of:
                    - match: ctx.service.metadata.name == "anthropic.default"
                    - match: ctx.service.metadata.name == "pg-staging.payments"

Such Users authenticate and interact with Cordium via the cordium CLI (read more here) or the SDKs (read more here).

Running Agents in Cordium

Cordium is agent-agnostic. Any agent capable of running inside a Linux environment can run inside a Workspace, including Claude Code, Codex, OpenCode, Gemini CLI, Aider, OpenHands, Goose, custom agents built on the Claude Agent SDK, LangGraph, CrewAI or PydanticAI, and MCP servers. In practice, there are four common patterns:

Pattern	How	Best for
Unattended one-shot runs	An ephemeral, auto-stopping Workspace whose task runs the agent in non-interactive mode (e.g. `claude -p`, `codex exec`) and pushes a branch or opens a pull request. Triggered via `cordium run`, `cordium create workspace --start` or the SDKs.	Fixing bugs, implementing issues, dependency upgrades, migrations, triage.
Interactive sessions	A persistent Workspace in which a developer runs the agent from a browser terminal, `cordium ssh` or VS Code.	Pair-programming with an agent on a long-lived branch.
Programmatic sandboxes	An application uses the SDKs to create a Workspace per task or per user, executes the model-generated code with `Exec`, transfers files, and deletes the Workspace.	Code interpreters, evaluations, agent harnesses and products that execute untrusted code.
Orchestrated agents	An orchestrator (e.g. the Cordium Agent or your own agent) creates, drives and compares several Workspaces in parallel via the `cordium` CLI or the API, without holding any credential.	Fanning a task out to several agents, best-of-N attempts, multi-repository changes.

Here is a short example of an unattended Claude Code run that fixes a GitHub issue in an ephemeral Workspace and stops itself once done (read the complete example with pull request creation and pre-builds here):

cordium create ws --template claude-agent.payments.cordium --ephemeral --start \
  --var TASK="Fix #1842: TestWebhookRetry is flaky because the retry backoff reads the wall clock"

Isolation Model

Agents frequently need to install packages, compile code, run language runtimes, execute test suites, build containers, spawn subprocesses, interact with databases, use package managers, run browsers, or execute arbitrary developer tooling. For this reason, Workspaces intentionally provide what appears to be full root capability from inside the sandbox environment. Internally, however, the Workspace runs as a rootless container with its own user, PID, mount, cgroup and network namespaces inside a restricted supervisor container (read more here).

On top of that, every Workspace can be locked down further depending on how much the agent is trusted:

Egress network rules restrict which networks and ports the agent can reach, with a default-deny posture if needed (read more here).
A read-only root filesystem and dropped Linux capabilities restrict what the agent can modify (read more here).
Octelium Policies restrict, on a per-request and L7-aware basis, which Services, database users, HTTP paths, Kubernetes namespaces or LLM models the agent's Workspace can use, and they can be scoped to the Workspace's Space and Template (read more here).
Resource limits and timeouts cap the CPU, memory, storage and run time of each Workspace (read more here).

Ephemeral and Reproducible Execution

Cordium is designed around reproducible Workspace creation. Templates define the image, repositories, startup tasks, limits, runtime configuration, variables, and initialization logic declaratively. Pre-built Templates are snapshotted and restored within seconds using Kubernetes CSI snapshots. This allows AI-agent workloads to start from deterministic environments with pre-installed dependencies, cached package trees, cloned repositories, language toolchains, and runtime frameworks already prepared ahead of time (read more here).

An ephemeral Workspace run starts from a clean state and is fully destroyed afterward. This prevents state bleed between runs, limits persistence opportunities for compromised agents, and makes execution behavior easier to reason about operationally. Persistent Workspaces remain available for human-assisted development sessions, long-running automation, collaborative debugging, or agents that intentionally maintain local state over time. WorkspaceSnapshots let you checkpoint a Workspace before a risky agent run, roll back afterwards, or fork the same state into several Workspaces for parallel attempts (read more here).

Observability and Auditability

All infrastructure access performed by Workspaces is audited through Octelium's OpenTelemetry-native, application-layer L7-aware visibility. This includes HTTP and gRPC API requests (e.g. request path, method and query parameters), LLM inference requests (e.g. models, tokens and tool calls), database queries, full SSH sessions, Kubernetes API operations, etc...

note

Read in detail about Octelium visibility here.

Because every Workspace has a dedicated Session identity, infrastructure activity can be correlated directly back to the Workspace, the Template, the originating User, the Space, and the specific Session performing the operation. This becomes particularly important for AI-agent workloads where reproducibility, traceability, and post-incident analysis are operationally critical.

Examples

You can read the following examples with complete, ready-to-use configurations:

Claude Code: fix issues and open pull requests unattended.
Codex: implement features with codex exec in pre-built Workspaces.
OpenCode: run OpenCode against any LLM provider.
Secretless LLM access: run agents without any API key inside the Workspace.
Parallel agents: fan a task out to several agents and compare the results.