Sharing sessions

A shared trace is one agent session published on beacon.sh with a link you can send to anyone you choose. It shows the session’s prompts, the agent’s answers and reasoning, and every tool call, command, file edit and MCP call with its result, in order. Secrets are redacted and local paths are made relative before anything leaves your machine. Sharing is always something you turn on. Beacon’s hooks and background jobs never upload a session unless you set up one of the automatic workflows below.

​

Choose a sharing workflow

​

Visibility levels

Every shared trace has one of three visibility levels: Making a trace public always asks for confirmation first, and without a terminal to ask on it is refused unless you pass --yes. Sharing a session again updates the same trace and keeps its visibility unless you name a new one. You can change a trace’s visibility, copy its link or unshare it from the Shared page of the Beacon Cloud dashboard, or from the trace page itself.

​

What a shared trace contains

Every workflow publishes the same thing: a beacon.trace.v1 trace built from the session’s Beacon events, the same projection the local dashboard and lenses read. Before anything is uploaded:

• Every event goes through Beacon’s secret redaction and size limits.
• Paths under the session’s directory are written relative to it, and your home directory becomes ~.
• The working directory and repository path are left out. The project is named by the repository’s or directory’s name, and the remote is sent without credentials.
• Cost is sent only when the runtime reported one, never a list-price estimate.
• On a machine that forwards to Beacon Cloud in Metadata-only mode, prompts, answers, reasoning, tool arguments and output, diffs and the derived title are left out, as forwarding leaves them out. See Metadata-only endpoints.

beacon.sh redacts every string again on its side. Redaction catches common credential shapes, not everything sensitive, so run beacon share --print to read exactly what would be uploaded before sharing a session that touched secrets. beacon share has the full details. Each session has one stable id on beacon.sh (<runtime>:<session-id>), so a session shared more than one way, for example by hand and then by the pre-push hook, is still one trace.

​

Sharing from Beacon Cloud

When an endpoint is connected to Beacon Cloud, its sessions appear in Agent Activity. Open a session and select Share to publish a snapshot of it from the events your device forwarded, with a visibility and an optional title. Update snapshot refreshes it later. What the trace can show depends on the device’s privacy mode: a Metadata-only device forwards no prompts, answers or tool output, so neither does its trace.

​

Credentials

Sharing from the CLI, a skill or the pre-push hook uses the first of these that is available:

1. A Beacon API key passed with --key (bcn_api_...).
2. Your beacon login sign-in, when it carries the traces:write permission. A sign-in from an older beacon login lacks it; run beacon login again.
3. A Beacon API key in the BEACON_API_KEY environment variable.

The credential is sent only in the request’s Authorization header, redirects are refused, and it is never printed or written into config. See Sharing via API Key for creating a key.

​

Related