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

# Sessions and history

> What a session is, when it ends, and how long its history lives.

A **session** is one run of `heymcp share`. It holds the public URL, the
handshake report, and every frame that passed through the tunnel.

## The three states

<CardGroup cols={3}>
  <Card title="Live" icon="circle-play">
    The tunnel is connected. Events are arriving now.
  </Card>

  <Card title="Closed" icon="circle-stop">
    You stopped `heymcp share`, or the connection dropped past the resume
    window. The history is still there to read.
  </Card>

  <Card title="Expired" icon="circle-minus">
    Past the retention window. The session row remains so you can see it
    happened, but the events are gone.
  </Card>
</CardGroup>

An expired session shows *"This one's gone to sleep"* rather than an empty
timeline, so you can tell "nothing happened" apart from "history was pruned".

<h2 id="reconnects-dont-fork-your-history">
  Reconnects don't fork your history
</h2>

Wi-Fi drops, you close the lid, your VPN reconnects. The CLI backs off and
retries, quietly for the first 30 seconds so a blink doesn't fill your terminal
with noise.

If it gets back within **15 minutes**, it resumes the *same* session. Same URL,
same timeline, events simply continue. You don't end up with your afternoon
split across four session rows.

Past that window, the next connection starts a fresh session. Your reserved
slug is unchanged, so the URL in your clients still works.

## Retention

How long events are kept depends on your plan:

| Plan  | Retention |
| ----- | --------- |
| Hobby | 24 hours  |
| Pro   | 7 days    |

**The window is stamped on the session when it opens**, from the plan in force
at that moment. Two consequences, both intentional:

* Upgrading to Pro does not retroactively resurrect yesterday's expired history.
* Downgrading does not delete history you could already see.

Pruning runs hourly and deletes events past the stamped window, leaving the
session row behind.

## Limits on what's captured

The tunnel forwards everything. The *inspector* has bounds, so that a chatty
afternoon can't consume unbounded storage:

|                             | Bound  | What happens past it                                                                                                     |
| --------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------ |
| Event payload               | 256 KB | Truncated in the inspector and flagged. **The full response still reaches the client** — nothing is trimmed on the wire. |
| Events buffered per session | 2,000  | The oldest are dropped, and a visible `DROP` marker appears in the timeline.                                             |

That marker matters. A visible gap in the timeline is worth much more than a
silent one — you'll never read a timeline as complete when it isn't.

## Concurrent tunnels

Hobby allows 3 tunnels open at once, Pro allows 10. Each `heymcp share` is one
tunnel. Closing the terminal closes it.

If you hit the limit, the next `heymcp share` is refused with a message saying
so. `heymcp sessions` shows what's currently live.

## Exporting

History is readable while it lives, but you can take it with you:

```bash theme={null}
heymcp export <session-id> --format json > afternoon.json
```

See [`heymcp export`](/cli/export). The JSON export is lossless — request and
response are stored as separate events precisely so that an export loses
nothing, even though the inspector folds them together for reading.