engine-manage

name	engine-manage
description	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.
compatibility	Requires kurtosis CLI. Docker or Kubernetes cluster access depending on backend.
metadata	{"author":"ethpandaops","version":"1.0"}

Engine Manage

Manage the Kurtosis engine server lifecycle.

Status

kurtosis engine status

Shows whether the engine is running and its version.

Start

# Start with default settings
kurtosis engine start

# Start with debug images
kurtosis --debug-mode engine start

On Kubernetes, the engine runs as a pod in a kurtosis-engine-* namespace. You also need to run kurtosis gateway to access it from your local machine.

Stop

kurtosis engine stop

Restart

kurtosis engine restart

Equivalent to stop + start. Useful after changing cluster settings or upgrading.

View logs

kurtosis engine logs

Dumps engine server logs. Useful for diagnosing startup failures or API errors.

Docker vs Kubernetes

# Check which backend is active
kurtosis cluster get

# Switch to Docker
kurtosis cluster set docker
kurtosis engine restart

# Switch to Kubernetes
kurtosis cluster set kubernetes
kurtosis engine restart
kurtosis gateway  # Required for k8s

Engine on Kubernetes

When running on Kubernetes:

# The engine runs in its own namespace
kubectl get ns | grep kurtosis-engine

# Check engine pod
kubectl get pods -n <engine-namespace>

# View engine logs directly
kubectl logs <engine-pod> -n <engine-namespace>

# Start the gateway (required for local CLI to reach k8s engine)
kurtosis gateway &

Common issues

Symptom	Fix
No Kurtosis engine is running	Run kurtosis engine start
Engine starts but engine status shows nothing (k8s)	Start the gateway: kurtosis gateway
Version mismatch warning	kurtosis engine restart to match CLI version
Engine start hangs (k8s)	Check pods: kubectl get pods -A | grep kurtosis
Old engine blocking new start	kurtosis engine stop then clean namespaces