Softprobe CLI

Appearance

sp tunnel ​

When developers use this: Establish a bidirectional reverse WebSocket tunnel to bridge test execution and replay dispatches from a cloud-hosted control plane (SaaS) down to local services running on your workstation or in isolated private environments.

Synopsis ​

The sp tunnel command starts a persistent, foreground reverse WebSocket tunnel client.

When you use a cloud-hosted control plane (such as api.softprobe.ai) but your Java application under test runs locally on your laptop, the cloud-hosted scheduler cannot direct HTTP replay traffic to a private address like http://localhost:8080.

By establishing a WebSocket tunnel connection to the SaaS gateway, the scheduler can route replay dispatches through this secure channel down to your machine, where the CLI forwards them locally and replies with response frames.

SaaS Edge Authorization & Header Injection ​

When tunneling to the SaaS environment (api.softprobe.ai), the WebSocket connection must pass through our secure edge gateway. The sp client automatically handles authentication handshakes by injecting the following custom headers into the WebSocket connection request:

http
Authorization: Bearer <your-token>
X-Tenant-ID: <your-tenant-id>

The CLI retrieves these credentials from your active configuration profile or environment variable overrides. If they are missing or invalid, the edge gateway will reject the handshake with a 401 Unauthorized or 403 Forbidden response.

Usage ​

bash
sp tunnel [flags]

Flags ​

FlagDefaultDescription
--port8080Local target application port where the Java service is running
--apptravel-otaTarget application ID (appId) or application name for this tunnel
--url—Override the exact WebSocket gateway URL (e.g., ws://localhost:8092/api/ws/tunnel)

All Global flags are fully supported, specifically:

  • --api-url: Used to infer the WebSocket connection URL if --url is omitted (e.g. converting https://api.softprobe.ai to wss://api.softprobe.ai/api/ws/tunnel).
  • --tenant-id: Target Tenant ID (overrides profile config).
  • --token: Auth token (overrides profile config).
  • --profile: Active profile (for config resolution).

Connection Resolution ​

If the --url flag is not explicitly provided, the CLI automatically infers the secure WebSocket endpoint from your resolved API URL:

  1. SaaS Cloud: If your API URL points to the cloud (https://api.softprobe.ai), the CLI connects via secure WebSockets: wss://api.softprobe.ai/api/ws/tunnel?app=<appId>
  2. Self-Hosted HTTP: If the API URL begins with http://, the scheme is converted to standard WebSocket: ws://<api-host>/api/ws/tunnel?app=<appId>
  3. Self-Hosted HTTPS: If the API URL begins with https://, the scheme is converted to secure WebSocket: wss://<api-host>/api/ws/tunnel?app=<appId>

SaaS Lifecycle Example ​

Step 1: Start your local service ​

Run your Java application with the Softprobe agent attached:

bash
java -javaagent:/opt/softprobe/sp-agent.jar \
     -Dsp.app.id=f3e2d1c0b9a87654 \
     -jar target/my-local-app.jar

Step 2: Establish the Secure Tunnel to SaaS ​

Start the tunnel client targeting the production SaaS gateway:

bash
sp tunnel \
  --app f3e2d1c0b9a87654 \
  --port 8080 \
  --api-url https://api.softprobe.ai

If you prefer to configure your environment explicitly using environment variables:

bash
export SP_TOKEN="eyJhbGciOiJIUzI1NiIsIn..."
export SP_TENANT_ID="tenant-12345"

sp tunnel --app f3e2d1c0b9a87654 --port 8080 --api-url https://api.softprobe.ai

Console Output:

text
Connecting tunnel to wss://api.softprobe.ai/api/ws/tunnel?app=f3e2d1c0b9a87654...
Forwarding traffic for app 'f3e2d1c0b9a87654' to localhost:8080
✔ Reverse tunnel connected successfully!

Once established, inbound replay dispatches from the SaaS scheduler will be printed to your console:

text
[TUNNEL] Received request: POST /api/flights/search (ID: req-abc123)
[TUNNEL] Dispatched response back (Status: 200)