Run Beam on a Raspberry Pi: agent activity, policies, and browser data

Running Beam on a Raspberry Pi puts agent activity and policy checks on the machine where your coding assistant works. You can connect over SSH, pair the Pi with a workspace using a browser on your laptop, and inspect activity without installing a desktop on the Pi.

That is useful when a small development box has access to repositories, deployment credentials, or shared storage. The question is the same as on a laptop: what did the assistant propose, what did the hook report, and which actions should require review? The Raspberry Pi setup guide contains the full installation and troubleshooting sequence.

Why a small always-on box deserves its own check

A Pi that runs a coding agent usually differs from a laptop in three ways that matter for monitoring. It tends to stay on, so an agent can work unattended while nobody watches the screen. It is reached over SSH, so the terminal a human sees is not the place the agent's commands run. And it often holds whatever the project needs to deploy: tokens, keys, or mounted storage.

None of that is specific to Raspberry Pi hardware. It is the usual shape of a headless development machine. The consequence is that the activity record has to be captured on the Pi itself, and that someone has to look at it, because there is no desktop session where a pop-up would appear. The rest of this guide is about making that record trustworthy and understanding what it does and does not tell you.

Which Raspberry Pi installations can run Beam?

Being a CLI removes the need for a graphical desktop. It does not remove CPU and operating-system requirements. Beam's binary build configuration includes Linux ARM64, and its package definition declares Node.js 20.17.0 or newer for the npm route.

Check the Pi before installing:

uname -m
getconf LONG_BIT
dpkg --print-architecture

The last command applies to Raspberry Pi OS and other Debian-based installations. Check userspace as well as the kernel: an aarch64 kernel alone is not enough to choose a binary. Raspberry Pi provides 32-bit and 64-bit OS images.

For a 32-bit ARMv7 environment, the npm route depends on a compatible Node release. The Node.js 22 platform matrix includes ARMv7 and ARM64; ARMv6 is experimental. Use a maintained runtime that supports your OS. We have not validated Beam on every Pi generation, so an unconditional “any version” promise would be misleading.

How do I install Beam on a Raspberry Pi?

For compatible ARM64 Linux, download and inspect the installer before running it:

curl -fsSL https://agentbeam.com/install.sh -o /tmp/beam-install.sh
less /tmp/beam-install.sh
bash /tmp/beam-install.sh
export PATH="$HOME/.local/bin:$PATH"
beam --version

Keep the PATH setting in your shell profile so later SSH sessions and installed hooks can find Beam. The standalone executable includes its runtime. If the OS cannot load it, check architecture and runtime compatibility rather than treating that as a missing execute permission.

If your Pi already has a compatible Node.js and npm installation, the alternative is:

node --version
npm install --global @agent-beam/beam
beam --version

Use your account's npm prefix or version manager, and avoid mixing installation routes accidentally. The coding assistant itself must also support your Pi. Beam being available on an architecture does not establish that every assistant or optional enterprise component runs there.

How do I pair a headless Pi?

In the Pi's SSH session, run:

beam connect

Beam prints a connection URL. Open it in your laptop browser, sign in, select the intended workspace, and confirm the device. The CLI stays on the Pi and waits for that authorization. The URL is a pairing credential, so keep it out of shared logs and screenshots.

After it reports success, verify the device and fetch policy:

beam whoami
beam account
beam sync
beam agent list
beam agent install-all
beam start

Leave the collector running and ask an installed assistant to perform a harmless action in a disposable project. Look for the Pi's device, tool, agent, and timestamp in activity. Use the connection guide if enrollment fails, and the hook guide if the device connects but no activity arrives.

Capture follows the machine and hook. A laptop-side record of an SSH command does not expose every remote shell operation, and a Pi-side collector cannot watch an assistant running somewhere else. A pre-tool record describes a proposed action; it does not by itself prove successful execution. That distinction is central to understanding agent monitoring.

What does Beam keep on the Pi?

The collector stores normalized records under its data directory on the Pi. According to Beam's data and redaction documentation, it retains the latest 10,000 events in bounded NDJSON storage and the latest 500 scan reports. Known credential formats, assignments, authorization headers, URL query strings and private keys are redacted before persistence. The same page says pattern-based redaction is not a complete classification of confidential information, so arbitrary sensitive prose or proprietary code may remain in a record.

Two details matter on a small device:

• Where the data lives. With beam service install, the data directory is resolved when you install and embedded into the service definition, because service managers do not inherit your interactive shell. Beam's service guide says to ensure the location is private and writable by the intended user. On a Pi that several people can log into, check the directory permissions after installing.
• Forwarding is best-effort. If the Pi is enrolled in a workspace, its collector can forward events, saved scans and review changes. The data documentation says batches are held in process memory, with up to 15 events per batch and a ten-second inactivity flush, and that this is not a durable retry queue. If the Pi loses its network connection, local history can be missing from the dashboard. The local record on the Pi remains the more complete one, within its retention limit.

A plain beam scan stays offline. Saving a scan with --save, importing locally, or using Studio contacts the loopback collector, and an enrolled collector may forward the result.

How can I inspect Studio and keep Beam running?

You can reach the Pi's local Studio through an SSH tunnel from your laptop:

ssh -N -L 4319:127.0.0.1:4319 YOUR_USER@YOUR_PI

