Using Ergo

Ergo for macOS · requires macOS 15 or later

First launch

On first launch Ergo creates a built-in sample cluster called prod-eks and selects it. It runs entirely inside the app — no network, no credentials, no account — and every feature works against it. It is the fastest way to learn the interface before connecting your own clusters.

Connecting clusters

Kubeconfig files

Choose Settings + Connections and add a connection from your kubeconfig. You can select multiple files and Ergo merges their contexts using the same precedence kubectl applies to KUBECONFIG: the first file to define a context name wins.

Because Ergo runs in the macOS App Sandbox, it remembers each file through a security-scoped bookmark so it keeps working across restarts without needing access to your whole home directory.

EKS, GKE, AKS

Add a cloud-provider connection and sign in through Ergo's built-in browser flow. Ergo discovers your accounts and clusters, then mints cluster tokens itself — no cloud CLI, no exec credential plugin, nothing to install.

Signing out clears the tokens Ergo holds. Use "Use another account" to force the account chooser.

Environments

Ergo guesses an environment tier (production, staging, development) from each cluster's name. Correct it in the connection editor if the guess is wrong. The tier colors the cluster name in the sidebar and enables stricter confirmations for production deletes.

Exploring a cluster

The sidebar lists the resources in the selected namespace. Click a resource to open its detail pane, which shows its current state, events, and dependent relationships. Use the search field to jump to a specific resource by name.

The pipeline view

Ergo's flagship feature. Open any resource and the pipeline view walks ownerRefs, operator heuristics, and the event stream to reconstruct the full chain behind it — then pinpoints where the chain actually broke.

How it works

• Follow the chain. Ergo resolves ownership across cert-manager, Argo, Keda, and any operator that sets ownerRefs — Certificate → Request → Order → Challenge, and so on.
• Pinpoint the break. Correlated events surface the exact resource and moment a rollout, sync, or issuance went sideways, with a plain-language root cause.
• Trace ingress paths. For routing resources, Ergo maps ingress rules down to the pods actually serving the traffic.

The cluster map

Select the map view to see an overview of every resource in the current namespace and how they relate. Colored dots indicate the environment tier, and status highlights surface resources that are not ready. Click a node to open its detail or pipeline view.

Editing resources

Schema forms

For any resource type, Ergo can generate a typed form from its OpenAPI schema. Custom resource definitions (CRDs) become real UI — fields are labelled, validated, and laid out according to the schema's structure — so you never need to edit raw YAML for standard operations.

Manifest editor

Prefer YAML? Switch to the manifest editor for full-control editing. The manifest view keeps the document valid and shows the exact YAML that will be sent to the API server.

Dry run

Before committing any change — form or manifest — Ergo sends it to the API server as a server-side dry run. The returned diff shows exactly what will be applied, including server-side defaults and admission-controller mutations that you can't predict from the YAML alone.

Making changes

Every write operation in Ergo follows the same path: a confirmation dialog, then a commit, then a line in the local audit log.

Confirmations

Before Ergo commits a change, the confirmation dialog spells out the resource, its namespace, and the cluster. On clusters marked production, the dialog is set in red and extra safeguards apply. Read it; the details are the point.

Production deletes

On a cluster marked production, the delete button stays disabled until you type the resource's name. A pod its controller owns will be recreated; an unowned one is gone for good. For anything else, the sheet warns that dependent objects may be garbage-collected.

Scaling

Pick a replica count outside a HorizontalPodAutoscaler's bounds and Ergo names the bound you crossed, its current metric targets, and the fact that the autoscaler will override your number.

Available operations

Ergo Pro unlocks nine write operations: apply manifest, scale, restart, drain, cordon, uncordon, edit taints, evict, and delete. All flow through the same confirmation and audit-log path. Browsing and server-side dry runs are free and available without a subscription.

Audit log

Every committed change writes one line to a plain-JSON audit log on your Mac — one file per day, one line per action. Failures are recorded with their reason, not only the changes that worked. The log lives in the app's container and can be exported from Settings + Diagnostics.

Pod terminal and port forwarding

Open a terminal session into any pod, or forward a port to your local Mac. Sessions are kept alive with keepalives and will reconnect automatically if the connection drops. A clean exit or closing the terminal window will not reconnect.

These features require a recent API server release that supports the Kubernetes WebSocket protocols. Ergo checks your cluster's version first and tells you if a feature gate or newer release is needed.

Local agent (MCP)

Ergo can expose a local MCP endpoint so an AI agent tool can drive the Kubernetes client on your behalf. The endpoint listens on localhost only and accepts connections from your own Mac.

The MCP tools are built on Ergo's read-only cluster interface, which has no mutating methods to call. The agent can browse, describe, and explain — but it cannot change anything. Mutations are a separate interface the agent surface never holds.

Settings

• Connections. Add, remove, and reorder cluster connections.
• iCloud sync. Optionally keep cluster-configuration details in step across your Macs. Off by default. Never syncs credentials.
• Diagnostics. View and export on-device crash and hang data. Ergo keeps the twenty most recent reports locally and never uploads them without your explicit action.
• What's New. Current version and changelog.

Keyboard shortcuts

Use ⌘F to focus the search bar from anywhere. Press ⌘1 through ⌘9 to cycle between recent resources. Open the window menu for the full list.