alpacon tunnel

Create a secure TCP tunnel between your local machine and a remote server. This allows you to forward a local port to a remote port, enabling access to services running on the server (such as databases, web applications, or internal APIs) through a secure connection. Optionally, run a local command with the tunnel lifecycle attached.

alpacon tunnel [flags] SERVER [-- COMMAND...]

Options

  -g, --groupname string      Groupname for the tunnel
  -h, --help                  help for tunnel
  -l, --local string          Local port to listen on (required)
  -r, --remote string         Remote port to connect to (required)
  -u, --username string       Username for the tunnel
  -v, --verbose               Show connection logs
      --work-session string   Attach this tunnel to a work-session (overrides 'work-session use')

Running a local command

If -- COMMAND [ARGS...] is provided, Alpacon runs the local command in the same session with the tunnel lifecycle attached: the tunnel opens before the command starts and closes when the command exits. Place -- before the local command so Alpacon parses the tunnel flags and forwards everything after -- to the local program exactly as provided.

Examples

Forward local port 9000 to remote port 8082:

alpacon tunnel my-server -l 9000 -r 8082

Same using long flags:

alpacon tunnel my-server --local 9000 --remote 8082

Forward local port 2222 to remote SSH port 22:

alpacon tunnel my-server -l 2222 -r 22

Specify username and groupname for the tunnel:

alpacon tunnel my-server -l 9000 -r 8082 -u admin -g developers

Attach the tunnel to a specific work session:

alpacon tunnel my-server -l 9000 -r 8082 --work-session 11111111-2222-3333-4444-555555555555

Run psql with the tunnel attached:

alpacon tunnel prod-db -l 5432 -r 5432 -- psql -h 127.0.0.1 -p 5432 -U app appdb

Run kubectl with the tunnel attached:

alpacon tunnel prod-k8s -l 6443 -r 6443 -- kubectl --server=https://127.0.0.1:6443 get pods

Enable verbose output for debugging:

alpacon tunnel my-server -l 9000 -r 8082 -v

Work session requirement

When you sign in with browser login, alpacon tunnel requires an active work session that includes the tunnel scope. Token authentication (API token or service token) bypasses this requirement.

The session to attach is resolved from the --work-session flag, the ALPACON_WORK_SESSION environment variable, or the active session set with alpacon work-session use—in that order.