SYS.DOCS // DOCS

Codex Environments

The Codex Agent creates isolated, repository-backed Codex environments in your own cluster. Each environment clones one GitHub repository into a persistent workspace, runs the Codex runtime in its own pod, and exposes a TLS endpoint you attach to from the Codex CLI on your machine.

Unlike Hermes or OpenClaw, the Codex Agent has no long-running workload of its own: it holds the subscription credential and isolation policy, and you create environments on demand.

Requirements

Add a TLS-enabled wildcard domain on an Envoy Gateway traffic class under the cluster’s Domains. Edka creates environment endpoints under this domain. We recommend a private Gateway that clients reach through Tailscale or Cloudflare WARP.
Connect the GitHub integration and give it access to the repositories you want to use. Edka’s GitHub App requests the Contents and Pull requests permissions it needs; you approve them when you install or update the App.
Use a ChatGPT subscription or a project-scoped OpenAI API key (sk-proj-…) with access to the model you select.
Install a local Codex CLI with --remote and --remote-auth-token-env support. Run codex --help to verify that both flags are available.

Choose a private environment domain

The Codex Agent lists TLS-enabled wildcard domains that use an Envoy Gateway traffic class. For private access, choose one of these paths:

Tailscale: Add the wildcard domain to a Tailscale tailnet (BYOD) Gateway class. Tailnet clients can then reach the environment endpoints.
Cloudflare Zero Trust: Add a DNS-validated wildcard domain to a MetalLB private VIP Gateway class. Install the Cloudflare connector so WARP clients can reach the environment endpoints.

The Cloudflare connector routes the cluster’s private subnet. The Domains flow still manages the hostname and TLS certificate.

See Tailscale Tailnet Traffic Exposure and Cloudflare Zero Trust Private Access for setup steps.

Deploy the Codex Agent

Open a cluster, then go to Workloads → Agents.
Select Deploy Agent and choose Codex Agent.
Pick the Environment Domain: the wildcard domain for environment endpoints.
Under Configuration, choose a sign-in method.
Set the Default Model if needed.
Submit and watch the agent card for progress.

Authentication modes

ChatGPT Subscription keeps the subscription credential out of environment workspaces. Select Sign in with ChatGPT, then complete OpenAI’s device flow in the new tab with the one-time code. Edka keeps the resulting credential out of the browser client and writes it only to a Kubernetes Secret in your cluster. The credential proxy gives running environments short-lived access. Complete the deployment within 15 minutes of signing in, or paste ~/.codex/auth.json into the fallback field. You can also sign in or switch the connected ChatGPT account after deployment from the agent detail page.

OpenAI Project API Key uses standard API billing. Edka accepts project-scoped keys (sk-proj-…) so you can use a dedicated OpenAI project with its own budget and model access. Edka writes the key only to a Kubernetes Secret in your cluster and mounts it only in the codex-proxy sidecar. The repository clone and Codex workspace containers cannot read it. Change the key in the agent settings to restart environments with the new value.

Create an environment

Open the Codex agent card and go to the Environments tab.
Select New Environment.
Pick a GitHub repository and branch.
Optionally set a name (lowercase DNS label), a resource preset, a storage class for the workspace volume, and an auto-delete TTL.
Create the environment and follow the provisioning progress bar.

Resource presets set the CPU and memory limits of the workspace, from 1 CPU / 1 GiB (small) up to 8 CPU / 8 GiB (xlarge). Auto-delete removes the environment after the selected number of hours. Use it for one-off reviews or tests.

Each environment gets its own endpoint under the environment domain, a persistent workspace volume with the cloned repository, and a GitHub token scoped to the selected repository that Edka rotates automatically.

Attach from your terminal

Open the environment while it is running.
Select Reveal Connection and verify with your passkey.
Copy the attach command, which exports a short-lived connection token and runs:

codex --dangerously-bypass-approvals-and-sandbox --remote wss://<environment-endpoint> --remote-auth-token-env EDKA_CODEX_TOKEN

Codex runs commands with full access inside the isolated environment pod, not on your computer. Connection tokens expire quickly. Create a new one whenever you reconnect. Edka never stores these tokens.

Environment lifecycle

The environment list shows status, repository, endpoint, and age. The detail view adds live CPU and memory usage, pod links (Open Pod, View Logs), and workspace facts.
Provisioning shows a live progress bar; a page reload keeps the current stage.
If the agent’s defaults change after you create an environment, the environment keeps its Codex version and model. Edka marks it as drifted. Recreate it to use the new defaults.
Delete Environment removes the pod, workspace volume, route, and runtime credentials. Deleting it discards any work you have not pushed.
Delete all environments before you uninstall the Codex Agent.

Access and safety

Edka stores and rotates the ChatGPT subscription credential only in a Kubernetes Secret in your cluster. The repository clone and Codex workspace containers never see it. The credential proxy uses short-lived access tokens instead.
Edka stores OpenAI Project API keys only in a Kubernetes Secret in your cluster and mounts them only in the credential-proxy sidecar. The repository clone and Codex workspace containers cannot read them. Use a dedicated project with a budget and change the key from the agent settings if it leaks.
Edka asks for step-up verification before it reveals a connection. Each token works for one environment.
Edka scopes the GitHub token to the environment’s repository with Contents and Pull requests write access.
The network policy, on by default, accepts inbound traffic only from Envoy Gateway. Outbound, the environment can resolve DNS and reach public HTTP or HTTPS addresses; cluster services, other pods, node metadata endpoints, and private network ranges are unreachable. Change it under Settings → Security.
Edka requires cluster write access to create, connect to, or delete an environment. Archived clusters block these actions.