Kubeconfig management

Kubeconfig management

Sextant can tidy up your kubeconfig for you: rename a context, set its default namespace, duplicate it for another namespace, delete it, and merge several files into one. It also tells you when a client certificate or token is about to expire, and checks a kubeconfig before you add it.

Your kubeconfig is shared with kubectl, Helm, cloud CLIs and your IDE, so Sextant does not change ~/.kube/config or any other file of yours until you allow it, and every change is shown to you before it is written.

Contents: How Sextant writes your kubeconfig safely · Allow Sextant to edit · Changing a context · Merging files · Credential expiry · Checking a kubeconfig when you add it · Restoring a backup

How Sextant writes your kubeconfig safely

Every change follows the same steps, and none of them can be skipped:

1. Only files it may edit. Sextant's own files (pasted kubeconfigs, cloud clusters, the merged file) are always editable. ~/.kube/config, the files in KUBECONFIG and files you added are editable only after you turn on "Allow Sextant to edit" for that file (off by default). This is enforced by Sextant's backend, not just hidden in the window.
2. A preview first. Preview shows exactly what would change — contexts, clusters and users added, removed, renamed or changed, and the current context — and which file is written. Credentials are never shown (they read <hidden>). The preview also warns when the file has comments (they are not kept) or when quoting and indentation would change.
3. Nothing changed behind your back. Write to the file computes the change again from the file as it is now. If the file changed since the preview (you ran kubectl config use-context, a cloud CLI refreshed a token…), nothing is written: "The file changed after the preview. Look at the change again."
4. A backup every time. Before writing, the file as it is now is copied next to it as <file>.bak-<date>-<time> (UTC, for example config.bak-20261019-101500), readable only by you on Linux and macOS. Sextant keeps the newest five of its own backups of each file and deletes older ones; it never touches any other file in the folder.
5. An atomic write. The new content goes to a temporary file in the same folder, with the original's permissions, and then replaces the file in one step. A crash or a power cut leaves either the old file or the new one, never half a kubeconfig.
6. Links stay links. If ~/.kube/config is a symbolic link (into a dotfiles repository, say), the file it points to is changed and the link stays. Sextant shows you that real path before you allow editing.
7. Unknown fields are kept. Sextant edits the YAML structure, so fields it does not know (extensions, preferences, plugin settings) stay as they were.
8. Credentials never leave the backend. No certificate, key, token or password appears in a preview, an error, a log or a notification, and Sextant never runs an exec plugin (aws, gke-gcloud-auth-plugin, kubelogin…) to look at anything.

AI agents (the MCP server) and extensions cannot change kubeconfig files: only your clicks in the window can.

Allow Sextant to edit

Open Settings → Clusters → Kubeconfig. Each source has a switch:

• Sextant's own file: always editable — pasted, cloud and merged sources.
• Allow Sextant to edit — every other file, off by default. Turning it on asks Allow Sextant to edit this file?, names the file the change is written to (the real file, after symbolic links) and where its backups go, and reminds you that kubectl and cloud CLIs use the file too. Press Allow to confirm.

Turn the switch off at any time. Removing a source forgets the permission: if you add the file again, Sextant asks again.

Changing a context

Right-click a cluster in the rail (or open its menu):

Item	What it does
Rename context…	Gives the context a new name. A name that is taken in the file is refused. If another file in KUBECONFIG names the old context as its current context and Sextant may not edit that file, the preview says so.
Set default namespace…	Sets the context's namespace; leave it empty to remove it.
Duplicate with namespace…	Adds a copy of the context under a new name with another default namespace, next to it in the same file.
Delete context…	Removes the context, and its cluster and user entries when no other context uses them. Deleting the current context leaves no current context: kubectl then uses no cluster until you choose one.

Each opens a dialog: fill it in, press Preview, read the change, then Write to the file. If the file is not editable yet, the dialog says so and offers Open settings.

After a rename or a delete, that cluster is disconnected. A renamed cluster keeps everything Sextant stored for it — display name, colour, icon, agent access rules, saved views, pins and workspace places — under its new name. A deleted one loses them, so a context created later with the same name starts clean.

Merging files

Merge files… (in Settings → Clusters → Kubeconfig) copies the contexts, clusters and users of the files you choose (Add file…, up to 32 files) into Sextant's own kubeconfig file merged.yaml in its data folder (see Settings). The chosen files are not changed.

• A name that is already taken by a different entry gets a suffix (-2, -3); the preview lists each one as "saved as".
• Relative paths in the files (certificates, token files) are made absolute, so the merged entries keep working.
• The merged file appears as a source marked Merged. Removing it deletes merged.yaml; your original files stay.

Merging into ~/.kube/config itself is not offered: merge into Sextant's file, which is always safe to change.

Credential expiry

Sextant reads, without connecting and without running anything, when each context's credentials stop working:

• a client certificate's end date;
• a bearer token's expiry, when the token is a JWT;
• an OIDC id-token's expiry (and whether a refresh token lets kubectl renew it).

For users who log in through a program (an exec plugin such as aws, gke-gcloud-auth-plugin or kubelogin) or another auth provider, the expiry is known only after the program runs, so Sextant just names it.

A cluster whose credentials expire soon or have expired gets a badge on its icon in the rail; hover it for the date. Warn about credentials expiring within (days) in Settings → Clusters → Kubeconfig sets how early (14 by default, 1 to 365). The expiry is read again whenever the cluster list is refreshed and once an hour.

Desktop notifications about it are off by default: tick Credentials under Notify about in Settings → General → Notifications. See Problems and notifications.

Checking a kubeconfig when you add it

When you add a file or paste a kubeconfig (Getting started), Sextant checks it first, offline. If it finds a problem, Kubeconfig check lists it per context:

• not valid YAML (with the line and column), not a kubeconfig, no contexts;
• a current context, cluster or user that is not defined;
• no server address, or one that is not an https:// or http:// URL;
• a certificate authority or client certificate that is not a valid certificate, or a file it names that does not exist;
• a client certificate or token that has expired;
• a login program that is not installed or not in PATH (it is looked up, never run);
• insecure-skip-tls-verify (a warning: the server's certificate is not verified).

Check connection connects to a context once to see whether the cluster answers; nothing connects unless you press it. Then press Add anyway or close the dialog, fix the file and try again. A kubeconfig without problems is added straight away.

Restoring a backup

Backups are plain copies next to the file. To undo a change, close Sextant (or just stop using that cluster), then copy the backup over the file, for example:

cp ~/.kube/config.bak-20261019-101500 ~/.kube/config

Then press Refresh kubeconfig in the cluster rail.