Terminal & Shell

Kunobi includes a fully integrated terminal panel that lets you run shell commands, exec into running containers, stream logs, forward ports from pods, and access node shells — all without leaving the application.

Opening the Terminal

The terminal panel slides up from the bottom of the window, inspired by the VSCode integrated terminal. There are three ways to open it:

• Keyboard shortcut — Press ⌘J (macOS) or Ctrl+J (Windows/Linux) to toggle the panel.
• Sidebar icon — Click the Terminal icon (>_) in the vertical navigation bar.
• Auto-open — Configure the terminal to open automatically when you switch to certain pages. See Terminal Auto-Open in Settings.

Once open, drag the top edge of the panel to resize its height.

The terminal panel has two top-level tabs:

• Terminals — Shell sessions, log viewers, and port forwards.
• AI — AI conversations (see AI & MCP).

Terminal Sessions & Tabs

Each terminal session appears as a tab inside the terminal panel. You can run multiple sessions simultaneously — local shells, pod execs, node shells, log viewers, and port forwards all live as separate tabs.

Click + in the top-right corner of the terminal area to open a new local session.

Lazy numbering — The first terminal for a given target shows just the name (e.g., my-pod). When you open a second terminal for the same target, both tabs are renumbered (e.g., 1: my-pod, 2: my-pod).

Rename tabs — Double-click a tab name to rename it to something more descriptive.

Split Panes

Split the active terminal to view multiple sessions side by side.

• Horizontal split — Divides the terminal area into left and right panes.
• Vertical split — Stacks panes top and bottom.

Switch focus between panes using keyboard shortcuts, and close a split to return to a single pane. See the Keyboard Shortcuts table below for the relevant bindings.

Terminal Types

Local Terminal

A standard shell session on your local machine (bash or zsh, depending on your system). Useful for running kubectl, helm, flux, or any other CLI tools alongside the Kunobi UI.

To open a local terminal:

1. Click Terminal in the left sidebar.
2. Click + in the top right of the terminal area.

Pod Exec Terminal

Opens a shell session directly inside a running container — equivalent to kubectl exec -it <pod> -- /bin/sh.

To exec into a container:

1. Navigate to the K8s Drilldown page.
2. Find the pod you want to exec into.
3. Click on the pod to open the details sidebar.
4. Click Exec in the actions section.
5. If the pod has multiple containers, a container selector appears — choose the target container. Single-container pods open directly.
6. A new terminal tab opens with a shell inside the container.

Bulk shell open — Select multiple pods in the resource table and open shells for all of them at once (capped at 10 simultaneous sessions to prevent flooding).

Auto-reconnect — If a pod is deleted during a rollout, Kunobi tracks the owner reference (e.g., ReplicaSet, Deployment) and finds the replacement pod automatically. The terminal session reconnects without manual intervention.

Node Shell

Opens a privileged shell on a Kubernetes node — useful for debugging node-level issues such as disk pressure, networking, or kubelet configuration.

To access a node shell:

1. Navigate to K8s Drilldown and select the Nodes resource type.
2. Click on a node to open the details sidebar.
3. Click Node Shell in the actions section.

Under the hood, Kunobi creates a privileged debug pod on the target node using nsenter to enter the host namespace. The debug pod is automatically cleaned up when you close the terminal session.

Note: Node shell access requires cluster-admin permissions and may not be available in all clusters.

Log Viewer

Stream and search logs for pods and workloads directly inside the terminal panel.

Supported resource types: Pods, Deployments, StatefulSets, DaemonSets, ReplicaSets, Jobs, and Nodes.

Opening the Log Viewer

1. Navigate to the resource in K8s Drilldown.
2. Click on the resource to open the details sidebar.
3. Click Logs in the actions section.

A new terminal tab opens in log-viewer mode.

Log Viewer Features

• Real-time streaming — Follow mode tails new log lines as they arrive.
• Search — Find text in the log output with previous/next match navigation.
• Level filter — Filter by log level: DEBUG, INFO, WARN, ERROR, FATAL.
• Timestamps toggle — Show or hide timestamps on each line.
• Line wrap toggle — Wrap long lines to fit the pane, or scroll horizontally.
• Tail lines — By default, the viewer loads the 500 most recent lines.
• Previous container logs — View logs from a terminated container (equivalent to --previous).

Owner Reference Tracking

For workload-level resources (Deployments, StatefulSets, etc.), Kunobi resolves the underlying pods automatically. If a pod is replaced during a rollout, the log viewer detects the new pod via the owner reference chain and reconnects the stream seamlessly.

Port Forwarding

Forward one or more ports from a pod to your local machine — equivalent to kubectl port-forward.

To start port forwarding:

1. Navigate to K8s Resources and find the pod.
2. Select it — the action bar appears at the top of the table.
3. Click Port Forward (or press Shift+F).
4. In the dialog, enter the Remote Port (the container port) and optionally a Local Port — leave it empty for auto-assignment.
5. Click + Add Port to add additional port mappings in the same dialog.
6. Click Start Port Forward.

Once active, access the service at localhost:<local-port>.

Port validation — Both local and remote ports must be in the range 1 -- 65535.

Proxy terminals — Active port forwards appear as output-only terminal tabs in the terminal list, showing connection status and forwarded traffic information.

Per-cluster lifecycle — Port forwards are tied to their cluster connection. Disconnecting from a cluster automatically stops all port forwards for that cluster.

Terminal States

Each terminal displays a visual overlay indicating its current state:

State	Meaning
Connecting	Initializing the connection to the target.
Connected	Session is active and ready for input.
Disconnected	Connection lost. Click the overlay to reconnect.
Completed	The process finished normally (exit code 0).
Error	The connection failed after retries. Check the error message for details.

Keyboard Shortcuts

Action	macOS	Windows/Linux
Toggle terminal panel	⌘J	Ctrl+J
Copy selection	⌘C	Ctrl+C
Paste	⌘V	Ctrl+V
Split horizontal	—	—
Split vertical	—	—
Focus right pane	—	—
Focus left pane	—	—
Close split	—	—

Shortcuts marked with — are configurable in your keybindings. See Keybindings to customize any of these shortcuts.