Session context
Tell the viewer what they are looking at, before they ask.
Someone joining a session arrives with no idea what is going on. Context puts the answer beside the terminal instead of in the first five minutes of the call.
porthole host \
--ctx-title "Checkout 500s" \
--ctx-env production \
--ctx-severity high \
--ctx-note "Started after the 14:20 deploy. Rollback is staged but not applied." \
--ctx-link "Runbook=https://wiki.internal/runbooks/checkout" \
--ctx-link "Incident=https://status.internal/inc/4417"The viewer shows this in a sidebar: title, environment and severity badges, your notes, and the links as links.
From a file
For anything you use more than once, put it in YAML:
title: Checkout 500s
environment: production
severity: high
notes: |
Started after the 14:20 deploy.
Rollback is staged but not applied.
links:
- label: Runbook
url: https://wiki.internal/runbooks/checkout
- label: Incident
url: https://status.internal/inc/4417
checklist:
- Confirm the error rate on the dashboard
- Check whether the rollback is safe
- Decide: roll back or patch forwardporthole host --ctx incident.yamlIndividual --ctx-* flags override the corresponding field in the file, so one
document can serve a class of incidents with the specifics on the command line.
Limits
| Field | Limit |
|---|---|
| File size | 64 KiB |
title | 120 characters |
notes | 4,000 characters |
links | 20, label 80 chars, URL 2,048 bytes |
checklist | 50 items, 200 characters each |
Exceeding a limit is an error at startup, not a silent truncation.
Context never touches the signaling server
It arrives over the peer-to-peer DataChannel after the connection is established, not with the session metadata during the handshake.
This is deliberate: context carries incident notes and internal URLs, and those are exactly the kind of thing the server's whole design says it must never see. Sending it during signaling would have been simpler and would have put your internal wiki URLs on the one machine Porthole promises is blind.
In a template
Context is the main reason templates exist. A template can carry the whole document, with placeholders resolved at session start:
context:
title: "Code review — {git:branch}"
environment: "{env:DEPLOY_ENV}"
links:
- label: Repo
url: "{git:repo}"