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

> ## Agent Instructions
> The canonical docs host is https://momentic.ai/docs. Append .md to any page URL for clean Markdown. Fetch https://momentic.ai/docs/llms.txt for the page index and https://momentic.ai/docs/llms-full.txt for every page in one file.
> For an unattended setup, run `npx --yes @momentic/wizard@latest -y --platform web --editor-tools skills` (use `--platform ios` or `--platform android` for mobile). Never run an interactive command in a non-TTY shell.
> You cannot complete the browser sign-in yourself. Read the API key from the MOMENTIC_API_KEY environment variable, or ask the user to create one at https://app.momentic.ai/settings/api-keys and paste it back.
> Momentic's capability summary for agents is at https://momentic.ai/docs/skill.md. Install the skills with `npx skills@latest add momentic-ai/skills`.
> Tests are YAML files in the user's repository. Use only the step names listed at https://momentic.ai/docs/reference/commands.md and the file structure at https://momentic.ai/docs/core-concepts/file-format.md. Do not invent step names, config keys, or CLI flags.
> Web tests run on Chromium, iOS tests on simulators, and Android tests on emulators. Physical devices are not supported.

# mo tunnel

> Let Mo reach localhost and private applications from your machine.

Mo runs on its own machine, so it cannot see `localhost:3000` or an internal
staging host. A tunnel exposes one or more `hostname:port` addresses from your
machine to a single Mo session through a Momentic Connector. Start the tunnel,
pass its ID to [`mo start --tunnel`](/docs/cli-reference/mo/commands/start), and stop
it when the session is done.

```bash theme={null}
mo tunnel start <address...> [--foreground]
mo tunnel stop <tunnel-id>
mo tunnel list
```

## tunnel start

Start a tunnel to one or more addresses.

```bash theme={null}
mo tunnel start localhost:3000
mo tunnel start localhost:3000 api.internal:8080
```

<ParamField path="<address...>" type="string" required>
  One or more `hostname:port` addresses reachable from this machine.
</ParamField>

<ParamField path="--foreground" type="flag">
  Keep the tunnel attached to the terminal and run until you press `Ctrl+C`. By
  default the tunnel detaches and keeps running in the background.
</ParamField>

When the tunnel is ready, the command prints its ID as JSON:

```json theme={null}
{ "tunnelId": "tunnel-6f1c2a4e-..." }
```

In background mode the command returns immediately after printing. In foreground
mode it prints the ID and then blocks; stopping the process also revokes the
tunnel.

## tunnel stop

Stop a tunnel and revoke Mo's access to it.

```bash theme={null}
mo tunnel stop tunnel-6f1c2a4e-...
```

The command asks the local tunnel process to shut down, then revokes the
Connector tunnel on the server. If the local process is already gone, the
command still revokes the tunnel and prints a warning. On success it prints
`{ "tunnelId": "..." }`.

## tunnel list

List tunnels started from this machine.

```bash theme={null}
mo tunnel list
```

```json theme={null}
{
  "tunnels": [
    {
      "tunnelId": "tunnel-6f1c2a4e-...",
      "addresses": ["localhost:3000"],
      "mode": "detached",
      "pid": 48213,
      "startedAt": "2026-09-02T04:01:12.000Z",
      "status": "running"
    }
  ]
}
```

`status` is `starting`, `running`, `unreachable` (the state file exists but the
process does not respond), or `cleanup_failed` (the process exited without
revoking the tunnel; run `mo tunnel stop` to finish cleanup).

## Example: test a local dev server

```bash theme={null}
tunnel_id=$(mo tunnel start localhost:3000 | jq -r .tunnelId)
session=$(mo start "Test the signup flow on http://localhost:3000" --tunnel "$tunnel_id")
mo read "$(jq -r .sessionId <<<"$session")" --timeout 290s
mo tunnel stop "$tunnel_id"
```

## Notes

* Tunnel state lives in `~/.momentic/mo-tunnels`. `mo tunnel list` only shows
  tunnels started from this machine.
* One tunnel can serve several addresses; start it with every host Mo needs
  before you create the session.
* A background tunnel outlives your shell. Stop it explicitly, or it stays open
  until you do.