// 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.
| name | enclave-inspect |
| description | 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. |
| compatibility | Requires kurtosis CLI with a running engine. |
| metadata | {"author":"ethpandaops","version":"1.0"} |
Inspect and manage Kurtosis enclaves and their contents.
kurtosis enclave ls
Output shows enclave name, UUID, status (RUNNING/STOPPED), and creation time.
kurtosis enclave inspect <enclave-name>
This shows:
# Full enclave inspection (shows all services with ports)
kurtosis enclave inspect <enclave-name>
# View logs for a service
kurtosis service logs <enclave-name> <service-name>
# Follow logs in real time
kurtosis service logs <enclave-name> <service-name> -f
# Shell into a service
kurtosis service shell <enclave-name> <service-name>
# Run a command in a service
kurtosis service exec <enclave-name> <service-name> -- <command>
The inspect output shows port mappings like:
http: 8545/tcp -> http://127.0.0.1:61817
This means port 8545 inside the container is mapped to localhost:61817. On Kubernetes with gateway running, these are forwarded through the gateway.
File artifacts are named blobs of files stored in the enclave.
# List artifacts (shown in enclave inspect)
kurtosis enclave inspect <enclave-name>
# Download an artifact to local disk
kurtosis files download <enclave-name> <artifact-name> /tmp/output-dir
# Upload a local file as an artifact
kurtosis files upload <enclave-name> /path/to/local/file
Export the full enclave state for offline debugging:
kurtosis enclave dump <enclave-name> /tmp/enclave-dump
# Verify the dump completed successfully
ls -la /tmp/enclave-dump/
This exports:
Useful for sharing with others to debug issues.
| Symptom | Cause | Fix |
|---|---|---|
| Enclave not found | Typo or enclave was removed | Run kurtosis enclave ls to see available enclaves |
| Dump directory empty | Enclave has no services | Check kurtosis enclave inspect — enclave may be idle |
| Inspect shows STOPPED services | Services crashed or were stopped | Check logs with kurtosis service logs before restarting |
| K8s namespace missing | Enclave was cleaned up | Re-run the package to recreate the enclave |
# Create an enclave (usually done by kurtosis run)
kurtosis enclave add <enclave-name>
# Stop an enclave (preserves state)
kurtosis enclave stop <enclave-name>
# Remove a specific enclave
kurtosis enclave rm <enclave-name>
# Remove all enclaves
kurtosis clean -a
On Kubernetes, each enclave is a namespace prefixed with kt-:
# See enclave namespaces
kubectl get ns | grep kt-
# See pods in an enclave
kubectl get pods -n kt-<enclave-name>
# Describe a service pod
kubectl describe pod <pod-name> -n kt-<enclave-name>
# View pod logs directly
kubectl logs <pod-name> -n kt-<enclave-name>
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.
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).
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.
Lint and format Kurtosis Starlark files. Check syntax, validate docstrings, and auto-format .star files. Use when writing or reviewing Starlark packages to ensure code quality.
View and manage port mappings for Kurtosis services. Check which local ports map to service ports and troubleshoot connectivity. Use when services aren't reachable or you need to find the right port.
Manage Kurtosis Portal for remote context access. Start, stop, and check status of the Portal daemon that enables communication with remote Kurtosis servers. Use when working with remote Kurtosis contexts.