Skip to content
Get packs

Guide · Open source

How to use bore: expose a local port with a simple TCP tunnel

Updated · written with AI from the project's own documentation and checked against our catalogue data

bore is a small command-line tool that forwards a port on your own machine to a public address, so someone else can reach a web app, API or other TCP service you are running locally. This guide shows how to install it, expose a local port, self-host the server and add a shared secret. It is written for developers who want a quick, simple tunnel and do not need a large feature set.

boreekzhang/bore · ★ 11.6k · MIT

Quick start

  1. 1Install bore. Install with Homebrew on macOS using brew install bore-cli, or with Cargo using cargo install bore-cli. You can also use a prebuilt binary from the releases page.
  2. 2Start your local service. Run the web app or TCP service you want to share on a local port, for example 8000.
  3. 3Open the tunnel. Run bore local with your port and --to bore.pub. Note the remote port bore reports.
  4. 4Share the address. Give the bore.pub address and assigned port to the person who needs to reach your service.
  5. 5Optionally self-host. Run bore server on your own machine and point bore local at it with --to.
  6. 6Optionally add a secret. Pass --secret to both server and client, or set BORE_SECRET, to stop others using your server.

What bore does and what it does not do

bore is a TCP tunnel. It works at the TCP level and is meant to do only one job: forward traffic from a port on your machine to a remote address. The project describes itself as having no more and no less than that.

It is not a web-specific tool. The README does not mention custom domains or HTTP inspection, so do not expect those features.

  • Forwards TCP traffic from a local port to a public address
  • Public server available at bore.pub, or you can run your own
  • Written in Rust and distributed as a single binary for client and server

Install bore on macOS, Linux, Windows or with Docker

The README lists several routes. On macOS, bore is packaged as a Homebrew core formula. The Cargo route needs Rust and Cargo installed first. Prebuilt binaries are available on the releases page for macOS, Windows and Linux; unzip the file for your platform and move the bore executable into a folder on your PATH.

Arch Linux users can install bore from the AUR, and Gentoo users can use the gentoo-zh overlay. The README also publishes Docker images built for AMD 64-bit architecture.

  • Homebrew (macOS): brew install bore-cli
  • Cargo (requires Rust and Cargo): cargo install bore-cli
  • Prebuilt binaries: download from the releases page and place bore on your PATH
  • Arch Linux: yay -S bore (AUR)
brew install bore-cli cargo install bore-cli

Expose a local port with bore local

Start the app you want to share on a local port, then run bore local with that port number and the --to option pointing at the server. The README example uses port 8000 and the public server bore.pub.

bore assigns a random port on the remote server, so your local port will appear at bore.pub with a port number chosen for you. To request a specific remote port, use --port, but the command fails if that port is not available.

  • LOCAL_PORT is a required positional argument
  • --to is mandatory and sets the remote server address
  • --local-host lets you expose a different host on your local network instead of localhost
  • --secret sets the optional authentication secret
bore local 8000 --to bore.pub

Self-host your own bore server

If you do not want to use the public instance, you can run the server on your own network. Start it with bore server, then point bore local at your server with --to.

You can separate the control server from the tunnels by giving different IP addresses. This helps if you want the control server on a private network while tunnels accept connections on a public interface, or the reverse. Port range limits can be set with --min-port and --max-port, with defaults of 1024 and 65535.

  • --min-port defaults to 1024 and --max-port defaults to 65535
  • --bind-addr sets the IP clients must reach, default 0.0.0.0
  • --bind-tunnels sets the IP where tunnels listen, defaults to --bind-addr
bore server

Protect your server with a shared secret

On a custom deployment you can require a secret so others cannot use your server. Clients prove they know the secret during the handshake. The README is explicit that the secret is only used for that initial handshake and that no further traffic is encrypted by default.

If you do not pass --secret, bore will read the BORE_SECRET environment variable instead.

  • Set the same secret on the server and every client
  • Use BORE_SECRET to avoid putting the secret in shell history
# on the server bore server --secret my_secret_string # on the client bore local <LOCAL_PORT> --to <TO> --secret my_secret_string

What people use it for

  • Share a local web app or API with a colleague for a quick test
  • Let someone reach a local TCP service from outside your network
  • Run a self-hosted tunnel server with no extra services to manage
  • Expose a service on a chosen remote port with --port, if that port is free

Frequently asked questions

Is bore free to use?

bore is released under the MIT licence, which the README links from its acknowledgements. The source does not mention prices, so check the repository for current licence terms.

How do I install bore?

On macOS use brew install bore-cli. With Rust installed, you can run cargo install bore-cli. Prebuilt binaries for macOS, Windows and Linux are on the releases page.

Does bore encrypt my traffic?

Not by default. The README says the secret is only used for the initial handshake and that no further traffic is encrypted by default. Do not rely on bore alone for sensitive data.

Can I use bore with custom domains?

The README describes bore as a plain TCP forwarder with no web-specific features, and it does not mention custom domains or HTTP inspection. Pick a different tool if you need those.

How is bore different from ngrok or localtunnel?

The README says bore is similar to localtunnel and ngrok but is intended to be a highly efficient, unopinionated TCP forwarder that is simple to install and easy to self-host. Other comparable projects listed include frp and rathole.

Why does bore local fail when I set --port?

The README says the command will fail if the port you request on the remote server is not available. Try without --port so bore picks a random port, or choose another number.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

bore suits developers who want a quick, simple TCP tunnel to share a local app, especially if they want to self-host a small single binary. It is a poor fit if you need encrypted traffic by default, custom domains, HTTP inspection or detailed access control.

Install options & downloads