kurtosis-tech/service-manage

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 |