kurtosis-tech 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 |