The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu
Go agent-ai-cliagent-harnessesagent-securitybrowser-extensionciclaude-codecloudcodexcursordetection-engineeringjevknowledge-basememorymobile-device-managementobservabilitysecuritysecurity-information-and-event-managementsecurity-toolstelemetrytraces
Document Beacon Cloud sessions, devices, lenses and MCP write access
Claudeafd009c941b5
diff --git a/docs/cli/mcp-connect.mdx b/docs/cli/mcp-connect.mdxindex 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 runsdiff --git a/docs/cloud/devices.mdx b/docs/cloud/devices.mdxnew file mode 100644index 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.mdxnew file mode 100644index 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.mdxnew file mode 100644index 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.mdxnew file mode 100644index 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.mdxnew file mode 100644index 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.mdxnew file mode 100644index 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.mdxindex 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 thatfits, and the data says it was truncated.diff --git a/docs/deployment/managed-mcp.mdx b/docs/deployment/managed-mcp.mdxindex 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```bashbeacon 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 environmentvariable:```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 --checkbeacon 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.mdxindex 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.jsonindex 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",