Skip to content

The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu

Document Beacon Cloud sessions, devices, lenses and MCP write access

Claudeafd009c941b5
diff --git a/docs/cli/mcp-connect.mdx b/docs/cli/mcp-connect.mdx
index 2ed058ca..6611a5e9 100644
--- a/docs/cli/mcp-connect.mdx
+++ b/docs/cli/mcp-connect.mdx
@@ -25,8 +25,10 @@ with different names, so neither entry ever overwrites the other:
| `beacon` | This machine's `runtime.jsonl` and approved local memory | Locally, over stdio or loopback HTTP | [`beacon mcp doctor`](/cli/mcp-doctor) prints the config |
| `beacon-managed` | Session history this endpoint forwarded to Beacon Cloud | Beacon Cloud, over HTTPS | `beacon mcp connect` |
-Beacon Cloud MCP is read-only. Its tools are `beacon_search_sessions`, `beacon_grep`,
-`beacon_read_session`, `beacon_get_event`, `beacon_lookup` and `beacon_usage`.
+Beacon Cloud MCP reads your forwarded history with `beacon_search_sessions`, `beacon_grep`,
+`beacon_read_session`, `beacon_get_event`, `beacon_lookup` and `beacon_usage`. A connection
+signed in with write access can also publish lenses; see [Beacon Cloud MCP](/deployment/managed-mcp#tools).
+Tokens from `beacon mcp token create` are always read-only.
<Note>
`beacon mcp connect` never runs on an unattended install. The interactive onboarding wizard runs
diff --git a/docs/cloud/devices.mdx b/docs/cloud/devices.mdx
new file mode 100644
index 00000000..c9964398
--- /dev/null
+++ b/docs/cloud/devices.mdx
@@ -0,0 +1,75 @@
+---
+title: "Connect devices"
+description: "Enroll a machine in Beacon Cloud, check that it is forwarding, and revoke it"
+---
+
+A device is one machine running Beacon that forwards its sessions to your Beacon Cloud account.
+Each device has its own key, so you can revoke one without touching the others.
+
+## Connect a device
+
+On the machine, sign in and connect:
+
+```bash
+beacon login
+beacon endpoint connect
+```
+
+`beacon login` opens your browser to sign in. Signing in alone sends no telemetry.
+`beacon endpoint connect` registers the device with your account, stores its key locally and starts
+forwarding. If you run `beacon endpoint install` interactively and choose Beacon Cloud, it does
+both steps for you.
+
+Each time a device connects, Beacon also uploads the sessions it already found on
+disk from the last 30 days, so recent work appears right away. Pass `--no-backfill` to skip that.
+
+<Tip>
+ To set up a device with a coding agent, paste this into it:
+ `Read https://beacon.sh/start.md then set me up on Beacon`
+</Tip>
+
+For system-wide installs, privacy modes, offline buffering and every flag, see the
+[`beacon endpoint connect` reference](/cli/endpoint-connect).
+
+## Check a device
+
+The **Devices** page at [beacon.sh/dashboard/devices](https://beacon.sh/dashboard/devices) lists
+every device registered to your account, with its hostname, install ID, key prefix, when it was
+created and when Beacon last heard from it. A new device reads **Waiting for first event** until
+its first batch arrives.
+
+On the machine itself:
+
+```bash
+beacon endpoint status
+```
+
+reports whether the forwarder is running and whether Beacon Cloud accepts the device key.
+
+## Revoke a device
+
+Select **Revoke device** on the device's card. Beacon Cloud rejects that device's uploads
+immediately. History it already sent stays in your account.
+
+A revoked key cannot be restored. To bring the machine back, run `beacon endpoint connect` again
+to enroll it with a new key.
+
+To stop forwarding from the machine itself, run:
+
+```bash
+beacon endpoint disconnect
+```
+
+This stops the forwarder and deletes the local key. It does not revoke the key in Beacon Cloud, so
+revoke it on the **Devices** page too if the machine is lost or retired.
+
+## Related
+
+<Columns cols={2}>
+ <Card title="Sessions" icon="list" href="/cloud/sessions">
+ Read what your connected devices recorded.
+ </Card>
+ <Card title="Beacon Cloud forwarding" icon="tower-broadcast" href="/log-forwarding/asymptote">
+ What leaves a device and how it is sent.
+ </Card>
+</Columns>
diff --git a/docs/cloud/lenses/adding-lenses.mdx b/docs/cloud/lenses/adding-lenses.mdx
new file mode 100644
index 00000000..e24e44c0
--- /dev/null
+++ b/docs/cloud/lenses/adding-lenses.mdx
@@ -0,0 +1,68 @@
+---
+title: "Adding lenses"
+description: "Browse the lens marketplace, try a lens, and keep it open on every session"
+---
+
+A lens is a focused view of one session: the files it changed, what it cost, what a reviewer should
+look at. Beacon Cloud ships built-in lenses, and anyone can publish more to the marketplace. Add a
+lens once and it is available on every session you open.
+
+## Built-in lenses
+
+Every session already has these. Select **+** on a session's tab bar to open one.
+
+| Lens | What it shows |
+| --- | --- |
+| **Activity** | Actions, commands, failures and findings |
+| **Files Changed** | Created, edited and deleted files |
+| **Token Usage** | Usage and cost signals by model |
+| **Security Review** | Sensitive and consequential activity |
+| **Approvals & Policy** | Operator and policy decisions |
+| **Skills** | Skills loaded during the session |
+| **MCP Calls** | Calls grouped by server and tool |
+
+## Browse the marketplace
+
+The marketplace at [beacon.sh/lenses](https://beacon.sh/lenses) lists every public lens. Each card
+shows the lens's author, how many people installed it and its current version. You can browse
+without signing in.
+
+## Try a lens before adding it
+
+Select a card to open the lens's page at `/lenses/<key>`. It shows the description, the author and
+the current version, and a **Live preview** that runs the lens against a sample session, so you can
+see what it does before it touches your own data.
+
+## Add a lens
+
+Select **Add lens** on the lens's page. You need to be signed in.
+
+<Warning>
+ A lens written by someone else can read every session you open it on, including prompts, code
+ and tool output. Beacon blocks lenses from sending anything out, but only add lenses from
+ authors you trust.
+</Warning>
+
+Added lenses belong to your account, not to a session. To remove one, select **Remove lens** on the
+same page.
+
+## Lenses on the session page
+
+On a session, select **+** to open the lens menu. Built-in lenses come first, then the lenses you
+added under **Installed**. Each lens you open becomes a tab next to **Full session**; select **×**
+to close it. Beacon remembers your open tabs in this browser.
+
+The selected lens is kept in the URL as `?lens=<key>`, so you can share a link that opens straight
+to it. The person you share it with sees the lens only if they have added it too; otherwise Beacon
+asks them to add it from the marketplace.
+
+## Related
+
+<Columns cols={2}>
+ <Card title="Creating lenses" icon="wand-magic-sparkles" href="/cloud/lenses/creating-lenses">
+ Build a lens with your coding agent or upload one.
+ </Card>
+ <Card title="Managing lenses" icon="sliders" href="/cloud/lenses/managing-lenses">
+ Release new versions and choose who can find a lens.
+ </Card>
+</Columns>
diff --git a/docs/cloud/lenses/creating-lenses.mdx b/docs/cloud/lenses/creating-lenses.mdx
new file mode 100644
index 00000000..e04c73e9
--- /dev/null
+++ b/docs/cloud/lenses/creating-lenses.mdx
@@ -0,0 +1,85 @@
+---
+title: "Creating lenses"
+description: "Build a lens with your coding agent, or upload one in the web app"
+---
+
+A lens is one self-contained HTML file. You can have your coding agent build and publish it, or
+upload a file yourself.
+
+## Build a lens with your agent
+
+The marketplace at [beacon.sh/lenses](https://beacon.sh/lenses) and the create page both have a
+**Copy prompt** button. It copies:
+
+```text
+Read & follow https://beacon.sh/lenses.md to start building a lens. Use the Beacon MCP to publish and manage it.
+```
+
+Paste it into your agent and add a sentence describing what the lens should show.
+[`beacon.sh/lenses.md`](https://beacon.sh/lenses.md) is the full guide: the file rules, the data
+your lens receives, and the publishing steps.
+
+To publish, the agent needs [Beacon Cloud MCP](/deployment/managed-mcp) with write access. See
+[Lenses with MCP](/cloud/lenses/lenses-mcp).
+
+## Upload a lens in the web app
+
+Select **Create a lens** on the marketplace, or go to
+[beacon.sh/lenses/create](https://beacon.sh/lenses/create). You need to be signed in.
+
+| Field | |
+| --- | --- |
+| **Title** | Display name, up to 100 characters. |
+| **Key** | Permanent, globally unique ID used in URLs. Filled in from the title; 3–64 lowercase letters, numbers or hyphens. |
+| **Description** | Optional, up to 500 characters. Shown on the marketplace card and the lens page. |
+| **HTML file** | A single `.html` file, up to 16 MiB. |
+| **Who can discover this lens?** | **Just me**, or **Everyone — list in the marketplace**. |
+
+Select **Create lens**. The file becomes version `1.0.0`, it is released, and it is added to your
+own sessions straight away.
+
+Some keys are reserved for built-in lenses, such as `activity`, `files-changed` and `token-usage`.
+
+## File requirements
+
+- One HTML file with a `<head>` element, up to 16 MiB, with all CSS and JavaScript inline.
+- No external resources: no `<link>`, `<iframe>`, `<object>`, `<embed>` or `<base>`, no remote
+ scripts, fonts or images, no CSS `@import`. Use inline SVG, canvas or `data:` URIs.
+- No network: `fetch`, `XMLHttpRequest`, WebSockets, `EventSource`, WebRTC and form submission
+ are blocked.
+- No navigation. A lens that tries to leave its frame is closed.
+- No Content Security Policy of your own. Beacon injects the sandbox policy.
+
+Beacon checks these rules when you upload and rejects a file that breaks them.
+
+## Getting the session data
+
+Your lens gets the session from one call:
+
+```js
+const { trace, messages, truncated } = await window.traces.getTrace()
+```
+
+`window.beacon` is the same object. The call resolves once, with the session's metadata in `trace`
+and its activity as `messages`, each with typed `parts`: `text`, `thinking`, `tool_call`,
+`tool_result`, `error` and `system_event`. The full type is in
+[`beacon.sh/lenses.md`](https://beacon.sh/lenses.md).
+
+Treat every value as untrusted: insert it with `textContent`, never `innerHTML`.
+
+<Note>
+ Beacon Cloud lenses use this Traces-compatible format. Lenses for the
+ [local dashboard](/concepts/lenses) receive Beacon's `LensDataV1` instead, so a local lens file
+ needs changes before it works in Beacon Cloud.
+</Note>
+
+## Related
+
+<Columns cols={2}>
+ <Card title="Lenses with MCP" icon="plug" href="/cloud/lenses/lenses-mcp">
+ Let your agent publish and release lenses.
+ </Card>
+ <Card title="Managing lenses" icon="sliders" href="/cloud/lenses/managing-lenses">
+ Release new versions and change who can find a lens.
+ </Card>
+</Columns>
diff --git a/docs/cloud/lenses/lenses-mcp.mdx b/docs/cloud/lenses/lenses-mcp.mdx
new file mode 100644
index 00000000..cab7786e
--- /dev/null
+++ b/docs/cloud/lenses/lenses-mcp.mdx
@@ -0,0 +1,91 @@
+---
+title: "Lenses with MCP"
+description: "Let your coding agent create, upload, release and publish lenses"
+---
+
+[Beacon Cloud MCP](/deployment/managed-mcp) lets your coding agent do everything with a lens that
+you can: create it, upload versions, release one, and choose who can find it.
+
+## Before you start
+
+- **Connect Beacon Cloud MCP** with `beacon mcp connect`, or add `https://mcp.beacon.sh` to your
+ client by hand. See [Beacon Cloud MCP](/deployment/managed-mcp#connect).
+- **Allow write access.** When your client signs in, the Beacon approval page offers a
+ checkbox to also let it create and publish lenses. Tick it, then select **Allow read and write
+ access**. Read-only connections cannot see the lens tools that change anything.
+- **Give the agent a shell.** The HTML file is uploaded with an HTTP request such as `curl`, never
+ pasted into a tool call.
+
+<Note>
+ Access tokens created with `beacon mcp token create` are always read-only. Use browser sign-in
+ to publish lenses.
+</Note>
+
+## Lens tools
+
+| Tool | What it does | Access |
+| --- | --- | --- |
+| `beacon_lenses_list` | Lists your lenses, the lenses you added, or the marketplace | Read |
+| `beacon_lenses_create` | Creates a lens: key, title, description, icon and visibility | Write |
+| `beacon_lenses_prepare_upload` | Reserves a new version and returns a single-use upload URL | Write |
+| `beacon_lenses_complete_upload` | Finishes an upload. The version stays a draft | Write |
+| `beacon_lenses_release_version` | Makes a version current | Write |
+| `beacon_lenses_update` | Changes title, description, icon or visibility | Write |
+
+## Publish a new lens
+
+Ask your agent to build and publish a lens, for example:
+
+```text
+Read & follow https://beacon.sh/lenses.md to start building a lens. Use the Beacon MCP to publish
+and manage it. The lens should show every failed command and what the agent did next.
+```
+
+The agent then:
+
+1. Writes the HTML file, following [the file rules](/cloud/lenses/creating-lenses#file-requirements).
+2. Creates the lens with `beacon_lenses_create`. It is private unless you ask otherwise.
+3. Calls `beacon_lenses_prepare_upload` with a version such as `1.0.0` and gets an upload URL.
+4. Uploads the file to that URL:
+ ```bash
+ curl -X POST -H "Content-Type: text/html" --data-binary @lens.html "<uploadUrl>"
+ ```
+ The response carries an `artifactId`.
+5. Calls `beacon_lenses_complete_upload` with that `artifactId`.
+6. Releases the version with `beacon_lenses_release_version` once you approve, and gives you the
+ lens page link, `https://beacon.sh/lenses/<key>`.
+
+Upload URLs expire after 15 minutes and work once. If an upload fails, the agent can prepare the
+same version again.
+
+## Update an existing lens
+
+Ask the agent to change the lens. It uploads the new file as a new version, such as `1.0.1`,
+completes it, and releases it when you say so. Versions are immutable, so a version number cannot
+be reused.
+
+Uploading alone changes nothing for anyone using the lens. Only a release does.
+
+## Roll back
+
+Ask the agent to release an earlier version:
+
+```text
+Roll my failed-commands lens back to 1.0.0.
+```
+
+## Change details or visibility
+
+Ask the agent to rename the lens, change its description or icon, or make it public or private.
+It calls `beacon_lenses_update`. The key cannot change.
+
+## Related
+
+<Columns cols={2}>
+ <Card title="Beacon Cloud MCP" icon="plug" href="/deployment/managed-mcp">
+ Connect your agent and see every tool.
+ </Card>
+ <Card title="Managing lenses" icon="sliders" href="/cloud/lenses/managing-lenses">
+ Versions, releases and visibility.
+ </Card>
+</Columns>
diff --git a/docs/cloud/lenses/managing-lenses.mdx b/docs/cloud/lenses/managing-lenses.mdx
new file mode 100644
index 00000000..72382b1f
--- /dev/null
+++ b/docs/cloud/lenses/managing-lenses.mdx
@@ -0,0 +1,65 @@
+---
+title: "Managing lenses"
+description: "Upload new versions, change the current version, and choose who can find a lens"
+---
+
+After you create a lens, you can change its details, upload new versions, roll back, and decide
+whether it is listed in the marketplace. You manage lenses through
+[Beacon Cloud MCP](/cloud/lenses/lenses-mcp): ask your agent, and it calls the tools for you.
+
+Only the lens's owner can change it.
+
+## Change details
+
+The title, description and icon can change at any time. Ask your agent, for example:
+
+```text
+Rename my files-changed-plus lens to "Files Changed+" and update its description.
+```
+
+The key is permanent. To use a different key, create a new lens.
+
+## Upload a new version
+
+Every upload is a new, immutable version with its own semantic version number, such as `1.0.1`
+or `1.1.0`. A version number can be used only once, so to change the HTML, upload another version.
+
+Uploading a version does not change what anyone sees. It stays a draft until you release it.
+
+## Release or roll back
+
+Releasing a version makes it the **current version**: the one the lens page, the marketplace and
+everyone who added the lens see. Releasing takes effect immediately.
+
+To roll back, release an earlier version. Nothing is re-uploaded, and every version stays
+available to release again.
+
+## Who can see a lens
+
+| Visibility | Who can see and add it |
+| --- | --- |
+| **Private** | Only you. New lenses are private unless you choose otherwise. |
+| **Public** | Everyone. The lens is listed in the marketplace once it has a released version. |
+
+Change visibility by asking your agent, for example "Make my token-heatmap lens public."
+
+Making a public lens private removes it from the marketplace straight away, and it disappears from
+the sessions of everyone else who added it. You keep it.
+
+## Your lenses
+
+Ask your agent to list your lenses. It shows every lens you own, public or private, with its
+current version. You can also list the lenses you added, or browse the marketplace, the same way.
+
+Lenses cannot be deleted yet. To retire one, make it private.
+
+## Related
+
+<Columns cols={2}>
+ <Card title="Lenses with MCP" icon="plug" href="/cloud/lenses/lenses-mcp">
+ The tools and the publishing flow your agent uses.
+ </Card>
+ <Card title="Creating lenses" icon="wand-magic-sparkles" href="/cloud/lenses/creating-lenses">
+ File rules and the session data a lens receives.
+ </Card>
+</Columns>
diff --git a/docs/cloud/sessions.mdx b/docs/cloud/sessions.mdx
new file mode 100644
index 00000000..a1998aa7
--- /dev/null
+++ b/docs/cloud/sessions.mdx
@@ -0,0 +1,59 @@
+---
+title: "Sessions"
+description: "Find, filter and read your agent sessions in Beacon Cloud"
+---
+
+Every session your connected devices forward lands in **Agent Activity** at
+[beacon.sh/dashboard/sessions](https://beacon.sh/dashboard/sessions). It is the first page you see
+after signing in.
+
+## Find a session
+
+- **Search** matches session text, repositories, devices and models.
+- **Date range** shows the last 24 hours, 7 days or 30 days.
+- **Filters** narrow by device, agent harness, model, severity, activity category and repository.
+- **Quick filters** jump to sessions that need review, are high risk, ran commands, wrote files or
+ called MCP tools.
+
+By default the list shows **Captured sessions**: sessions with real activity. Switch to **All
+sessions**, **Recurring sessions** or **Empty sessions** to see the rest.
+
+Press <kbd>F</kbd> anywhere in the dashboard to jump to a page.
+
+## Read a session
+
+Open a session to see who ran it, on which device and harness, with which model, in which
+repository and branch, and what it cost in tokens.
+
+Below that is the activity timeline: every prompt, response, tool call, command, file edit, MCP
+call and approval in order. Use the type pills to focus on one kind of event, search within the
+session, and open the **JSON** drawer on any event to see exactly what Beacon recorded.
+
+What you can read depends on the device's [privacy mode](/deployment/managed#what-leaves-your-machine).
+A Metadata-only device shows what happened, but not the prompt, output or diff.
+
+## View a session through a lens
+
+The tabs above the timeline are lenses. **Full session** is the timeline itself. Select **+** to add
+a lens such as **Files Changed**, **Token Usage** or **Security Review**, or one you installed from
+the marketplace. The open lens is kept in the page URL as `?lens=<key>`, so a link opens straight
+to it.
+
+See [Adding lenses](/cloud/lenses/adding-lenses).
+
+## Search from your agent
+
+Everything on this page is also available to the agent you are working in through
+[Beacon Cloud MCP](/deployment/managed-mcp). Ask it to find a session, and it can search, grep and
+read your history without you leaving the terminal.
+
+## Related
+
+<Columns cols={2}>
+ <Card title="Adding lenses" icon="layer-group" href="/cloud/lenses/adding-lenses">
+ Add focused views to every session.
+ </Card>
+ <Card title="Beacon Cloud MCP" icon="plug" href="/deployment/managed-mcp">
+ Search your sessions from Claude Code, Cursor, Codex and more.
+ </Card>
+</Columns>
diff --git a/docs/concepts/lenses.mdx b/docs/concepts/lenses.mdx
index 3f3d36d3..63c9bf28 100644
--- a/docs/concepts/lenses.mdx
+++ b/docs/concepts/lenses.mdx
@@ -128,7 +128,8 @@ window.beacon.getTrace().then(function (data) {
- A lens is one file of at most 16 MiB, with everything inline.
- A lens sees one trace. A view across several sessions is not supported yet.
-- Lenses are local. The store is per user on this machine, and there is no hosted gallery
- or sharing; to share a lens, share the file.
+- Lenses in the local dashboard are local. The store is per user on this machine; to share a
+ local lens, share the file. Beacon Cloud has its own [lens marketplace](/cloud/lenses/adding-lenses),
+ whose lenses use a different data format (see [Creating lenses](/cloud/lenses/creating-lenses#getting-the-session-data)).
- Very large traces are cut to fit: the lens receives the longest prefix of events that
fits, and the data says it was truncated.
diff --git a/docs/deployment/managed-mcp.mdx b/docs/deployment/managed-mcp.mdx
index 1600ca64..fd5fc98c 100644
--- a/docs/deployment/managed-mcp.mdx
+++ b/docs/deployment/managed-mcp.mdx
@@ -1,111 +1,155 @@
---
-title: "MCP"
-description: "Search your Beacon Cloud agent history from the assistants you already use"
+title: "Beacon Cloud MCP"
+sidebarTitle: "MCP"
+description: "Search your agent history and publish lenses from the assistants you already use"
---
-Beacon Cloud MCP lets an assistant search and read the agent history you forward to Beacon
-Cloud. Use it to find a past session, recover a command or tool result, revisit work across
-different harnesses, and inspect token usage without leaving your current agent.
+Beacon Cloud MCP connects the agent you are working in to your Beacon Cloud history. It can find a
+past session, recover a command or tool result, compare work across harnesses, review token usage,
+and [publish lenses](/cloud/lenses/lenses-mcp) for you.
-The server is read-only. It cannot change endpoint configuration, edit a session, or run a tool
-on your machine.
+The server is hosted at `https://mcp.beacon.sh`. It uses Streamable HTTP and OAuth, so there is
+nothing to run locally and no key to paste.
-## Before you connect
+## Connect
-You need:
+You need Beacon [connected to Beacon Cloud](/cloud/devices) so there is history to search. If you
+chose Beacon Cloud during `beacon endpoint install`, the installer has already offered to connect
+MCP for you.
-- Beacon installed and [connected to Beacon Cloud](/cli/endpoint-connect)
-- At least one supported MCP client on the machine
-- A Beacon account with access to the forwarded history
-
-<Note>
- Connecting an endpoint and connecting MCP are separate choices. Endpoint onboarding does not
- add an MCP server to your harnesses.
-</Note>
-
-## Connect your agents
-
-Run:
+### Automatic setup
```bash
beacon mcp connect
```
-Beacon discovers supported harnesses, shows every configuration change it plans to make, and asks
-before writing. Each changed file is backed up first.
+Beacon finds the supported harnesses on the machine (Claude Code, Codex CLI, Cursor, VS Code,
+Gemini CLI, OpenCode and Oh My Pi), shows every change it plans to make, and asks before writing. Each
+changed file is backed up first. The server is added as **`beacon-managed`**, with only its URL.
+
+Restart any harness that is already running, then sign in from it the first time:
+
+- **Claude Code:** run `/mcp` and choose `beacon-managed`.
+- **Codex CLI:** run `codex mcp login beacon-managed`.
+- **Cursor:** open **Cursor Settings → MCP** and sign in to `beacon-managed`.
+- **VS Code:** run **MCP: List Servers** and start `beacon-managed`.
+- **Gemini CLI:** run `/mcp auth beacon-managed`.
+- **OpenCode:** run `opencode mcp auth beacon-managed`.
+- **Oh My Pi:** run `/mcp reauth beacon-managed`.
+
+Each opens the Beacon approval page in your browser.
+
+### Manual setup
+
+<Tabs>
+ <Tab title="Claude Code">
+ ```bash
+ claude mcp add --transport http --scope user beacon-managed https://mcp.beacon.sh
+ ```
+ Then run `/mcp`, choose `beacon-managed`, and approve access in the browser.
+ </Tab>
+ <Tab title="Codex CLI">
+ ```bash
+ codex mcp add beacon-managed --url https://mcp.beacon.sh
+ codex mcp login beacon-managed
+ ```
+ </Tab>
+ <Tab title="Cursor">
+ Add to `~/.cursor/mcp.json`:
+ ```json
+ {
+ "mcpServers": {
+ "beacon-managed": { "url": "https://mcp.beacon.sh" }
+ }
+ }
+ ```
+ Cursor shows the server as needing login. Select it to approve access in the browser.
+ </Tab>
+ <Tab title="VS Code">
+ Add to `.vscode/mcp.json`:
+ ```json
+ {
+ "servers": {
+ "beacon-managed": { "type": "http", "url": "https://mcp.beacon.sh" }
+ }
+ }
+ ```
+ Start the server from **MCP: List Servers** and approve access in the browser.
+ </Tab>
+ <Tab title="Gemini CLI">
+ ```bash
+ gemini mcp add --scope user --transport http beacon-managed https://mcp.beacon.sh
+ ```
+ Then run `/mcp auth beacon-managed`.
+ </Tab>
+ <Tab title="OpenCode">
+ Add to `~/.config/opencode/opencode.json`:
+ ```json
+ {
+ "$schema": "https://opencode.ai/config.json",
+ "mcp": {
+ "beacon-managed": { "type": "remote", "url": "https://mcp.beacon.sh", "enabled": true }
+ }
+ }
+ ```
+ Then run `opencode mcp auth beacon-managed`.
+ </Tab>
+</Tabs>
+
+For other harnesses and every command flag, see the [`beacon mcp connect` reference](/cli/mcp-connect).
+
+### Verify
+
+Ask your agent:
-The server appears as **`beacon-managed`**. By default, Beacon writes only the server URL. Each
-harness asks you to sign in with OAuth the first time it connects.
-
-<Accordion title="Example">
```text
-Beacon Cloud MCP: https://mcp.beacon.sh (checked)
-Server name: beacon-managed
-Auth: OAuth; Beacon writes only the URL, and each harness signs in on first use
-
-HARNESS ACTION AUTH
-Claude Code add oauth
-Cursor add oauth
-OpenCode add oauth
+List my five most recent Beacon sessions.
```
-</Accordion>
-
-After connecting, restart any harness that is already running. Then sign in from that harness:
-- **Claude Code:** Run `/mcp` and choose `beacon-managed`.
-- **Codex CLI:** Run `codex mcp login beacon-managed`.
-- **Cursor:** Open **Cursor Settings → MCP**, find `beacon-managed`, and sign in.
-- **VS Code:** Run **MCP: List Servers** and start `beacon-managed`.
-- **Gemini CLI:** Run `/mcp auth beacon-managed`.
-- **OpenCode:** Run `opencode mcp auth beacon-managed`.
-- **Oh My Pi:** Run `/mcp reauth beacon-managed`. Until you do, Oh My Pi reports the server as
- failing to connect each time it starts.
+## Read or write access
-For supported configuration formats, manual setup for other harnesses, and all command flags, see
-the [`beacon mcp connect` reference](/cli/mcp-connect).
+When your client signs in, the Beacon approval page asks what to allow:
-## What your agent can do
+- **Read** is always granted. The agent can search and read your sessions: prompts, responses,
+ tool calls and output, commands and file edits.
+- **Write** is optional and only offered when the client asks for it. Tick the checkbox to let the
+ agent create, upload, release and publish lenses under your account.
-Beacon Cloud MCP exposes tools for:
+Neither lets the agent change your sessions, your devices, or anything on your machine, or read
+anyone else's data. A tool that needs write access is hidden from read-only connections.
-- searching sessions by text and structured filters
-- grepping retained prompts, responses, commands, tool calls, and results
-- reading a session timeline
-- retrieving one event by identifier
-- looking up related history
-- reviewing token usage
+## Tools
-Try prompts such as:
+| Tool | What it does |
+| --- | --- |
+| `beacon_search_sessions` | Lists sessions by text and filters: time, harness, repository, model, device, needs review |
+| `beacon_grep` | Searches prompts, responses, commands, tool calls and results with a regular expression |
+| `beacon_read_session` | Reads a window of one session's timeline, or the events around one event |
+| `beacon_get_event` | Returns one event in full |
+| `beacon_lookup` | Lists the harnesses, repositories, models and devices you can filter on |
+| `beacon_usage` | Summarizes token usage and reported cost by model, harness, repository or day |
+| `beacon_lenses_list` | Lists your lenses, the lenses you added, or the marketplace |
+| `beacon_lenses_*` | Create, upload, release and update lenses (write access). See [Lenses with MCP](/cloud/lenses/lenses-mcp) |
-- “Find the session where I fixed the release workflow last week.”
-- “Show me the command that resolved the failing Go test.”
-- “Search my Claude Code and Cursor history for changes to the MCP connection flow.”
-- “Summarize token usage for this repository over the past seven days.”
+Time filters accept a relative window such as `24h`, `7d` or `2w`, or exact `after` and `before`
+dates. `beacon_read_session` also accepts a dashboard session URL.
-Results are limited to history your account can access in Beacon Cloud.
+Agents work best when they search first and then read only the part of a session they need.
-## Privacy and retention
+## Example prompts
-MCP can return only what the endpoint forwarded.
+- "Find the session where I fixed the release workflow last week."
+- "Show me the command that resolved the failing Go test."
+- "Search my Claude Code and Cursor history for changes to the MCP connection flow."
+- "Summarize token usage for this repository over the past seven days, by model."
+- "Build a lens that shows every failed command and publish it." (needs write access)
-- **Standard mode** sends locally retained content, including prompts, responses, tool arguments
- and results, subject to Beacon's redaction and size limits.
-- **Metadata-only mode** removes prompts, responses, reasoning, tool arguments and results,
- command output, diffs, and inventory content before upload. Content search and session reading
- are therefore limited in this mode.
+Session titles and summaries are metadata. For exact claims about commands, files or errors, have
+the agent read the events.
-Beacon caps each retained string at 4 KB before writing it locally. Text beyond that limit is not
-available to Beacon Cloud MCP.
+## Access tokens
-See [Beacon Cloud forwarding](/log-forwarding/asymptote#what-leaves-the-machine) and
-[retention and redaction](/security/retention-redaction) for the complete data flow.
-
-## Authentication options
-
-OAuth is the recommended default. Beacon writes no secret into harness configuration, and you
-approve access in the browser.
-
-If a harness cannot use MCP OAuth, create a personal MCP token and keep it in an environment
+If a harness cannot sign in with OAuth, create a personal MCP token and keep it in an environment
variable:
```bash
@@ -113,8 +157,26 @@ export BEACON_MCP_TOKEN="$(beacon mcp token create --name laptop)"
beacon mcp connect --token-env BEACON_MCP_TOKEN
```
-Beacon writes only the environment variable reference, never the token value. Tokens can be
-revoked from **beacon.sh → Dashboard → MCP Access**.
+Beacon writes only the variable's name into the harness configuration, never the token.
+
+- Tokens from `beacon mcp token create` are **read-only**. Use OAuth to publish lenses.
+- Tokens start with `bcn_mcp_`, are shown once, and expire after 90 days by default
+ (`--expires-in-days`, up to 366, or `0` for never).
+- You can have up to 25 active tokens.
+
+## Security
+
+- **Session content is data, not instructions.** Your history can contain text that looks like
+ instructions, including prompt injection captured from a tool result. Keep your agent's
+ confirmations on for actions that change systems or send data out.
+- **You see only your own history.** Results are limited to sessions forwarded from your devices.
+- **Privacy modes apply.** MCP returns only what a device forwarded. A Metadata-only device sends
+ no prompts, responses, tool arguments or output, so there is nothing to grep. Retained strings
+ are capped at 4 KB on the device before forwarding.
+- **Connect only to `https://mcp.beacon.sh`.**
+
+See [Beacon Cloud forwarding](/log-forwarding/asymptote#what-leaves-the-machine) and
+[retention and redaction](/security/retention-redaction) for the full data flow.
## Check or remove the connection
@@ -123,34 +185,35 @@ beacon mcp status --check
beacon mcp disconnect
```
-`status` reports which harnesses are configured and can verify the server URL. `disconnect`
-removes only entries previously written by Beacon; it leaves MCP entries you created yourself
-untouched.
+`status` reports which harnesses are configured and checks the server. `disconnect` removes only
+the entries Beacon wrote, and leaves MCP entries you added yourself untouched.
-## Beacon Cloud and local MCP
+## Troubleshooting
-Beacon offers two separate MCP servers:
+- **Authentication needed.** Restart the sign-in from your client, for example `/mcp` in Claude
+ Code.
+- **Lens tools are missing.** The connection is read-only. Sign in again and tick the lens
+ checkbox on the approval page.
+- **No results.** Check that the session appears at [beacon.sh](https://beacon.sh/dashboard), widen
+ the time window, and use `beacon_lookup` to get exact harness and repository names.
+- **Config changes not picked up.** Restart the harness.
-| Server | Data | Connection |
-|---|---|---|
-| `beacon-managed` | History forwarded to Beacon Cloud across connected endpoints | Hosted HTTPS server configured with `beacon mcp connect` |
-| `beacon` | This machine's local runtime log and approved local memory | Local stdio or loopback server configured with `beacon mcp doctor` |
+## Beacon Cloud and local MCP
+
+Beacon has two MCP servers. Use either, or both.
-Use both if you want cross-device managed history and direct access to this machine's local data.
+| Server | Data | Set up with |
+| --- | --- | --- |
+| `beacon-managed` | History forwarded to Beacon Cloud from all your devices | `beacon mcp connect` |
+| `beacon` | This machine's local runtime log and approved local memory | [`beacon mcp doctor`](/cli/mcp) |
## Related
<Columns cols={2}>
- <Card title="Beacon Cloud" icon="cloud" href="/deployment/managed">
- Learn about hosted storage, search, analytics, and long-term agent history.
- </Card>
- <Card title="beacon mcp connect" icon="plug" href="/cli/mcp-connect">
- Review every command, flag, supported harness, and configuration format.
- </Card>
- <Card title="Beacon Cloud forwarding" icon="tower-broadcast" href="/log-forwarding/asymptote">
- Understand what leaves an endpoint and how forwarding works.
+ <Card title="Lenses with MCP" icon="layer-group" href="/cloud/lenses/lenses-mcp">
+ Have your agent build, publish and release lenses.
</Card>
- <Card title="Local Beacon MCP" icon="server" href="/cli/mcp">
- Search the runtime log and approved memory stored on this machine.
+ <Card title="beacon mcp connect" icon="terminal" href="/cli/mcp-connect">
+ Every flag, supported harness and configuration format.
</Card>
</Columns>
diff --git a/docs/deployment/managed.mdx b/docs/deployment/managed.mdx
index 09a41dd3..b5d1ce7a 100644
--- a/docs/deployment/managed.mdx
+++ b/docs/deployment/managed.mdx
@@ -1,46 +1,82 @@
---
title: "Beacon Cloud"
-description: "Hosted storage, search, and long-term history for your agent sessions"
+description: "One place for every agent session across your devices and harnesses"
---
-The easiest way to use Beacon without running your own backend.
-
-Beacon Cloud gives individual developers hosted storage, search, and long-term history for their agent sessions.
-
-Install Beacon, connect your account, and your traces are automatically available in one place across the agents you use.
-
-## What Beacon Cloud gives you
-
-| Capability | Beacon Cloud |
-| --- | --- |
-| Hosted ingest | Send Beacon traces to a managed backend |
-| Unlimited retention | Keep your agent history over time |
-| Search | Find past sessions, prompts, commands, and tool calls |
-| Cross-harness history | See activity from Claude Code, Cursor, Codex, and more in one place |
-| Analytics | Understand usage, tokens, workflows, and runtime behavior |
-| Knowledge | Surface recurring workflows, corrections, and useful patterns |
-| No backend to run | Asymptote handles storage and infrastructure |
-
-## One place for all your agent history
-
-Your agent history is usually split across different tools and local session files.
-
-Beacon Cloud brings those traces together into one searchable timeline, so you can quickly find past work, revisit how you solved something, and compare sessions across harnesses.
-
-## Keep what your agents learn
-
-The more you use agents, the more useful history you create.
-
-Beacon Cloud keeps that history over time so successful workflows, debugging patterns, repeated corrections, and repository knowledge do not disappear when a session ends.
-
-## Bring that history back into your agents
-
-Connect [Beacon Cloud MCP](/deployment/managed-mcp) to search and read your forwarded session
-history from Claude Code, Cursor, Codex CLI, and other MCP clients. The server is read-only and
-uses OAuth by default, so Beacon writes only its URL into supported harness configurations.
-
-## Start in minutes
-
-Install Beacon, connect to Beacon Cloud, and keep using your existing agents.
-
-No database, storage bucket, or indexing infrastructure required.
+Beacon Cloud is the hosted home for your agent history. Connect a device, and the sessions Beacon
+records from Claude Code, Cursor, Codex CLI and every other supported harness show up at
+[beacon.sh](https://beacon.sh), searchable and kept over time.
+
+You keep using your agents exactly as before. Beacon Cloud stores and indexes the history for you,
+so there is no database, bucket or pipeline to run.
+
+## What you get
+
+- **Sessions.** Every forwarded session on one timeline, with filters for device, harness, model,
+ repository and risk. Open a session to read its prompts, commands, tool calls and file edits.
+- **Lenses.** Focused views of a session, such as files changed, token spend or security
+ findings. Use the built-in lenses, add more from the [marketplace](/cloud/lenses/adding-lenses),
+ or [build your own](/cloud/lenses/creating-lenses).
+- **MCP.** Let the agent you are working in search and read your past sessions, and publish lenses
+ for you. See [Beacon Cloud MCP](/deployment/managed-mcp).
+- **Analytics.** Token usage and cost by model, agent activity over time, and the harnesses,
+ models and repositories you use most.
+- **Findings and inventory.** Threat-rule findings with their evidence, plus the configs, MCP
+ servers, skills and hooks each device reports.
+- **Profile.** An optional public page of aggregate activity. See
+ [Configure your profile](/manage/profile).
+
+## Get started
+
+<Steps>
+ <Step title="Install Beacon">
+ Follow the [quickstart](/get-started/quickstart) for macOS, Linux or Windows.
+ </Step>
+ <Step title="Sign in and connect">
+ ```bash
+ beacon login
+ beacon endpoint connect
+ ```
+ The interactive installer (`beacon endpoint install`) does both for you when you choose
+ Beacon Cloud. See [Connect devices](/cloud/devices).
+ </Step>
+ <Step title="Open your sessions">
+ Go to [beacon.sh/dashboard](https://beacon.sh/dashboard). Sessions from the last 30 days on
+ the device are uploaded when it connects, so the dashboard is not empty on day one.
+ </Step>
+ <Step title="Connect MCP (optional)">
+ ```bash
+ beacon mcp connect
+ ```
+ See [Beacon Cloud MCP](/deployment/managed-mcp).
+ </Step>
+</Steps>
+
+## What leaves your machine
+
+Beacon records locally first. Only a connected device forwards, and you choose how much it sends:
+
+- **Standard** sends retained content, such as prompts, responses, tool arguments and results,
+ after local redaction and size limits.
+- **Metadata-only** strips prompts, responses, reasoning, tool arguments and results, command
+ output, diffs and inventory content on the device, before anything is uploaded.
+
+See [Beacon Cloud forwarding](/log-forwarding/asymptote#what-leaves-the-machine) for the full data
+flow.
+
+## Related
+
+<Columns cols={2}>
+ <Card title="Connect devices" icon="laptop" href="/cloud/devices">
+ Enroll a machine, check that it is forwarding, and revoke it.
+ </Card>
+ <Card title="Sessions" icon="list" href="/cloud/sessions">
+ Find, filter and read your agent sessions.
+ </Card>
+ <Card title="Lenses" icon="layer-group" href="/cloud/lenses/adding-lenses">
+ Add focused views to every session.
+ </Card>
+ <Card title="Beacon Cloud MCP" icon="plug" href="/deployment/managed-mcp">
+ Bring your history into the agent you are using.
+ </Card>
+</Columns>
diff --git a/docs/docs.json b/docs/docs.json
index 6052acee..04440f66 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -56,8 +56,27 @@
"icon": "cloud-arrow-up",
"pages": [
"deployment/hosting-options",
- "deployment/open-source",
- "deployment/managed"
+ "deployment/open-source"
+ ]
+ },
+ {
+ "group": "Beacon Cloud",
+ "icon": "cloud",
+ "pages": [
+ "deployment/managed",
+ "cloud/devices",
+ "cloud/sessions",
+ "deployment/managed-mcp",
+ {
+ "group": "Lenses",
+ "pages": [
+ "cloud/lenses/adding-lenses",
+ "cloud/lenses/creating-lenses",
+ "cloud/lenses/managing-lenses",
+ "cloud/lenses/lenses-mcp"
+ ]
+ },
+ "manage/profile"
]
},
{
@@ -93,8 +112,6 @@
"group": "Manage Beacon",
"icon": "sliders",
"pages": [
- "deployment/managed-mcp",
- "manage/profile",
{
"group": "Inventory",
"root": "guides/inventory",