Settings · kubyl.dev

Kubyl has no settings window. App: Open Settings (Ctrl ,, the Kubyl menu or the welcome screen) opens settings.json in your default editor. The one exception is the Clusters & Kubeconfigs tab, which edits per-context and source settings and writes them into the same file.

How the file works

It is live-reloaded. Save the file and the change applies immediately.
Kubyl writes changes atomically and only writes fields that differ from the defaults.
A $schema entry is added to a new file, and settings.schema.json is regenerated on every start. Point your editor at it for completion and validation.
If the file can't be parsed, Kubyl never overwrites it. Your changes stay in memory and a warning is logged.
Secrets never live here. See Authentication.

settings.json

{
  "theme": "system",
  "kubernetes": {
    "health_check_interval": 30
  },
  "keymap": {
    "preset": "k9s"
  },
  "logs": {
    "tail_lines": 500,
    "wrap": true
  }
}

Appearance

Key	Default	Meaning
`theme`	`dark`	`dark`, `light` or `system`. The light theme is still unfinished.
`ui_font_size`	`13`	Interface size in px, 9–24. Changed by zoom.

kubernetes

Key	Default	Meaning
`load_default_kubeconfig`	`true`	Load `~/.kube/config`.
`load_kubeconfig_env`	`true`	Load the files in `$KUBECONFIG`.
`kubeconfigs`	`[]`	Extra files or folders. `~` is expanded.
`health_check_interval`	`30`	Seconds between cluster pings.
`group_contexts`	`true`	One sidebar entry per cluster and user.
`separate_groups`		Contexts to show separately.
`contexts.<id>`		Per cluster: `display_name`, `color`, `default_namespace`, `production`, `read_only`, `hidden`, `namespaces`.

explorer

Key	Default	Meaning
`group_order`		Order of sidebar groups. Ids: `overview`, `events`, `workloads`, `network`, `config`, `storage`, `devices`, `access`, `cluster`, `administration`, `custom`, and the contributed rows `alerts`, `network_flows`, `prometheus`, plus `security` and `cost` (the last two are available in the release after 0.6.0). Groups you leave out follow in their default order.
`hidden_groups`		Groups to hide, by the same ids. `devices` (Device Resources, for DRA) only shows on clusters that serve those kinds.
`show_counts`	`true`	Show object counts next to kinds.
`default_grace_period`	none	Grace period for deletes.
`cluster_order`	`name`	`name` or `connected_first`.

keymap

preset is default or k9s. bindings is a list of entries with a context and a map of keystrokes to actions. Use null to unbind a key, and an array for actions with arguments. Changes apply immediately and mistakes show as a warning toast. See Keyboard shortcuts.

settings.json

{
  "keymap": {
    "bindings": [
      {
        "context": "ResourceList",
        "bindings": {
          "ctrl-k": null,
          "x": ["palette::Open", { "mode": "resources" }]
        }
      }
    ]
  }
}

logs

Key	Default	Meaning
`ring_buffer_lines`	`100000`	Lines kept per log view.
`timestamps`	`true`	Show timestamps.
`wrap`	`false`	Wrap long lines.
`follow`	`true`	Follow new lines.
`tail_lines`	`1000`	Lines to load initially.

terminal

Key	Default	Meaning
`shell_override`	none	Shell to run in containers. Otherwise `/bin/bash`, then `/bin/sh`, then `sh`.
`local_shell`	`$SHELL`, else `%COMSPEC%`, else `/bin/sh`	Shell of local terminal tabs. Available in the release after 0.6.0.
`scrollback_lines`	`10000`	Scrollback size.
`font_size`	`13`	Terminal font size.
`option_as_meta`	`false` on macOS, `true` elsewhere	Treat Option (Alt) as Meta.
`open_in`	`panel`	`panel` or `tab`.
`debug_image`	`busybox:1.37`	Image for debug containers.
`node_shell_image`	`docker.io/tyrola/kubyl-debug:3.24`	Image for node shells.
`node_shell_namespace`	`kube-system`	Namespace for node shell pods.

files

Key	Default	Meaning
`concurrency_per_pod`	`2`	Parallel transfers per pod.
`verify`	`true`	SHA-256 verification on both sides.
`chunk_size_mb`	`4`	Chunk size for large files.
`show_hidden`	`false`	Show hidden files.
`bookmarks`	`[]`	Saved locations.
`debug_image`	`busybox:1.37`	Image for distroless containers.
`preview_limit_kb`	`256`	Largest file to preview.

yaml_editor

