Port Forwarding to Workspace Services

Access web servers, databases, and other services running in your Workspace Manager workspaces from your local machine using SSH port forwarding.

Overview

SSH port forwarding allows you to securely tunnel network connections from your local machine to services running in your workspace. This enables you to access workspace services as if they were running locally.

Prerequisites

• SSH access configured (see SSH documentation)
• Workspace running and accessible
• Service running in the workspace on a specific port

Basic Port Forwarding

SSH port forwarding creates a secure tunnel between your local machine and the workspace. There are two main types:

Local Port Forwarding

Forward a local port to a service running in the workspace:

ssh -L [local_port]:localhost:[remote_port] wsm.my_workspace

Example: Access a web server running on port 3000 in the workspace:

ssh -L 8080:localhost:3000 wsm.my_workspace

Now visit http://localhost:8080 in your browser to access the workspace service.

Remote Port Forwarding

Expose a local service to the workspace (less common):

ssh -R [remote_port]:localhost:[local_port] wsm.my_workspace

Example: Make your local database accessible from the workspace:

ssh -R 5432:localhost:5432 wsm.my_workspace

Background Port Forwarding

Keep the tunnel open without an interactive session:

ssh -fN -L 8080:localhost:3000 wsm.my_workspace

• -f - Run in background
• -N - Don’t execute remote commands

Common Use Cases

Database Access

Access databases running in your workspace. Workspace Manager databases run on the db hostname within the workspace network.

MariaDB / MySQL

ssh -L 3306:db:3306 wsm.my_workspace

Connect with your local client:

mysql -h 127.0.0.1 -P 3306 -u dbuser -p

Or use MySQL Workbench, DBeaver, or other GUI tools pointing to localhost:3306.

PostgreSQL

ssh -L 5432:db:5432 wsm.my_workspace

Connect with your local client:

psql -h localhost -p 5432 -U dbuser -d dbname

Or use a GUI tool like pgAdmin, DBeaver, or DataGrip pointing to localhost:5432.

MongoDB

ssh -L 27017:db:27017 wsm.my_workspace

Connect with your local client:

mongosh mongodb://localhost:27017/mydb

Or use MongoDB Compass or other GUI tools pointing to localhost:27017.

Elasticsearch / OpenSearch

Forward Elasticsearch or OpenSearch for local access:

# Elasticsearch (default port 9200)
ssh -L 9200:db:9200 wsm.my_workspace

# OpenSearch (default port 9200)
ssh -L 9200:db:9200 wsm.my_workspace

Access the API locally:

# Check cluster health
curl http://localhost:9200/_cluster/health

# Search indices
curl http://localhost:9200/_cat/indices

Use with local tools like Elasticvue or other Elasticsearch/OpenSearch clients by configuring them to connect to http://localhost:9200.

Redis / Valkey

ssh -L 6379:localhost:6379 wsm.my_workspace

Connect with redis-cli:

redis-cli -h localhost -p 6379

Or use RedisInsight or other Redis/Valkey GUI tools pointing to localhost:6379.

Multiple Ports

Forward multiple services in a single SSH session:

# MariaDB, OpenSearch, and Redis/Valkey
ssh -L 3306:db:3306 \
    -L 9200:db:9200 \
    -L 6379:localhost:6379 \
    wsm.my_workspace

Now you can access all three services from your local machine simultaneously.

Remote Port Forwarding (Local to Workspace)

Remote port forwarding exposes services running on your local machine to the workspace. This is useful for debugging scenarios.

Xdebug Remote Debugging

Enable Xdebug in your workspace to connect back to your local IDE:

Step 1: Forward your local Xdebug port to the workspace:

ssh -R 9003:localhost:9003 wsm.my_workspace

Step 2: Configure Xdebug in your workspace’s local INI file at ~/html/.user.ini:

xdebug.mode=debug
xdebug.client_host=localhost
xdebug.client_port=9003
xdebug.start_with_request=trigger

Step 3: Configure your local IDE to listen on port 9003:

PhpStorm/IntelliJ:

1. Go to Settings → PHP → Debug
2. Set Xdebug port to 9003
3. Click Start Listening for PHP Debug Connections

VS Code:

1. Install PHP Debug extension
2. Add to .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Listen for Xdebug",
      "type": "php",
      "request": "launch",
      "port": 9003,
      "pathMappings": {
        "/home/web/project": "${workspaceFolder}"
      }
    }
  ]
}

Step 4: Trigger Xdebug from your browser or CLI:

# Browser: Add query parameter
http://your-workspace-url.com?XDEBUG_TRIGGER=1

# CLI: Set environment variable
XDEBUG_TRIGGER=1 php script.php

Persistent Xdebug Forwarding

Add the remote forward to your SSH config for automatic setup:

Host wsm.my_workspace
  User <workspace_id>
  HostName <ssh_endpoint>
  RemoteForward 9003 localhost:9003

Other Remote Forwarding Use Cases

Webhook Testing: Expose your local webhook endpoint to the workspace:

ssh -R 8080:localhost:8080 wsm.my_workspace

Now services in the workspace can send webhooks to http://localhost:8080.

Local API Access: Make your local API accessible from workspace:

ssh -R 4000:localhost:4000 wsm.my_workspace

SSH Config for Persistent Forwarding

Add port forwarding to your SSH config for automatic setup:

Host wsm.my_workspace
  User <workspace_id>
  HostName <ssh_endpoint>
  # Forward workspace services to local
  LocalForward 3306 db:3306
  LocalForward 5432 db:5432
  LocalForward 9200 db:9200
  LocalForward 6379 localhost:6379
  # Forward local Xdebug to workspace
  RemoteForward 9003 localhost:9003

Now connecting with ssh wsm.my_workspace automatically forwards all configured ports in both directions.

Related Documentation

• SSH Access - Configure SSH access to workspaces
• Connecting Visual Studio Code - VS Code remote development
• Connecting JetBrains IDEs - JetBrains remote development