Skip to main content
vers tunnel forwards a local port to a port on a VM. Traffic to 127.0.0.1:<local-port> on your machine is forwarded through the Vers SSH tunnel to <remote-host>:<remote-port> inside the VM. If <remote-host> is omitted, it defaults to localhost. This is exactly what ssh -L does — just with Vers’ SSH-over-TLS plumbing handled for you.

​
Synopsis

​
Examples

​
Forward local 8080 to port 80 on HEAD

​
Forward to a specific VM

​
Reach a service on a different host from inside the VM

Useful when the VM itself has access to an internal network (a database, another VM, a tenant service) that you want to poke at from your laptop.

​
When to use vers tunnel vs public hostnames

Public hostname

Every VM already has a public hostname: {vm-id}.vm.vers.sh. If the service is listening on ports 1024–10000 and should be reachable by other people or agents, just hit the hostname directly. See Networking.

vers tunnel

Use a tunnel when the service is bound to 127.0.0.1, listens on a port outside the public range, or shouldn’t be on the public internet at all (databases, admin panels, local dev servers).

​
How it works

1

Resolve target

Target VM is <vm-id|alias> if given, otherwise HEAD.
2

Establish SSH connection

Opens an SSH-over-TLS connection to the VM using your Vers SSH key (the same auth path as vers connect).
3

Bind locally

Listens on 127.0.0.1:<local-port>. Each new connection is forwarded through the SSH channel to <remote-host>:<remote-port> on the VM side.
4

Keep running

The tunnel stays up until you Ctrl-C or the connection drops.

​
Troubleshooting

  • address already in use — something else is bound to the local port. Pick another.
  • Tunnel opens but the service doesn’t respond — check the remote side is actually listening. From the VM: ss -tlnp | grep :<port> or curl localhost:<port>.
  • Works at first, then hangs — the VM paused or the SSH connection dropped. Check vers status <vm> and restart the tunnel.

​
Common Patterns

​
Forward a database port

​
Reach a private service via a VM

Useful when the VM can talk to something your laptop can’t:

​
Multi-service debugging

Run tunnels in separate terminals to poke at several services from the same VM at once:

​
See also