/files-inspect

name: files-inspect
description: 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.
compatibility: Requires kurtosis CLI with a running engine.
metadata:
  author: ethpandaops
  version: "1.0"

Files Inspect

Work with Kurtosis file artifacts — the mechanism for passing files between services and into containers.

What are file artifacts?

File artifacts are named collections of files stored in an enclave. They're created by:

• `plan.upload_files()` — upload local files from a package
• `plan.render_templates()` — render Go templates with data
• `plan.store_service_files()` — copy files from a running service
• `plan.run_sh()` / `plan.run_python()` — store output files from scripts

Services mount artifacts via the `files` parameter in `ServiceConfig`.

List artifacts in an enclave

kurtosis enclave inspect <enclave-name>

The "Files Artifacts" section shows each artifact's UUID and name:

========================================= Files Artifacts =========================================
UUID           Name
4a0563e5a391   1-lighthouse-geth-0-127
f49b81f30a8f   el_cl_genesis_data
88c3f17013f3   jwt_file

Download artifacts

# Download to a local directory
kurtosis files download <enclave-name> <artifact-name> /tmp/artifact-output

# Example: inspect genesis data
kurtosis files download <enclave-name> el_cl_genesis_data /tmp/genesis
ls -la /tmp/genesis/
cat /tmp/genesis/config.yaml

Upload files

# Upload a local file or directory as an artifact
kurtosis files upload <enclave-name> /path/to/local/file-or-dir

The command returns the artifact name and UUID for use in subsequent service configs.

Inspect files inside a running service

Verify files were mounted correctly by checking content matches expectations:

# List files at the mount path to confirm they exist
kurtosis service exec <enclave-name> <service-name> -- ls -la /mounted/path/

# Inspect file contents to verify correctness
kurtosis service exec <enclave-name> <service-name> -- cat /mounted/path/config.yaml

# Compare against expected content (e.g., check a key value)
kurtosis service exec <enclave-name> <service-name> -- sh -c "grep 'expected_key' /mounted/path/config.yaml"

# Or shell in for interactive exploration
kurtosis service shell <enclave-name> <service-name>

Starlark file patterns

Upload files from package

artifact = plan.upload_files(src="./static_files/config.yaml", name="my-config")

plan.add_service(
    name="my-service",
    config=ServiceConfig(
        image="my-image:latest",
        files={"/etc/myapp": artifact},
    ),
)

# Verify files were mounted correctly
plan.exec(
    service_name="my-service",
    recipe=ExecRecipe(command=["ls", "-la", "/etc/myapp/"]),
)

Render templates with variables

template = read_file("./templates/config.toml.tmpl")

artifact = plan.render_templates(
    name="rendered-config",
    config={
        "config.toml": struct(
            template=template,
            data={"port": 8080, "host": "0.0.0.0"},
        ),
    },
)

Template syntax uses Go templates:

# config.toml.tmpl
host = "{{.host}}"
port = {{.port}}

Copy files from a running service

artifact = plan.store_service_files(
    service_name="my-service",
    src="/data/output",
    name="service-output",
)

Store output from a shell command

result = plan.run_sh(
    run="echo 'hello' > /tmp/output.txt && cat /tmp/output.txt",
    store=[StoreSpec(src="/tmp/output.txt", name="shell-output")],
)

Kubernetes-specific

On Kubernetes, file artifacts are stored as files-artifacts-expander init containers:

# See init containers for a service pod
kubectl describe pod <pod-name> -n kt-<enclave-name> | grep -A10 "Init Containers"

# Check if files-artifacts-expander succeeded
kubectl logs <pod-name> -n kt-<enclave-name> -c files-artifact-expander

# If the expander image is failing (ImagePullBackOff), check image tag
kubectl describe pod <pod-name> -n kt-<enclave-name> | grep "files-artifacts-expander"

Debugging workflow

When files aren't working as expected, follow these steps:

# 1. List artifacts in the enclave to verify they exist
kurtosis enclave inspect <enclave-name>

# 2. Download the artifact and inspect its contents locally
kurtosis files download <enclave-name> <artifact-name> /tmp/debug-artifact
cat /tmp/debug-artifact/config.yaml

# 3. Verify the mount path inside the service
kurtosis service exec <enclave-name> <service-name> -- ls -la /mounted/path/

# 4. Check file contents match expectations
kurtosis service exec <enclave-name> <service-name> -- cat /mounted/path/config.yaml

# 5. If mismatch: check template data or upload source

Common issues

| Symptom | Cause | Fix | |---------|-------|-----| | File not found in service | Wrong mount path | Check `files` dict key matches expected path | | Empty file after render | Template syntax error | Download artifact and inspect rendered output | | Init container crash | files-artifacts-expander image issue | Check init container logs with kubectl | | Artifact name conflict | Duplicate artifact names | Use unique names for each `plan.upload_files()` / `plan.render_templates()` | | Permission denied | Container runs as non-root | Mount to a writable path or adjust image permissions |