Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.vers.sh/llms.txt

Use this file to discover all available pages before exploring further.

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

# HEAD VM
vers tunnel <local>:<remote>
vers tunnel <local>:<remote-host>:<remote>

# Specific VM
vers tunnel <vm-id|alias> <local>:<remote>
vers tunnel <vm-id|alias> <local>:<remote-host>:<remote>

​
Examples

​
Forward local 8080 to port 80 on HEAD

vers tunnel 8080:80

​
Forward to a specific VM

vers tunnel my-vm 5432:5432

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

# Forward local 9090 to 10.0.0.2:80 via the VM
vers tunnel 9090:10.0.0.2:80
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

vers tunnel my-db-vm 5432:5432
# then from your laptop: psql -h 127.0.0.1 -p 5432 ...

​
Reach a private service via a VM

Useful when the VM can talk to something your laptop can’t: 
vers tunnel my-vm 9090:10.0.0.2:80
# then from your laptop: curl http://127.0.0.1:9090

​
Multi-service debugging

Run tunnels in separate terminals to poke at several services from the same VM at once: 
# Terminal 1
vers tunnel my-vm 3000:3000       # app
# Terminal 2
vers tunnel my-vm 5432:5432       # database
# Terminal 3
vers tunnel my-vm 6379:6379       # cache

​
See also