Port Forwarding

Some services only listen on the remote machine itself — a database bound to localhost, an internal dashboard, a development server — so you can't reach them from your phone or laptop directly. Port forwarding in Caret tunnels a port through your existing SSH connection so you can, without opening anything to the public internet.

There is no Caret cloud in between: the tunnel runs over the same secure SSH connection you already use for that server.

Quick start: reach a remote service in three steps

Say a dashboard (or database, or dev server) is running on your server but only listens on localhost — so you can't open it from your device. Here's the whole loop, start to finish.

1. On the server: have the service running

Port forwarding needs no special server setup — Caret tunnels over the SSH connection you already use, so there's nothing extra to install and nothing to open in the firewall. You only need to know two things about the service you want to reach:

  • The host it listens on, as seen from the server — usually 127.0.0.1 (the same as localhost).
  • The port it listens on — for example 8080 for a web dashboard, or 5432 for a PostgreSQL database.

If you're not sure it's running, open a terminal on the server in Caret and check — for a web service, curl http://127.0.0.1:8080 should respond.

2. In the app: add the forward

  1. Open the server in Caret and go to its Port Forwarding section.
  2. Tap Add and choose Local.
  3. Fill in:
    • Local port — a free port to open on your device, for example 8080.
    • Destination host — 127.0.0.1 (the service's address as seen from the server).
    • Destination port — the service's port, for example 8080.
  4. Save and switch the forward on. Caret shows the local address to connect to.

3. Access it from your device

Now point your tool at the local address Caret shows — usually 127.0.0.1 and the local port you chose. For a web dashboard, open http://127.0.0.1:8080 in your browser; for a database, point your database client at 127.0.0.1:5432. You're now talking to the service on the server, through the encrypted tunnel.

That's it. Swap in a different service and port and the steps are exactly the same. To expose a port on the server that points back to your device instead, use a reverse forward in step 2 — see below.

Three kinds of forwarding

  • Local forwarding brings a remote service to you. Caret opens a port on your device and quietly sends anything that connects to it across to a service on (or reachable from) the server. You then use the service through Caret's local address — for example, point your database client at 127.0.0.1 and the local port Caret shows, and you're really talking to the database on the server.
  • Reverse forwarding does the opposite: it opens a port on the server that points back to something running on your device or your local network. Use it when something on the server needs to reach a service on your side — for example, to let a teammate's process on the server reach a dev server running on your laptop.
  • Dynamic forwarding (a SOCKS proxy) is a flexible version of local forwarding. Instead of pointing at one fixed service, Caret runs a SOCKS5 proxy on your device; point an app, your browser or your system network settings at it and that app's connections all travel through the server, each to whatever address it asks for — so one proxy covers every destination the server can reach, with no separate forward per service.

If you're not sure which you need, it's almost always local forwarding.

Local forwarding

Local forwarding brings a service that runs on (or near) your server to your device. Caret opens a port on your phone, tablet or Mac; anything that connects to that port is carried over the SSH tunnel to a service the server can reach. This is the everyday case — reaching a database, an internal dashboard or a dev server that only listens on the remote machine.

A worked example — reach a remote database:

  1. Make sure the database is running on the server and note its port — for example 5432 for PostgreSQL. As seen from the server it usually listens on 127.0.0.1.
  2. In Caret, open the server → Port Forwarding → Add → Local.
  3. Fill in:
    • Local port — a free port to open on your device, for example 5432.
    • Destination host — 127.0.0.1 (the address the server reaches the database on; use another machine's address if the database runs elsewhere on the server's network).
    • Destination port — the database's port, 5432.
  4. Save and switch the forward on.
  5. Point your database client at 127.0.0.1:5432 — the local address Caret shows, not the server's address. You're now connected to the database running on the server.

The same pattern works for any service: open http://127.0.0.1:8080 in a browser to reach a dashboard, or point any tool at the local port you chose. If that local port is already taken on your device, pick a different one. The tunnel only lives while the SSH connection is open — if it drops, reconnect and switch the forward back on.

Reverse forwarding

Reverse forwarding goes the other way: it opens a port on the server that points back to a service running on your device or your local network. Reach for it when something on the server needs to call back to your side — for example, letting a process on the server reach a dev server running on your laptop, or handing a remote script access to a service that only runs locally.

A worked example — expose your local dev server to the server:

  1. Make sure your local service is running on your device — for example a dev server on 127.0.0.1:3000 — and reachable from the device Caret is running on.
  2. In Caret, open the server → Port Forwarding → Add → Reverse.
  3. Fill in:
    • Port to open on the server — the port the server should start listening on, for example 3000.
    • Destination host — the address on your side to point back to, usually 127.0.0.1.
    • Destination port — your local service's port, for example 3000.
  4. Save and switch the forward on.
  5. On the server, connect to 127.0.0.1:3000 — for example from the server's terminal in Caret — and you'll reach the service running on your device.

By default the server opens this port on its own loopback, so only the server itself can reach it — not the wider network. Whether it can be reached more widely depends on the address you bind it to and the server's own SSH and firewall settings, so exposing it beyond the server is a deliberate step you take there. Like any forward, it lives only while the SSH connection is open.

Dynamic forwarding (a SOCKS proxy)

Note: Dynamic forwarding is available in the latest version of Caret. If you don't see a Dynamic option in the type picker, update the app.

Local and reverse forwards each point at one fixed destination. Dynamic forwarding is more flexible: Caret runs a SOCKS5 proxy on your device, and any app you point at that proxy has its connections carried through the server — each to whatever address it asks for. It's the same idea as local forwarding, but a single proxy covers every destination the server can reach, so you don't set up a separate forward for each service.

Reach for it when you want to browse internal sites or use tools that need several machines on the server's network, without adding a forward for every one.

A worked example — route a browser through the server:

  1. In Caret, open the server → Port Forwarding → Add → Dynamic.

  2. Fill in:

    • Local address — 127.0.0.1, so the proxy is reachable only from your own device.
    • Local port — a free port to open on your device for the proxy, for example 1080.

    Dynamic forwarding needs no destination — each app picks its own, so there's no remote address or port to enter.

  3. Save and switch the forward on. Caret shows it as a SOCKS5 proxy at the local address and port you chose.

  4. Point an app at the proxy: in your browser's or system's network settings, set the SOCKS5 (SOCKS) proxy to 127.0.0.1 and the local port, for example 1080. That app's traffic now travels through the server and can reach anything the server can — for instance an internal site that only the server's network can open.

Only the apps you point at the proxy use it; everything else on your device connects as normal. Like any forward, the proxy lives only while the SSH connection is open — if it drops, reconnect and switch it back on.

You can set up several forwards on a single server — a mix of local, reverse and dynamic — and switch each one on or off as you need it.

Is anything exposed to the internet?

It depends on the direction. A forward always travels inside your encrypted SSH connection between Caret and the server — it is not a hole in the server's firewall.

  • A local forward opens its port only on your own device, so the remote service is reachable just by you — nothing is published to anyone else.
  • A reverse forward opens a port on the server. By default that port listens on the server's loopback, reachable only from the server itself; but if you bind it to a wider address and the server's SSH and firewall settings allow it, it can become reachable from the server's network — or the public internet. So expose a local service through a reverse forward only when you mean to.
  • A dynamic forward (the SOCKS proxy) opens its port on your own device, just like a local forward. Keep its local address on the loopback (127.0.0.1) and only you can use it; if you bind it to a wider address such as 0.0.0.0 or your device's network address, others on your network could reach the proxy and route their traffic through the server — so do that only on purpose.

When something goes wrong

  • The forward won't connect. Make sure the service is actually running on the server and listening on the exact port your tunnel points at. Try reaching it from the server's own terminal first to confirm it's up.
  • You're connecting to the wrong address. For a local forward, connect to the local address Caret shows (usually 127.0.0.1 and your chosen port), not the server's address.
  • The tunnel stopped. A forward only lives as long as the SSH connection. If the session dropped, reconnect to the server and switch the forward back on.
  • A port is already in use. If the local port you picked is taken by something else on your device, choose a different one.

Still need help?

Tell us your device and its operating system version, the app version (Settings → About), and what you were doing when the problem happened.