Key	Default	Meaning
`validate`	`true`	Validate against the cluster's schema.
`hide_managed_fields`	`true`	Hide `managedFields`.
`confirm_apply_on_prod`	`true`	Ask before applying on production clusters.
`side_by_side_diff`	`false`	Side-by-side instead of unified diffs.

metrics and overview

Key	Default	Meaning
`metrics.source`	`auto`	`auto`, `prometheus`, `metrics_server` or `off`.
`metrics.discover`	`true`	Look for Prometheus automatically.
`metrics.refresh_interval`	`15`	Seconds between refreshes.
`metrics.prometheus`		Per-cluster endpoint: `namespace`, `service`, `port`, `scheme`, `path`, `url`, `service_account`, `insecure_skip_tls_verify`, `disabled`.
`metrics.queries`		PromQL overrides by query id. `$sel` is replaced with label matchers.
`overview.top_n`	`4`	Top-N entries, 1–4.
`overview.derived_events`	`true`	Derive OOMKilled warnings.
`overview.notify_warnings`	`false`	Toasts for Warning events in favorited namespaces.
`overview.notify_interval`	`60`	Seconds between notification checks.
`prometheus.sidebar`	`true`	Show the Prometheus row.
`prometheus.refresh_interval`	`15`	Seconds, 5–3600.

alerts and netflow

See the tables in Alerts and Network flows. The per-cluster blocks are alerts.clusters.<id> (disabled, discover, alertmanagers, matchers, rules) and netflow.clusters.<id> (backend, hubble, whisker, loki).

Key	Default	Meaning
`alerts.sidebar`	`auto`	`auto`, `always` or `never`.
`alerts.ack_duration`	`1h`	Length of an acknowledge silence.
`netflow.sidebar`	`true`	Show the Network Flows row.
`netflow.max_flows`	`20000`	Flows kept in memory.
`netflow.max_age_minutes`	`60`	Oldest flow kept.
`netflow.keep_query_values`	`false`	Keep URL query values in HTTP flows.

argocd, updates, webview

Key	Default	Meaning
`argocd.api_transport`	`auto`	`auto`, `proxy` or `forward`.
`argocd.auto_connect`	`true`	Reconnect API mode automatically.
`updates.clusters.<id>`		`provider` plus `eks`, `gke` or `aks` details.
`webview.open_in`	`auto`	`auto` or `browser`.
`webview.idle_stop_minutes`	`30`	Stop idle background forwards. `0` keeps them.
`webview.devtools`	`false`	Enable developer tools.
`webview.private_by_default`	`false`	Open every view as a private session.

helm, agent and cost

Each of these has its own page with the full tables: Helm, Agents and Cost.

Key	Default	Meaning
`helm.path`	found on `PATH`	The `helm` binary to run.
`helm.artifact_hub`	`false`	Also search Artifact Hub in the Charts tab.
`helm.default_timeout`	`5m0s`	Helm's `--timeout` for installs, upgrades, rollbacks and uninstalls.
`helm.atomic`	`true`	Roll back a failed install or upgrade.
`agent.default`	first installed	Agent for new threads: `claude`, `codex`, `gemini`, `copilot`, `goose`, `opencode` or a custom id.
`agent.custom`	none	Extra ACP agents, or built-ins started differently.
`agent.kubectl`	`none`	`none` or `context`: what `kubectl` in the agent's own shell reaches.
`agent.cwd`	scratch folder per thread	The agent's working folder.
`agent.max_tool_output_kib`	`64`	Most a Kubyl tool returns to the agent, 8–1024 KiB.
`agent.default_log_lines`	`500`	Lines a `logs` tool call returns by default, 10–5000.
`cost.clusters.<id>.service`	detected	Where OpenCost is, as `namespace/service:port` (port defaults to 9003). Available in the release after 0.6.0.

kubeconfig_editor and self_update

Key	Default	Meaning
`kubeconfig_editor.backups_kept`	`10`	Backups per edited kubeconfig.
`kubeconfig_editor.allow_external_edits`	`true`	Offer to edit files Kubyl doesn't own.
`kubeconfig_editor.editable_files`		Files you opted in to editing.
`self_update.auto_check`	`true`	Check for updates every 6 hours.
`self_update.channel`	`stable`	`stable` or `preview`. `preview` currently falls back to stable.

Some state isn't a setting. Window layout, favorites, saved port-forwards, palette history, column choices, sidebar folders, the YAML revision history, reopenable agent thread titles (never their contents) live in state.json, which Kubyl manages itself. See Files and environment.