gateway

Name: gateway
Author: kurtosis-tech/kurtosis

$npx mdskill add kurtosis-tech/kurtosis/gateway

Start the Kurtosis gateway to access Kubernetes engine pods.

Enables local CLI access to engine pods in Kubernetes clusters.
Requires kurtosis CLI with Kubernetes cluster access.
Executes port forwarding to engine and service pods automatically.
Displays port mappings via kurtosis enclave inspect command.

SKILL.md

.github/skills/gatewayView on GitHub ↗

---
name: gateway
description: Start and manage the Kurtosis gateway for Kubernetes. The gateway forwards local ports to the Kurtosis engine and services running in a k8s cluster. Required when using Kurtosis with Kubernetes. Use when kurtosis engine status shows nothing on k8s or services aren't reachable.
compatibility: Requires kurtosis CLI with Kubernetes cluster access.
metadata:
author: ethpandaops
version: "1.0"
---

# Gateway

The Kurtosis gateway creates local port forwards to the engine and services running in a Kubernetes cluster.

## When you need it

The gateway is **required** when running Kurtosis on Kubernetes. Without it, the local CLI cannot reach the engine pod in the cluster.

Not needed when using Docker backend.

## Start the gateway

```bash
# Run in the background
kurtosis gateway &

# Or in a separate terminal
kurtosis gateway
```

## Verify it's working

```bash
kurtosis engine status
```

If this returns engine info, the gateway is working. If it says "No Kurtosis engine is running" but you know the engine pod is up, the gateway isn't running.

## Stop the gateway

```bash
pkill -f "kurtosis gateway"
```

## How it works

The gateway:
1. Finds the engine pod in the `kurtosis-engine-*` namespace
2. Creates a local port forward to the engine's gRPC port
3. When services are accessed, creates additional port forwards to service pods
4. Port mappings shown in `kurtosis enclave inspect` point to localhost via the gateway

## Common issues

| Symptom | Fix |
|---------|-----|
| `No engine running` but engine pod is up | Start the gateway: `kurtosis gateway &` |
| Gateway crashes or disconnects | Restart: `pkill -f "kurtosis gateway"; kurtosis gateway &` |
| Port conflicts | Kill old gateway first: `pkill -f "kurtosis gateway"` |
| Services unreachable after gateway restart | Re-inspect enclave for new port mappings |

More from kurtosis-tech/kurtosis

Skill	Description
cli-local-build	Build and test the Kurtosis CLI from source. Compile the CLI binary locally, run it against Docker or Kubernetes engines, and iterate on CLI changes without creating a release. Use when developing or debugging CLI commands.
cluster-manage	Manage Kurtosis cluster settings. Switch between Docker and Kubernetes backends, list available clusters, and configure which cluster Kurtosis uses. Use when you need to change where Kurtosis runs enclaves.
context-manage	Manage Kurtosis contexts for connecting to different Kurtosis instances. Add, list, switch, and remove contexts. Use when working with multiple Kurtosis environments (local, remote, team shared).
docker-debug	Debug Kurtosis running on local Docker. Inspect engine, API container, and service logs. Diagnose container crashes, port conflicts, and networking issues. Use when kurtosis commands fail or services aren't reachable on Docker.
docker-local-build	Build and test Kurtosis from source on local Docker. Compiles all components (engine, core, files-artifacts-expander), builds Docker images, installs the CLI, and restarts the engine. Use when developing Kurtosis and testing changes locally with Docker.
dump	Dump Kurtosis state for debugging and sharing. Export enclave state including service logs, configurations, and file artifacts to a local directory. Use when you need to capture state for offline analysis or to share with others for debugging.
enclave-inspect	Inspect and manage Kurtosis enclaves. List enclaves, view services and ports, examine file artifacts, dump enclave state for debugging, and clean up. Use when you need to understand what's running inside an enclave or export its state.
engine-manage	Manage the Kurtosis engine server. Start, stop, restart the engine, check status, and view engine logs. Covers both Docker and Kubernetes engine backends. Use when the engine won't start, needs restarting, or you need to check engine health.
files-inspect	Inspect, download, upload, and debug Kurtosis file artifacts. View artifacts in an enclave, download them locally for inspection, upload local files, and troubleshoot file mounting issues. Use when services can't find expected files or configs are wrong.
grafloki	Start Grafana and Loki for centralized log collection from Kurtosis enclaves. View aggregated service logs in a Grafana dashboard. Use when you need a UI for browsing logs across multiple services or want persistent log storage.