/service-manage

name: service-manage
description: Manage services in Kurtosis enclaves. Add, inspect, stop, start, remove, update services. View logs, shell into containers, and execute commands. Use when you need to interact with running services.
compatibility: Requires kurtosis CLI with a running engine and at least one enclave.
metadata:
  author: ethpandaops
  version: "1.0"

Service Manage

Manage services running inside Kurtosis enclaves.

List services

# Services are shown in enclave inspect output
kurtosis enclave inspect <enclave-name>

View logs

# View logs
kurtosis service logs <enclave-name> <service-name>

# Follow logs in real time
kurtosis service logs <enclave-name> <service-name> -f

# Show all logs (not just recent)
kurtosis service logs <enclave-name> <service-name> -a

Shell and exec

# Get an interactive shell
kurtosis service shell <enclave-name> <service-name>

# Execute a single command
kurtosis service exec <enclave-name> <service-name> -- ls -la /data

# Execute with pipes (wrap in sh -c)
kurtosis service exec <enclave-name> <service-name> -- sh -c "cat /etc/hosts | grep localhost"

Inspect a service

kurtosis service inspect <enclave-name> <service-name>

Shows detailed info including ports, status, and container ID.

Stop and start

# Stop a service (keeps it in the enclave, just stops the container)
kurtosis service stop <enclave-name> <service-name>

# Restart a stopped service
kurtosis service start <enclave-name> <service-name>

Remove a service

kurtosis service rm <enclave-name> <service-name>

Add a service manually

kurtosis service add <enclave-name> <service-name> <image>

Update a service

kurtosis service update <enclave-name> <service-name>

Common patterns

Verify after operations

Always confirm stop/start/rm succeeded:

# Check service state changed as expected
kurtosis enclave inspect <enclave-name>

# For start: verify the service responds
kurtosis service exec <enclave-name> <service-name> -- wget -qO- http://localhost:8080/health

Check if a service is healthy

# HTTP health check
kurtosis service exec <enclave-name> <service-name> -- wget -qO- http://localhost:8080/health

# Check process is running
kurtosis service exec <enclave-name> <service-name> -- ps aux

# Check listening ports
kurtosis service exec <enclave-name> <service-name> -- netstat -tlnp

Debug a crashing service

# Check recent logs
kurtosis service logs <enclave-name> <service-name>

# Check all logs from the start
kurtosis service logs <enclave-name> <service-name> -a

# Inspect for error status
kurtosis service inspect <enclave-name> <service-name>

Copy data between services

Use file artifacts in Starlark:

# Store files from one service
artifact = plan.store_service_files(service_name="source-svc", src="/data/output", name="shared-data")

# Mount in another service
plan.add_service(name="dest-svc", config=ServiceConfig(
    image="my-image",
    files={"/input": artifact},
))

Troubleshooting

| Symptom | Cause | Fix | |---------|-------|-----| | Service won't start | Port conflict or image issue | Check logs with `kurtosis service logs`, verify image exists | | Exec command hangs | Container has no shell | Use a base image with shell or `exec -- /bin/sh -c "command"` | | Logs show no output | Service crashed immediately | Use `kurtosis service logs -a` to see full history | | Service not listed | Wrong enclave | Run `kurtosis enclave ls` and `kurtosis enclave inspect` to find it | | Stop has no effect | Service already stopped | Check status with `kurtosis enclave inspect` first |