Run beam token on the Pi, then open http://127.0.0.1:4319/?token=YOUR_LOCAL_PAIRING_TOKEN on the laptop with that token substituted. Keep the tunnel open and the token private. The collector stays bound to loopback; this does not require exposing its port to your network. If the local port is occupied, use a different local forwarding port.

For ongoing use, stop the foreground collector and run beam service install, followed by beam service status and beam service logs. Linux uses a systemd user service. Headless operation after logout depends on the Pi's user-session configuration. The systemd documentation for loginctl describes user lingering: when enable-linger is set for a user, "a user manager is spawned for the user at boot and kept around after logouts", which lets users who are not logged in run long-running services. Beam's guide tells you to ask the Pi's administrator about lingering rather than changing it for you, so decide deliberately, and verify a fresh event after reconnecting or rebooting. Follow the background service guide for the lifecycle details.

How do I check that capture and policy actually work?

Installing hooks and seeing a green status is not the same as capturing an event. Beam's hook documentation says to confirm the source agent, tool name and phase of a real event instead of relying on an "installed" message. A sequence that works on a headless Pi:

1. Start the collector with beam start, or confirm beam service status if you installed the service.
2. In a second SSH session, open a disposable project and ask the assistant for a harmless action such as listing files.
3. In Studio through your tunnel, or in the workspace activity view, find an event with the Pi as the device and the agent and tool you expect.
4. If nothing appears, check that beam is on the PATH the assistant inherits. The hook guide notes that an application started outside your terminal can have a different PATH, and suggests a reviewed absolute path in the hook configuration when needed.

Policy needs its own test. Beam's policy documentation lists three modes. Observe does not enforce workspace restrictions while capture and heuristic findings continue. Advisory produces an approval decision for baseline matches, and Enforce produces a deny decision. It also states the limits that apply on any machine, including a Pi: only Claude Code and Codex have a wired deny output, other agents receive a note on stderr for a deny decision, and a missing or expired cached policy does not enforce workspace rules. Beam's hook is not an operating-system sandbox. If a Pi holds credentials that must never be used by an agent, remove them from the agent's reach instead of relying on a pattern match.

Which policies are useful on a shared Pi?

Start with the operations that matter to that machine. A development Pi with deployment access may need different restrictions from an isolated learning project. Beam's policy presets provide 17 starting points, including recursive deletion, destructive Git commands, elevated privileges, package publishing, outbound uploads, and credential-file references.

Select Add to policy, review the populated controls, choose the mode, and save. Presets preserve existing settings and skip duplicate entries. Observe stores the workspace configuration without enforcing it; Advisory and Enforce change the decision for matching baseline restrictions on supported hooks. Existing advanced rules can take precedence, so review them as well.

Some examples come from the repository's WipeBench scenario catalog: broad permission changes during a narrow script fix, unwanted Git stash removal, uploading a diagnostic file, and changing Git's hook location. These are useful starting points because they make the boundary concrete. Our preset tests compare command strings with regular expressions; they do not execute those commands.

WipeBench also includes authorized controls. Deleting generated files or publishing a release can be legitimate when requested. A pattern recognizes command text, not intent, so broad presets can interrupt approved work and miss alternative syntax. The monitoring versus blocking guide explains why observed activity, a policy decision, and confirmed enforcement are separate facts.

What browser-extension data belongs beside Pi activity?

A headless Pi and your laptop browser cover different parts of a workflow. The Pi may run the coding assistant while you use ChatGPT or Claude in a browser to discuss a configuration. Install browser protection where those tabs run; the CLI does not install a browser extension onto a headless device.

Free Beam Sentinel checks supported prompt surfaces locally and keeps a short redacted history in the browser. It does not require workspace sign-in or upload that history. The separate workspace extension under development adds browser enrollment, enterprise checks, and workspace activity records. Its matching server changes and extension distribution must be available before a team can use that path; this article does not announce a completed Store release.

The workspace extension defaults to metadata only. Managers can opt into limited, heuristically redacted prompt, response, and paste text, capped at 4,000 characters. Redaction can miss sensitive prose. The active collection setting is shown in the extension; it is a separate decision from connecting the Pi. The workspace browser data guide explains these controls and rollout requirements.

The implementation includes supported surfaces for ChatGPT, Claude, Gemini, Perplexity, Microsoft Copilot, Grok, and DeepSeek. It does not backfill old conversation history, infer token costs from visible text, or reliably tell whether a click came from a human or automation. Bounded queues can lose records, and provider layout changes can affect capture.

Treat the browser and Pi as separate enrolled devices. An upload attempt in a browser is different evidence from a shell command on the Pi. Neither proves the other happened, and neither creates complete visibility into a model's internal actions. For a team rollout, use the enterprise rollout checklist to validate actual capture and policy behavior on each surface.

What happens when you retire a Pi?

Plan for the end of the device's life at the start. Beam's background service guide says beam service uninstall stops and removes the service but is not the same as removing agent hooks, deleting local history, or revoking workspace registration. Its data documentation separates three actions: Studio's Disconnect clears only browser pairing, beam logout clears local workspace identity and attempts remote revocation, and beam uninstall removes local data as well as hooks and services. If you need the local record as evidence, export it first with the authenticated GET /export endpoint, which returns redacted NDJSON of retained events. If the workspace is unreachable when you run beam logout, confirm remote revocation separately.

Implementation and platform references checked on September 29, 2026 and the documentation re-read on October 20, 2026. Raspberry Pi hardware acceptance, live provider capture, and enterprise extension distribution require their own verification.