---
title: "Port forwarding"
description: "Use Alpacon port forwarding to reach a server service from your machine. Learn the login and work-session requirements, how tunnels end, and what is recorded."
---

> Full documentation index: https://docs.alpacax.com/llms.txt

# Port forwarding

Use port forwarding to reach a service on a server from a local TCP port.

## Service requirements

Port forwarding connects a local TCP port to a service on a server, such as a database or web application. The service must be reachable on the server's `127.0.0.1`; a service listening only on `::1` cannot be reached. Follow [Open a tunnel](/use/work-sessions/tunnels/open/) to connect.

## What a tunnel needs

- The server's **Tunnel** setting must be enabled by an administrator. See [server settings](/use/servers/manage/#tunnel-and-code-editor).
- An active work session must include the target server and **Port forwarding** (`tunnel`).
- Sign in with `alpacon login` without `-t`. Service tokens and personal API tokens cannot open tunnels.
- The server must support tunnels. If enabling the setting reports an agent requirement, ask an administrator to upgrade Alpamon. See the [CLI reference](/reference/cli/tunnel/) for platform requirements.

## When a tunnel ends

Press Ctrl+C to close a standalone tunnel. If you started a [local command with the tunnel](/use/work-sessions/tunnels/open/#run-a-local-command-with-the-tunnel), it closes when that command exits.

A tunnel also ends when its work session completes, expires, or is revoked. A standalone CLI tunnel prints `Error: tunnel connection lost: session closed by remote` and exits 1. Start another approved session before reconnecting.

With `-- COMMAND`, a remote close prints `Warning: Tunnel closed: session closed by remote` and interrupts the local command. Check the local command's result before retrying.

## What is recorded

Tunnel traffic is forwarded but not captured. In live activity, **Tunnels have no recording** explains this limit. The session history records who opened the tunnel and when it closed, with the account, port, and client type.

Look for **Opened port forwarding** and **Closed port forwarding** in [live activity](/use/live-activity/). Use [troubleshooting](/use/work-sessions/tunnels/troubleshooting/) if opening or keeping a tunnel fails.

Source: https://docs.alpacax.com/use/work-sessions/tunnels/