A shell in a container and a node shell to access the Kubernetes node, from the browser or the desktop. Both are on the Pro and Team plans and only admins can open them (on desktop, from 2.7.0); the node shell asks you to type the node name.
Where
Web and Desktop
Plans
Pro and Team
Role
Admin only (on desktop, from 2.7.0)
What it does
Web, pod: open the pod and pick the container; the terminal opens in the bottom panel, bridged to the Kubernetes exec.
Web, node: on the node, Shell opens a terminal on the node itself after you type the node name to confirm. Admins of Pro or Team organizations only.
Desktop, pod: the Freelens Shell and Attach pod menus.
Desktop, node: in the node menu, Shell opens a terminal on the node itself. Cordon, Uncordon and Drain are in the same menu and stay desktop-only.
Limits and timeouts
Limit
Value
Web: session length (pod or node)
2 hours
Web: sessions per person
3 terminals at once, counting pod shells, node shells and bastions
Web, node: sessions per person and cluster
1
Web, node: wait for the shell pod to start
up to 120 s; then the pod is deleted
Web, node: confirmation
type the node name
Web: size of each terminal message
64 KB
Desktop, node: wait for the shell pod to be Running
up to 2 minutes
What is not accepted
Web: members, the Free plan, or a connection from another site (the origin is checked).
Web, node: a typed name that does not match the node; a second node shell of yours in the same cluster; Windows nodes (use the desktop), Fargate and virtual-kubelet.
Desktop: the Free plan (from 2.4.0 on, the menus show with a lock and an upgrade notice; up to 2.3.0, they are hidden) and, from 2.7.0, Team organization members.
Node shell, on the web and on desktop, when the cluster blocks privileged pods in kube-system: Pod Security Admission, Azure Policy, Gatekeeper or Kyverno. On the web, the error message explains how to allow it on AKS and EKS.
How the node shell works (accessing a Kubernetes node)
Web: Kubepier’s server uses the cluster credential to create an ephemeral kubepier-shell-no-* pod in kube-system, pinned to the chosen node, with the alpine image pinned by digest, privileged and with no service account token. The terminal enters the node with nsenter (on Bottlerocket, through apiclient).
Web: the pod is deleted when the terminal closes, on error, if the connection drops, if it does not start within 120 s or after 2 hours.
Desktop: the app creates a pod in the kube-system namespace, pinned to the chosen node, with privileged, hostPID, hostIPC and hostNetwork, system-node-critical priority and a toleration for any taint.
Desktop: up to 2.6.0, the default image is docker.io/library/alpine, with no time limit for the pod; from 2.7.0, alpine:3.24.2 pinned by digest, the pod lasts at most 2 hours and gets no ServiceAccount token, and opening it asks for the typed node name (admins only). On Windows nodes, mcr.microsoft.com/powershell. You can change the image and set an imagePullSecret in the cluster settings.
Desktop: the terminal attaches to the pod with kubectl attach. On close, the pod is deleted.
Web, pod: every session opened goes to the organization audit log, with who, when, cluster, pod, container and whether it opened.
Web, node: "Opened node shell" and "Closed node shell", with who, when, cluster, node, pod and duration.
Desktop: every pod and node shell session goes to the kubepier-audit.log file, in the app data folder, on open and on close, with who, when, cluster, target and duration. Up to 2.6.0, local terminals (on your machine) are not recorded; from 2.7.0, opening and closing the local terminal also go to kubepier-audit.log.
What you type and what the terminal shows is never recorded.
Permissions you need on your side
Feature
Kubernetes permission (RBAC)
Pod shell (web and desktop)
create on pods/exec (and get on the pod)
Attach (desktop)
create on pods/attach
Node shell (web)
create and delete on pods and create on pods/exec in kube-system; get on nodes; admission that accepts a privileged pod in kube-system
Node shell (desktop)
create, get, list, watch and delete on pods in kube-system; create on pods/attach in kube-system; admission that accepts a privileged pod with hostPID, hostIPC and hostNetwork in kube-system
Cordon and Uncordon (desktop)
patch on nodes
Drain (desktop)
patch on nodes, list on pods and create on pods/eviction
Common errors
"Too Many Requests" when opening the web shell: you already have 3 terminals open, or already have a node shell in that cluster.
Node shell rejected by admission (PodSecurity, Azure Policy, Gatekeeper, Kyverno): the cluster blocks privileged pods in kube-system. Follow the message to allow it on AKS or EKS, or use another way into the node.
Node shell on a Windows, Fargate or virtual-kubelet node: not accepted on the web; for Windows, use the desktop.
"Pod creation timed out" on the node shell (desktop): the pod was not Running within 2 minutes: check that the node can pull the image and that admission accepts a privileged pod.
403: the credential lacks the verb in the table above.