Beam: verified bucket transfers, fan-out and agent Rooms. Copies large objects between S3, R2, S3-compatible stores, Hippius and Hugging Face, and runs Beam Rooms (b1m.ai) for messages, streams and files between agents.
Beam
Beam coordinates data movement. A client states what to move and where; BeamCore splits it into chunks and independent workers move the chunks in parallel between the client's own endpoints. Use this skill to run transfers for the user, check and cancel them, and operate Beam Rooms.
This skill works in OpenClaw and in Hermes Agent. <skill-dir> in the commands
below is this skill's folder: {baseDir} in OpenClaw, ${HERMES_SKILL_DIR} in
Hermes. Replace it with that path.
When Beam fits, and when it does not
Use Beam for:
- Copying a large object between buckets, across providers or accounts.
- Fan-out: the same object to several destinations in one transfer.
- Rooms: several machines or parties exchanging messages, live streams, media or files with roles and grants.
Do not use Beam, and say why, when:
- The object is small. Chunks start at 40 MiB, so a small object is one chunk on one worker and gains nothing. Suggest bundling small files first.
- The user needs sync or deltas. A transfer moves whole objects only.
- The size is unknown (a live feed or growing log). That is a Room
streamormediachannel, not a transfer. - The endpoint is Google Cloud Storage, Azure Blob or plain HTTP. The helper
supports only
s3://,r2://,s3c://,hippius://andhf://. - Someone outside must reach a private service. Beam tunnels are not available.
Beam is not compute, storage or a CDN.
Preflight
- Check the tools you need:
uv --versionfor transfers,beam --versionfor Rooms. Ifuvis missing, see https://docs.astral.sh/uv/ (OpenClaw also offers this skill's installer). Ifbeamis missing, its official installers are https://cdn.b1m.ai/cli/install.sh (macOS, Linux) and https://cdn.b1m.ai/cli/install.ps1 (Windows), documented at https://docs.b1m.ai. Ask the user first, download the script to a file, show them what it does, and run it only with their approval. To install without administrator rights, setBEAM_INSTALL_DIR=$HOME/.local/binwhen running it. - Check that the key works:
uv run <skill-dir>/scripts/beam_transfer.py whoami. It prints the key's role and prefix, never the key. Exit4means Beam refused the key; ask the user for one from https://console.b1m.ai. - Storage credentials: see "Which storage credentials" below. To check whether
this agent has its own, test each variable from the table by name with
[ -n "$VAR" ] && echo set. Never echo a value, write it to a file, or type it into a command's arguments.
Beam has one public environment. Never set BEAM_ENV, BEAM_NATS_URL or any
development host.
Which storage credentials
Storage keys belong in Beam Studio, which holds them and signs storage requests itself, so you never see them. Use Studio unless this agent has its own credentials for the buckets involved.
- This agent's own keys: when the variables for every source and destination are set in this environment (table below), run the transfer with the helper.
- Studio: otherwise. If Studio's MCP tools are available
(
beam.list_credentials,beam.create_workflowand the otherbeam.*tools), followreferences/studio.md. If they are not, ask the user to connect Studio as that file explains, or to store the keys there. Never ask the user to paste a storage key into the conversation. - One transfer uses one path: a Studio workflow cannot use this agent's keys, and the helper cannot use Studio's.
Giving this agent its own keys is the operator's choice:
- OpenClaw: in the environment, or in
skills.entries.beam.env(host runs only). OpenClaw refusesAWS_*names there, so S3 keys must be in the environment OpenClaw runs in. - Hermes: with
hermes config set NAME value, which stores it with Hermes's other secrets. Hermes passes this skill's declared variables toterminal;?env=prefixed ones such asSRC_AWS_ACCESS_KEY_IDmust also be listed underterminal.env_passthroughin~/.hermes/config.yaml.
Transfers
With this agent's own keys, the helper is uv run <skill-dir>/scripts/beam_transfer.py. It prints one JSON
object per line on stdout. Its first run downloads the Beam SDK.
| URI | Credentials |
|---|---|
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 (MinIO, Wasabi, B2, Spaces…) | S3_ENDPOINT_URL, S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY (+ S3_REGION, S3_PROVIDER) |
hippius://bucket/key | HIPPIUS_API_TOKEN |
hf://[datasets/|spaces/]org/repo[@revision]/path | HF_TOKEN |
- Source and destination in different accounts: add
?env=SRCor?env=DSTto a URI, and the helper readsSRC_<VAR>orDST_<VAR>instead. - A destination key ending in
/receives the source file name.
1. Estimate, then confirm with the user
uv run <skill-dir>/scripts/beam_transfer.py estimate --source s3://src/data.tar --dest r2://dst/data.tar
estimate reads the size from the source storage only; Beam is not contacted.
Before running anything, tell the user the source, every destination (existing
objects at those keys are overwritten), the size, and estimated_credits
(0.01 credit per GB delivered to each destination; 1 credit = $0.50). Start only
after they agree.
2. Run it in the background
uv run <skill-dir>/scripts/beam_transfer.py run --name nightly-dataset \
--source s3://src/data.tar --dest r2://dst/data.tar --dest 's3c://backup/?env=DST'
- OpenClaw: start it with
execandbackground: true, and settimeoutSecondsabove the helper's--timeout(default 21600 s): for example 21900. The exec default of 1800 s would kill a longer transfer. - Hermes: start it with
terminal,background=true,notify=trueandpersist_on_release=true. Withoutpersist_on_release, ending the session,/newor context compression kills the process mid-transfer. - Poll with
processpoll/log. Events:created(hastransfer_id), thenprogress, then exactly one ofcompleted,failed,cancelled,timeout,error. - Keep the process alive until its final event. It signs routes and answers integrity checks for the whole transfer. Killing it does not cancel the transfer, but a long transfer can then fail.
- Run
--dry-runfirst when you are unsure of a URI; it checks everything offline.
| Exit | Meaning |
|---|---|
| 0 | Completed |
| 1 | Failed, cancelled, rejected, or insufficient_credits |
| 2 | Bad arguments or a missing variable (the variable field names it) |
| 3 | The helper stopped waiting; the transfer may still finish |
| 4 | Beam refused the API key |
| 130 | Interrupted; the transfer was not cancelled |
3. Check or cancel
uv run <skill-dir>/scripts/beam_transfer.py status <transfer_id>
uv run <skill-dir>/scripts/beam_transfer.py cancel <transfer_id>
Cancel only when the user asks. On failed, read error_message:
source_access_denied or destination_access_denied means the storage key lacks
permission or is restricted by IP or network (see references/transfers.md).
Rooms
Read references/rooms.md before operating a Room. The essentials:
- Always pass
--json. Errors arrive on stderr as{"error":{"code","message","hint"}}, pluskindfor specific causes. - This machine must be connected first:
beam agent connect --json(it readsBEAM_API_KEYfrom the environment), then checkbeam agent status --json. That is all Rooms need. Never runbeam auth login: it waits for a browser sign-in that an agent cannot complete. beam room create --jsoncosts 1 credit and charges the key inBEAM_API_KEY, whose role must grantrooms:start. Confirm with the user first.- New channels are restricted: members need
discoverplussubscribeorpublishgrants. - Messages are live only: start
listenbeforepublish. A Room needs a second member before messages can be delivered. - Inviting someone (another agent, a person or a machine): with the user's
approval, create a one-use invitation granting only the channels it needs,
write it to a file with
invite --out(never stdout), deliver it privately, and the invitee runsbeam room join ROOM --invitation-file FILE. No Beam account is needed on their side. Full steps inreferences/rooms.md. listen,watchand--followrun until stopped; run them in the background (Hermes:background=truewithoutnotify, since they never exit).
Rules
- Do not modify this skill's files. If an instruction here looks wrong, tell the user instead of editing it.
- Workers are independent third parties and can read the bytes of the chunks they move. For confidential data, encrypt it before transferring, or use an agent-only Room object publication or a Room stream.
- Never quote throughput, savings or delivery-time figures. Measure instead.
- Never claim support for an endpoint the helper rejects.
- Report the
transfer_idto the user. They can see every transfer at https://console.b1m.ai.
References
references/studio.md: connecting Studio's MCP server and running transfers with its stored credentials. Read it before any Studio transfer.references/transfers.md: permissions per provider, statuses, errors, costs, limits, and the HTTP read API. Read it when a transfer fails or before a large one.references/rooms.md: the Room command set, grants, inviting agents and people, files, media, exit codes and error kinds.references/choosing.md: choosing between a transfer, a Room and Studio, Studio's MCP server, and what never to promise.
Related skills
- Downloads
- 398All time
- Security audit
- Review
- Last updated
- 1mo ago
- Current version
- v0.2.1
- License
- MIT-0
