SYS.DOCS // DOCS

Agents

Agents are managed AI runtimes and environment providers deployed into an Edka cluster. They are installed from the agent catalog, then managed from a dedicated Agents workspace with runtime health, environments, profiles, endpoints, logs, backups, and runtime-specific actions in one place.

The current managed agent runtimes are:

Runtime	Catalog app	Main capabilities
Codex	Codex Agent	Repository-backed environments, managed auth, remote CLI attach
Hermes	Hermes Agent	Profiles, webhooks, state backups, dashboard access
OpenClaw	OpenClaw	Device approval (browser pairing), control UI access

Open the Agents workspace

Open a cluster, then go to Workloads → Agents.

The Agents page shows one card per installed agent runtime. Each card combines app lifecycle state with live runtime information:

agent name, runtime, version, and namespace
install, update, and uninstall progress
observed runtime health
dashboard URL when external access is configured
CPU, memory, and pod resource usage
profile count and latest state backup when the runtime supports those capabilities

Agents that are still provisioning appear in the same grid, so you can follow a deploy without leaving the page.

Deploy an agent

Open Workloads → Agents for the cluster.
Select Deploy Agent.
Choose an agent runtime.
Complete the configuration form.
Submit the deployment and watch the agent card for progress.

Agent installs use the same reliable deployment pipeline as apps: Edka installs required add-ons, renders Kubernetes resources from the catalog definition, and streams progress back to the UI.

Langfuse tracing

Hermes Agent can send traces to an installed Langfuse instance. Enable Langfuse tracing in the Hermes configuration, select the Langfuse instance in the same cluster, then provide the project public and secret keys generated inside Langfuse.

Edka fills the in-cluster Langfuse base URL from the selected app instance, so the Hermes pod talks to Langfuse over the cluster service instead of a public route.

Agent detail tabs

Open an agent card to manage the runtime. Tabs are capability-gated, so only the surfaces supported by that runtime appear.

Tab	Purpose
Profiles	Manage the default profile and named in-pod profiles. Available when the runtime supports profiles.
Environments	Create and manage repository-backed Codex environments. Available when the runtime supports environments; see Codex Environments.
Overview	Inspect runtime version, observed status, app status, namespace, release, instance, catalog source, and runtime pods.
Endpoints	View and copy public access routes and in-cluster service addresses, including dashboard, API, and webhook URLs the runtime exposes.
Backups	Trigger manual state backups, inspect run progress, and see stored backups. Available when the runtime supports state backups.
Logs	Read runtime logs.
Devices	Approve browser or device pairing requests. Available for runtimes with device approval.
Settings	Edit the agent configuration, grant Kubernetes API access, manage network policy, or uninstall the agent.

For profile-capable runtimes, the detail page opens on Profiles by default. Environment-capable runtimes open on Environments; other runtimes open on Overview.

Profiles

Profiles are named agent workspaces inside one runtime pod. They share the parent agent’s Kubernetes resources and persistent volume, but each profile has its own instructions, memory, and optional webhook route.

Use profiles when you need multiple agent identities on the same runtime. Install another agent when you need dedicated resources or stronger isolation.

To add a profile, open Add Profile, set a profile name, and optionally expose webhooks. Submitting from there creates a blank profile. To start from a backup instead, expand Advanced options and choose a bootstrap mode:

Mode	Behavior
Blank profile	Creates an empty profile that inherits the parent runtime setup. This is the default.
From backup	Restores saved profile state from a previous state backup. Offered only when at least one backup exists.

Profile distributions (SOUL, skills, and cron from a Git repository) are not installed as in-pod profiles. Because that content is untrusted inside the parent agent’s secret-bearing pod, install a distribution as its own dedicated agent deployment instead.

Each profile’s gateway can also be started, stopped, and restarted from the Profiles tab.

Profile names must use lowercase letters, digits, and dashes, and must be at most 30 characters. The name default is reserved for the runtime’s root profile.

Webhooks

When the parent agent has webhooks enabled and a webhook hostname configured, a profile can expose a public webhook route at:

https://<webhook-hostname>/profiles/<profile-name>/webhooks/<route-name>

The default profile uses the parent webhook prefix:

https://<webhook-hostname>/webhooks/<route-name>

Edka can reveal a profile’s webhook signing secret after step-up verification. The secret is read live from the agent pod and is not stored by Edka. You can also send a signed test payload from Edka to validate public webhook delivery end to end.

State backups

State backups export profile state for recovery and profile cloning. For Hermes, enable them in the agent’s Backup configuration tab by selecting an S3 compatible object storage integration and schedule.

Backups include profile state: memories, sessions, skills, SOUL, and config. Credentials and live databases are deliberately excluded from the state export. If the cluster backup age key is configured under Cluster Settings → Backup, credentials are instead written as an encrypted sidecar in your object storage. During restore, paste the age private key only if you want to restore those encrypted credentials; the key is used once and is not stored.

The Backups tab supports:

scheduled backups driven by the in-cluster CronJob
manual Back Up Now runs
run progress for exported, failed, and current profiles
stored backup inventory for the current agent

Restores happen from Add Profile → Advanced options → From backup. The restore picker can include backups from other agents in the organization, filtered by your access to each backup’s source cluster.

Device approval

Some runtimes require browser or device pairing before the control UI can connect. OpenClaw supports device approval, so its agent detail page includes a Devices tab.

To pair a browser with OpenClaw:

Open the OpenClaw dashboard from the agent detail page.
Wait for the OpenClaw Control UI to show that browser pairing is required.
Return to Devices and click Approve.
Retry the OpenClaw Control UI connection.

When you click Approve, Edka asks the running OpenClaw gateway for the newest pending browser request, then approves the concrete request ID returned by OpenClaw. You do not need to copy or paste request IDs from the Control UI.

OpenClaw can replace a pending request when the browser retries with different auth details, scopes, or device identity. If approval reports that no pending request was found, keep the OpenClaw dashboard open until it shows pairing is required, then click Approve again in Edka.

Access and safety

Reading agents requires cluster read access.
Deploying, editing, creating profiles, triggering backups, testing webhooks, approving devices, and uninstalling require cluster write access.
Agents get no Kubernetes API access by default. Scoped RBAC and network policy are granted per agent from Settings → Security; see Agent Kubernetes Access and Network Policy.
Archived clusters block mutating agent actions.
Webhook secret reveal requires step-up verification, as does granting an agent cluster-wide custom RBAC rules.
State backups are stored in your selected object storage integration.
Organization-wide backup restore lists are filtered by source-cluster access.
External dashboards can manage sessions and secrets; expose them only behind a trusted private boundary.