Beam — Programmable Data Movement for Hermes Agent
Connect Hermes Agent to Beam Network
(Bittensor SN105), a decentralized, programmable bandwidth network that enables AI
agents to move, stream, and exchange data across cloud storage, enterprise
applications, and distributed infrastructure.
The Beam plugin allows Hermes agents to interact with Beam directly, enabling
automated data transfers, transfer monitoring, and secure collaboration through
Beam Rooms.
Key capabilities
- Cross-platform data movement: Transfer data between supported cloud storage
platforms and infrastructure: Amazon S3, Cloudflare R2, S3-compatible stores,
Hippius and Hugging Face. - Autonomous transfers: Estimate, initiate, monitor, and manage data transfers
through agent workflows. - Beam Rooms: Enable secure, end-to-end encrypted communication and data
exchange between agents, applications, and connected systems. - Real-time collaboration: Exchange messages, files, and media through shared
Rooms. - Programmable workflows: Integrate data movement into automated, multi-agent
operations without manually managing infrastructure.
Agents need data. Beam moves it.
Documentation: https://docs.b1m.ai
Tools
All tools belong to the beam toolset. Every handler returns JSON and reports
failures as {"error": ..., "kind": ...}.
| Tool | What it does |
|---|---|
beam_account | Checks BEAM_API_KEY against the Beam API: account status, user type, key role and key prefix. Never returns the key. |
beam_transfer_estimate | Reads the source object's size from its storage and estimates the cost (0.01 credit per GB delivered to each destination). Beam is not contacted. |
beam_transfer_start | Starts a transfer in a detached background worker and returns its job_id and Beam transfer_id. Spends credits and overwrites destination objects; requires confirmed: true. |
beam_transfer_status | Beam's status for a transfer, plus the worker's phase and last event for a job started here. |
beam_transfer_list | The organization's recent transfers and the jobs started from this machine. |
beam_transfer_cancel | Cancels a transfer. |
beam_rooms | Operates Beam Rooms through the beam CLI: enroll the machine, list, show, members, channels, grants, invitations, join, publish, media ingest, create (1 credit, requires confirmed: true). |
beam_room_listen | Starts, stops or lists background listeners on Room message channels. |
beam_room_messages | Reads what a listener received, from a cursor. |
The plugin also ships a beam skill (skill_view("beam:beam")) with guidance on
when Beam fits, confirming costs, credentials, Rooms and error handling.
Requirements
- Hermes Agent 0.21.6 or later.
- Python dependencies, installed by Hermes when the plugin is enabled:
beam-network-sdk[s3,r2]andhttpx(seepyproject.toml). - A Beam API key from https://console.b1m.ai. Transfers and Room creation spend
the organization's credits. - For Rooms only: the
beamCLI, installed with the official installer
documented at https://docs.b1m.ai.
Install
hermes plugins install beam
hermes plugins enable beam
hermes config set BEAM_API_KEY b1m_...
To try a local checkout, copy it to ~/.hermes/plugins/beam and run
hermes plugins enable beam. Start a new session afterwards: tools added by a
plugin appear from the next session.
Storage credentials
The transfer tools sign storage access locally with the Beam SDK. They read the
credentials for each endpoint from environment variables named by its URI scheme:
| URI | Variables |
|---|---|
s3://bucket/key | AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY (+ AWS_DEFAULT_REGION, AWS_SESSION_TOKEN) |
r2://bucket/key | R2_ACCESS_KEY_ID, R2_SECRET_ACCESS_KEY, and R2_ACCOUNT_ID or R2_ENDPOINT_URL |
s3c://bucket/key | S3_ENDPOINT_URL, S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY (+ S3_REGION, S3_PROVIDER) |
hippius://bucket/key | HIPPIUS_API_TOKEN (+ HIPPIUS_BASE_URL) |
hf://[datasets/|spaces/]org/repo[@revision]/path | HF_TOKEN (+ HF_ENDPOINT) |
Append ?env=PREFIX to a URI to read PREFIX_<VAR> instead, for example
s3://bucket/key?env=DST reads DST_AWS_ACCESS_KEY_ID. Store variables with
hermes config set NAME value. Keys must not be restricted to IP addresses or
networks: independent workers use the signed routes from their own hosts.
An agent without keys of its own can use Beam Studio instead, which keeps storage
credentials and exposes transfers through its MCP server. The bundled skill
explains that path.
How transfers run
beam_transfer_start validates the URIs and credentials, then starts
python -m beam_hermes.worker run ... in its own session with only the
environment variables that transfer needs (the base variables a process needs to
run, BEAM_API_KEY, and the storage variables its URIs name). The worker creates
the transfer, re-signs routes and answers integrity checks until the transfer
ends, so it keeps running after the Hermes session that started it. Its events
are appended as JSON lines to a file under the plugin's data directory, which
beam_transfer_status reads.
What the plugin does on your machine
- Network. HTTPS to the Beam API (
beamcore.b1m.ai); the Beam SDK's TLS
connection to Beam's transfer gateway while a transfer runs; metadata reads
(object size) from the storage providers named in the URIs. Storage keys never
leave the machine: the SDK signs short-lived, chunk-scoped routes locally. - Your data. Independent third-party Beam workers move the bytes and can
read them, so encrypt confidential data first. A transfer overwrites existing
objects at its destination keys. - Processes. A detached Python worker per transfer, running until the
transfer ends or times out (6 hours by default, 7 days at most), even after the
Hermes session that started it has ended. A detachedbeam ... listenprocess
per Room listener, running until stopped withbeam_room_listen. Short-lived
beam --json ...commands for Room actions andpsto confirm a process is
still the one the plugin started before reporting on or stopping it. - Files. Everything is written under Hermes's per-plugin data directory
(<hermes home>/plugin-data/beam/), owner-only: transfer job records and event
logs, listener message logs, Room invitation tokens (invite), and the WHIP
URL and bearer token frommedia_publish. Tools return the paths of token files,
never the tokens. - Credentials. The plugin reads
BEAM_API_KEYand the storage variables
named by the URIs it is given. Room tools run the installedbeamCLI, which
uses this machine's Beam agent enrollment.agent_connectenrolls the machine
withBEAM_API_KEY. - Spending.
beam_transfer_startandbeam_roomscreatespend
organization credits and refuse to run withoutconfirmed: true, which the
agent passes after asking you; Hermes itself does not prompt. - Reporting. The Beam SDK reports transfer performance timings to Beam. The
plugin never updates itself.
Development
python -m venv .venv && . .venv/bin/activate
pip install -r requirements-dev.txt
python -m pytest
ruff check . && ruff format --check .
The tests make no network calls. On a machine with Hermes installed,
hermes plugins validate . --install-deps and hermes plugins doctor . --ci run
the catalog checks.
License
MIT. Copyright (c) 2026 Beam Network, Fusionblock LLC.
README from the reviewed commit d41448c; it updates when the author re-pins.

Beam-Network