LocalhostRun

A small Elixir client for localhost.run, which lets you expose local ports to the internet via SSH tunnels.

This can be useful for development, testing webhooks, or sharing a local server with someone. It supports both unauthenticated and authenticated connections using SSH keys or your local SSH agent.

Installation

Add to your mix.exs:

def deps do
  [
    {:localhost_run, "~> 0.1.0"}
  ]
end

Basic Usage

You can use this module in different ways depending on your needs.

Start with GenServer

{:ok, pid} = LocalhostRun.start_link(internal_port: 4000)

As a supervised process

children = [
  {LocalhostRun, [internal_port: 4000]}
]

opts = [strategy: :one_for_one, name: MyApp.Supervisor]
Supervisor.start_link(children, opts)

Manual connection

{:ok, {conn_ref, channel_id}} = LocalhostRun.connect(internal_port: 4000)

receive do
  {:ssh_cm, ^conn_ref, {:data, ^channel_id, 0, message}} ->
    case JSON.decode!(message) do
      %{"event" => "tcpip-forward", "address" => host} ->
        Logger.info("Tunnel established to #{host}")

      %{"event" => "authn", "message" => msg} ->
        Logger.info("Authentication successful: #{msg}")

      %{"message" => msg} ->
        Logger.debug("Received: #{inspect(msg)}")
    end
end

Authentication

To use features like custom domains or longer tunnel timeouts, you’ll need to authenticate with localhost.run.

See their docs for details.

You have two options:

SSH agent

Make sure your SSH agent is running and your key is added:

eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_rsa

Then pass the agent to LocalhostRun:

{:ok, pid} = LocalhostRun.start_link(internal_port: 4000, ssh_options: [
  user: "your_username",
  key_cb: {:ssh_agent, []}
])

SSH key file

Alternatively, you can specify a key file:

{:ok, pid} = LocalhostRun.start_link(internal_port: 4000, ssh_options: [
  user: "your_username",
  key_cb: {:ssh_file, []}
])

Getting the tunnel address

If you need to get the public address of the tunnel:

{:ok, host} = LocalhostRun.get_exposed_host()
IO.puts("Tunnel is available at #{host}")

Logging

The module sets some helpful metadata in your logs:

• :ssh_host
• :ssh_port
• :external_host
• :internal_port

This can help with debugging or tracing tunnel usage.

License

Copyright 2025 Jonatan Männchen
Copyright 2025 Erlang Ecosystem Foundation

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.