Skip to content
Get packs

Guide · Open source

How to use Chisel: set up a server, client and tunnel

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

Chisel is a free, open-source command-line tool that forwards network connections between a server and a client. It wraps its traffic in HTTP and encrypts it with SSH, so it can get through firewalls and proxies that block other traffic. This guide shows you how to install it, start a server and a client, and open a tunnel to a service on a private machine.

Chiseljpillora/chisel · ★ 16.7k · MIT

Quick start

  1. 1Install Chisel. On Fedora, run sudo dnf -y install chisel. Otherwise, install with Go using go install github.com/jpillora/chisel@latest.
  2. 2Check the install. Run chisel --help to see the commands: server and client.
  3. 3Start the server. On a reachable machine, run chisel server with a port, for example --port 8080.
  4. 4Set access controls. Create a users file with --authfile or set one user with --auth so only approved clients connect.
  5. 5Connect the client. Run chisel client with the server address and the local port you want to tunnel.
  6. 6Test the tunnel. Open the forwarded port on your client machine and confirm it reaches the service.

What Chisel is and when to use it

Chisel is a single program that runs as either a server or a client. It is written in Go and licensed under MIT. Its README says it is mainly useful for passing through firewalls, and it can also provide a secure entry point into a private network.

  • Reach a service on a private machine from outside its network
  • Get through networks that only allow web-style connections
  • Give admins a simple encrypted entry point into an internal network
  • Run SSH through an HTTP proxy using the stdio ProxyCommand option

Install Chisel

On Fedora, install the packaged version with dnf. The README notes the Fedora package is maintained by the Fedora community. If you have Go installed, you can instead build from source with go install. Docker images are also published on Docker Hub and GitHub Container Registry.

  • Fedora: use the package manager command below
  • Source: requires Go, using the command below
  • Docker: run the image with --help to confirm it works
sudo dnf -y install chisel

Start a Chisel server

Run the server on a machine that other machines can reach. By default the server listens on port 8080 and the host falls back to 0.0.0.0. You can change the port with --port or -p. The server must be hosted somewhere reachable, so this only works if you control such a machine.

To keep the connection secure, share the key fingerprint with clients. You can generate a key with --keygen and load one with --keyfile. Use --authfile or --auth to restrict who can connect.

  • --port or -p sets the HTTP listening port
  • --host sets the listening interface
  • --keygen writes a new PEM-encoded key file
  • --backend proxies normal web requests to another HTTP server
$ chisel server --port $PORT --backend http://example.com

Connect a client and open a tunnel

The client connects to the server and asks it to forward a port. The README example tunnels your localhost:3000 to the server's localhost:3000. Replace the URL with your own server address.

Clients can also create several tunnel endpoints over one TCP connection, and they reconnect automatically with exponential backoff if the link drops.

  • Server address goes first, then the port to tunnel
  • Clients auto-reconnect; tune with --min/max-retry-interval
  • Reverse port forwarding sends connections through the server and out the client
$ chisel client https://<your-app>.fly.dev 3000

Use Chisel as an SSH ProxyCommand

Chisel's stdio mode lets the ssh command route its connection through Chisel. This is useful when SSH traffic must pass through an HTTP proxy. The README lists this as a feature, so check the client help for the exact stdio option before you use it.

  • Works with ssh -o ProxyCommand
  • Lets SSH run over HTTP

Secure and limit access

Chisel encrypts connections using the SSH protocol via crypto/ssh. Clients can be authenticated with a users file, and servers can be checked by fingerprint matching. The users file is a JSON object that maps user:pass to a list of address regular expressions. Patterns are not anchored by default, so anchor them with ^ and $ to avoid over-matching.

TLS can be enabled with --tls-key and --tls-cert. Note that when you use TLS, you must set both flags.

  • --auth sets one user with full access in the form user:pass
  • --authfile points to a users.json file and reloads on change
  • --socks5 allows SOCKS5 access; --reverse allows reverse port forwarding

What people use it for

  • Reach a development web app running on a home computer while away from it
  • Give an admin a single encrypted entry into an internal network
  • Get SSH working on a network that only allows HTTP traffic
  • Expose a private service through a server you control

Frequently asked questions

Is Chisel free to use?

Yes. The project is licensed under MIT, and its README describes it as open-source software that you run yourself. The README does not offer a hosted service.

How do I install Chisel?

On Fedora, run sudo dnf -y install chisel. If you have Go, you can run go install github.com/jpillora/chisel@latest. Docker users can run docker run --rm -it jpillora/chisel --help.

What do I need to run Chisel?

You need Go only if you install from source. You also need a server you control that other machines can reach, because the server side must be hosted somewhere reachable.

Is Chisel a GUI tool?

No. The README only describes command-line usage, so you run Chisel from a terminal.

How is Chisel different from ngrok or frp?

Chisel's README describes it as a single executable that tunnels TCP/UDP over HTTP and secures it with SSH. Comparable projects listed for this item include ngrok, frp, sshuttle and wstunnel. Check each one's documentation to compare features.

Why does my client keep reconnecting?

Chisel clients auto-reconnect with exponential backoff, and keepalive pings detect dead connections. You can tune retry timing with --min-retry-interval and --max-retry-interval, and keepalive with --keepalive.

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

Chisel suits developers, admins and people on restricted networks who can run their own server and want a simple encrypted tunnel. It is not a good fit if you need a hosted service with support or a graphical interface. Choose a managed tunnel product if you want someone else to run the infrastructure.

Install options & downloads