port-forward

Port Forward

View and manage port mappings for Kurtosis services.

View port info

kurtosis port print <enclave-name> <service-name> <port-id>

This prints the local URL for a specific port.

Find all ports

The easiest way to see all port mappings is enclave inspect:

kurtosis enclave inspect <enclave-name>

Output shows mappings like:

rpc: 8545/tcp -> 127.0.0.1:61817
ws: 8546/tcp -> 127.0.0.1:61813

The right side (127.0.0.1:61817) is how you access the service locally.

Port IDs

Port IDs are defined in the Starlark ServiceConfig:

plan.add_service(
    name="my-service",
    config=ServiceConfig(
        image="ethereum/client-go:latest",
        ports={
            "rpc": PortSpec(number=8545),      # port ID: "rpc"
            "ws": PortSpec(number=8546),        # port ID: "ws"
            "metrics": PortSpec(number=9001),   # port ID: "metrics"
        },
    ),
)

No-connect mode

If you ran with --no-connect, ports won't be forwarded locally:

# Ports not forwarded
kurtosis run --no-connect ./my-package

# Ports forwarded (default)
kurtosis run ./my-package

Kubernetes

On Kubernetes, port forwarding goes through the gateway. If ports stop working, restart the gateway:

pkill -f "kurtosis gateway"
kurtosis gateway &

Troubleshooting

When a port is unreachable, follow this diagnostic workflow:

# 1. Verify the enclave is running and check port mappings
kurtosis enclave inspect <enclave-name>

# 2. Confirm the specific service is running (not STOPPED)
kurtosis service inspect <enclave-name> <service-name>

# 3. If service is running but port fails, check service logs for errors
kurtosis service logs <enclave-name> <service-name>

# 4. On Kubernetes, verify the gateway is running
kurtosis gateway

Symptom	Cause	Fix
Port not accessible	Service not running or port not exposed	Check step 1-2 above
Connection refused	Service crashed or wrong interface	Check service logs (step 3)
No port mapping shown	Ran with --no-connect	Re-run without --no-connect
K8s ports unreachable	Gateway not running	Restart gateway (step 4)