Local Tunnels & Proxies

The proxy, connect, share, and ssh subcommands expose local services and sandbox shells over iroh-based P2P tunnels and connect to them from another machine. No port forwarding or VPN required.

proxy

Manage P2P proxy endpoints. The proxy command has several subcommands.

proxy start

Expose a local port over iroh. Prints a heyo:// connection URL that remote clients use to connect. Runs until Ctrl+C.

heyvm proxy start <PORT> [-r <RELAY_URL>] [--name <SHORTNAME>]
# Example:
heyvm proxy start 3000
heyvm proxy start 8080 --name my-server

Flag	Description
`-r, --relay <URL>`	Relay server URL for short ticket codes
`--name <NAME>`	Save the connection URL under this shortname

proxy list

List saved proxy endpoints (shortnames).

heyvm proxy list

proxy add

Add a saved endpoint by shortname.

heyvm proxy add <SHORTNAME> <TICKET_URL>
# Example:
heyvm proxy add my-server heyo://abc123...

proxy sync

Sync local proxy endpoints with the cloud.

heyvm proxy sync

connect

Connect to a remote proxy via its heyo:// ticket URL or a saved shortname. Binds a local TCP listener and forwards traffic to the remote service. Runs until Ctrl+C.

heyvm connect <TICKET_URL_OR_SHORTNAME> [-p LOCAL_PORT] [--shell] [--run-host]

Flag	Description
`-p, --port <PORT>`	Local port to listen on (default: random)
`-r, --relay <URL>`	Relay server URL for short ticket lookup
`--save <NAME>`	Save this connection under a shortname
`--shell`	After connecting, open an interactive SSH shell to the remote sandbox
`--run-host`	After connecting, mount remote workspace via SSHFS and run a host command (conflicts with `--shell`)
`--mount-path <PATH>`	Sandbox path to mount via SSHFS (default: `/workspace`, used with `--run-host`)

# Connect and listen on a random port
heyvm connect heyo://abc123...

# Connect on a specific port
heyvm connect heyo://abc123... -p 3000

# Connect using a saved shortname
heyvm connect my-server -p 3000

# Connect and open a shell
heyvm connect heyo://abc123... --shell

# Connect and run a host command on the remote workspace
heyvm connect heyo://abc123... --run-host -- npm test

Share a sandbox's shell over the P2P proxy (iroh). Remote users can connect via the ssh command.

heyvm share <id-or-slug> [-r <RELAY_URL>] [--name <SHORTNAME>]
# Example:
heyvm share my-sandbox --name my-shared-sandbox

Flag	Description
`-r, --relay <URL>`	Relay server URL for short ticket codes
`--name <NAME>`	Save the connection URL under this shortname

ssh

SSH into a shared sandbox via its heyo:// ticket URL or a saved shortname.

heyvm ssh <TICKET_URL_OR_SHORTNAME> [-p LOCAL_PORT]
# Example:
heyvm ssh heyo://abc123...
heyvm ssh my-shared-sandbox
heyvm ssh heyo://abc123... -- ls -la /workspace

Flag	Description
`-p, --port <PORT>`	Local port to listen on (default: random)
`-r, --relay <URL>`	Relay server URL for short ticket lookup
`--save <NAME>`	Save this connection under a shortname

You can pass a command after -- to run it in the remote sandbox instead of opening an interactive shell.

Typical workflows

Expose a local service

On machine A (e.g. your laptop): run heyvm proxy start 3000 to expose a local service. Copy the printed heyo:// URL.
On machine B (e.g. a colleague's machine): run heyvm connect <URL> -p 3000 to access that service at localhost:3000.

# On machine A:
heyvm proxy start 3000
# Copy the printed heyo:// URL

# On machine B:
heyvm connect heyo://... -p 3000
# Access the service at localhost:3000

On machine A: run heyvm share my-sandbox to share a sandbox. Copy the printed heyo:// URL.
On machine B: run heyvm ssh <URL> to get an interactive shell in the shared sandbox.

# On machine A:
heyvm share my-sandbox --name pair-session

# On machine B:
heyvm ssh pair-session

Save and reuse connections

Use shortnames to save and reuse connection URLs across sessions.

# Save when proxying
heyvm proxy start 3000 --name dev-server

# Save when connecting
heyvm connect heyo://abc123... --save dev-server

# Add manually
heyvm proxy add dev-server heyo://abc123...

# List saved endpoints
heyvm proxy list

# Connect using shortname
heyvm connect dev-server -p 3000