The system architecture of kubed-sh looks as follows:

kubed-sh system architecture

In a nutshell, kubed-sh uses kubectl to launch and control binaries and scripts for you. It is multi-cluster and context aware and supports some local commands (such as cd, ls, cat) as well as a number of cluster commands, for example ps, kill or curl.

Learn more about:


In this document we’re using terms as follows:


In kubed-sh you can always tell the execution target by looking at the prompt. The general format of the prompt is as follows:


For example:


Above means you’re currently in the example.com environment, using the minikube context with the default namespace.

Here are the rules:

Launching binaries and scripts

kubed-sh follows two simple rules that mimic the behaviour you’re used to from a local shell:

  1. If a launch command via a binary or a script with an interpreted environment (initially: support for Node.js, Python, and Ruby) ends with an &, this causes the creation of a deployment and a service (name equals the name of the binary or script); this is good for any long-running app, effectively executing in the background.
  2. If the launch command doesn’t end in an & then a pod is created; this is good for one-shot batch or interactive apps.

Further, kubed-sh supports environment variables to define and overwrite behavior such as the images used, exposed service port, runtime features like hot-reload, etc.


First and foremost kubed-sh depends on kubectl for all cluster operations. That is, all remote operations in the cluster essentially cause shelling out to kubectl. You can see what kubectl commands kubed-sh executes when you execute the debug built-in command.

To provide the shell interaction we’re using the REPL package chzyer/readline, offering autocomplete, search (CTRL+R) and other standard operations such as CTRL+L for clearing the screen.

kubed-sh is stateless, meaning that any kind of state—such as environment membership, phases or app components—is entirely stored in Kubernetes, using labels and annotations.