Hybrid Port Forward

Crafting supports Hybrid Development, which allows developers to write and run code on their local machine while connecting to the workloads running inside a sandbox. The cs port-forward command establishes both incoming and outgoing port forwards to enable this workflow.

Incoming Port Forward

An incoming port forward routes traffic that would normally hit a workload inside the sandbox to a port on your local machine instead. This effectively replaces a running service in the sandbox with the process running locally — without redeploying anything.

Example

Given a sandbox:

endpoints:
- name: app
  http:
    routes:
    - path_prefix: /
      backend:
        target: frontend
        port: http
workspaces:
- name: frontend
  ports:
  - name: http
    port: 8000
    protocol: HTTP/TCP

When a developer runs the frontend locally on localhost:8000 and wants to test it using the sandbox's endpoint and backend services:

cs port-forward -W SANDBOX/frontend

This forwards incoming traffic hitting https://app--SANDBOX-ORG.APP-DOMAIN to localhost:8000 on the developer's machine.

Outgoing Port Forward

An outgoing port forward routes traffic from localhost:PORT on the developer's machine to a workload running inside a sandbox. This lets a locally running process access sandbox-hosted dependencies (such as databases or caches) without any configuration changes.

Example

Given a sandbox:

workspaces:
- name: service
  ports:
  - name: http
    port: 8000
    protocol: HTTP/TCP
  port_forward_rules:
  - local: '3306'
    remote:
      target: db
      port: mysql
  - local: '6379'
    remote:
      target: redis
      port: redis
dependencies:
- name: db
  service_type: mysql
- name: redis
  service_type: redis

The service workload accesses MySQL at localhost:3306 and Redis at localhost:6379 within the sandbox. A developer running the same service locally uses the same configuration. Running:

cs port-forward -W SANDBOX/service

Establishes:

• Incoming: Forwards traffic from the sandbox's service port 8000 to localhost:8000 on the local machine.
• Outgoing: Forwards local localhost:3306 to the sandbox's db:3306 (MySQL), and localhost:6379 to redis:6379.

The local process runs without any configuration changes.

Explicit Port Forwarding Rules

By default, cs port-forward infers port-forwarding rules from the target workspace:

• Declared ports for incoming forwarding
• Rules in port_forward_rules for outgoing forwarding

Custom Outgoing Rules (-L)

A custom outgoing forwarding rule can be added using the -L flag:

cs port-forward -L 3000:8000 -L 3306:mysql:3306

• 3000:8000 — forwards local port 3000 to port 8000 on the target workspace.
• 3306:mysql:3306 — forwards local port 3306 to workload mysql port 3306.

Note: All remote ports must listen on 0.0.0.0. Ports listening only on localhost will not work.

Custom Incoming Rules (-R)

A custom incoming forwarding rule can be added using the -R flag:

cs port-forward -R 3000:localhost:3000

This forwards incoming traffic to port 3000 on the workspace to localhost:3000 on the local machine. The hostname localhost can be replaced with any hostname or IP address reachable by the local machine.

Disabling Auto-Discovered Rules

• Add -P to disable auto-discovered incoming forwarding rules.
• Add -F to disable auto-discovered outgoing forwarding rules.

See Also

• Workspace Port Forward — in-workspace port forward rules (used as preset for cs port-forward)
• Endpoints — exposing sandbox services externally
• Sandbox Networking — how workloads communicate within a sandbox