> ## Documentation Index
> Fetch the complete documentation index at: https://docs.murmur.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# murmur port-forward

> Tunnel one or more local ports to ports on an agent's VM over SSH — for hitting dev servers, databases, or services running inside an agent.

Opens one or more local TCP tunnels to a running [agent's](/concepts/agents) VM. Each tunnel binds a random local port and forwards traffic to the specified remote port on the VM. Keeps running until you press `Ctrl-C`.

## Synopsis

```bash theme={null}
murmur port-forward [flags] <slug> <port> [port ...]
```

Pass one or more port numbers. Each one creates a separate tunnel. The command prints the local port assigned to each tunnel on startup.

## Arguments

| Name          | Type   | Required | Description                                                                     |
| ------------- | ------ | -------- | ------------------------------------------------------------------------------- |
| `slug`        | string | yes      | The [agent's](/concepts/agents) slug.                                           |
| `port`        | int    | yes      | One or more remote port numbers on the VM (1--65535). At least one is required. |
| `--workspace` | string | no       | [Workspace](/concepts/workspaces) name. Overrides the value from `murmur.yaml`. |
| `--insecure`  | bool   | no       | Connect to the tunnel endpoint without TLS. Default: `false`.                   |

<Warning>
  The `--insecure` flag disables TLS on the tunnel connection. Only use it for local development when the tunnel endpoint does not have a certificate configured.
</Warning>

## Examples

### Forward a single port

```bash theme={null}
murmur port-forward fix-auth 8080
```

```
Tunneling to fix-auth via port-proxy.example.com:443...
✓ localhost:54321 → remote:8080
Press Ctrl-C to close all tunnels.
```

Open `http://localhost:54321` in your browser to reach the service running on port 8080 of the [agent's](/concepts/agents) VM.

### Forward multiple ports

```bash theme={null}
murmur port-forward fix-auth 3000 5432
```

```
Tunneling to fix-auth via port-proxy.example.com:443...
✓ localhost:61200 → remote:3000
✓ localhost:61201 → remote:5432
Press Ctrl-C to close all tunnels.
```

Each remote port gets its own local port. Both tunnels stay open until you press `Ctrl-C`.

### Forward a database port from another workspace

```bash theme={null}
murmur port-forward --workspace data-team etl-runner 5432
```

```
Tunneling to etl-runner via port-proxy.example.com:443...
✓ localhost:52100 → remote:5432
Press Ctrl-C to close all tunnels.
```

## Errors

| Code                                   | Meaning                                                                    | What to do                                                                                               |
| -------------------------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `NOT_FOUND`                            | No [agent](/concepts/agents) with that slug exists.                        | Check the slug. Use [`murmur ls`](/cli/ls) to list running [agents](/concepts/agents).                   |
| `UNAUTHENTICATED`                      | Identity token is missing or expired.                                      | Run `murmur auth` or check your `murmur.local.yaml` configuration.                                       |
| `FAILED_PRECONDITION`                  | The [agent's](/concepts/agents) VM is not running.                         | The [agent](/concepts/agents) may be [sleeping](/concepts/agents). Run [`murmur wake`](/cli/wake) first. |
| `port-forward is not supported on VMs` | You ran `murmur port-forward` from inside an [agent](/concepts/agents) VM. | Run this command from your laptop, not from a VM.                                                        |
| `invalid port`                         | A port argument is not a number or is outside 1--65535.                    | Pass valid port numbers as positional arguments.                                                         |
| `no ports specified`                   | No port arguments were provided.                                           | Add at least one port number after the slug.                                                             |

## Related

* [Agents](/concepts/agents) — concept overview
* [`murmur ssh`](/cli/ssh) — open a terminal on the agent's VM
* [`murmur status`](/cli/status) — check an agent's phase and progress
* [`murmur ls`](/cli/ls) — list running agents
* [`murmur wake`](/cli/wake) — restart a sleeping agent's VM