Beam for Agents

Use this guide to assess a client's architecture, discover opportunities for Beam, and turn them into a credible technical or commercial proposal. It is both a capability model and an architecture/sales-assistance playbook: identify where Beam helps, explain why, and name what must be confirmed before a client commits.

This page is deliberately conceptual. It carries almost no code. When you need an exact signature, a field name, or a working example, fetch it:

Read this page for judgement. Fetch those for syntax.

1. What Beam is

Beam is an open coordination layer for bandwidth.

A client expresses intent — move these bytes, from here, to there, under these conditions — and a network of independent operators competes to deliver it. Beam coordinates delivery using measured performance. It addresses problems such as slow or duplicated transfers, fragmented connectivity, and bandwidth that applications cannot easily discover or use.

Cloud egress can be a significant cost, but rates vary by provider, region, volume and route. Beam does not automatically remove a source provider's charges. Assess the client's actual bill and workload before promising savings.

Five roles separate coordination, execution and verification:

Beam runs as Bittensor subnet 105. This is useful context for questions about the underlying network; most client integrations use Beam's client interfaces without operating a subnet participant.

The structural fact to carry into a design conversation is that clients do not have to select or manage delivery workers themselves. They use Beam's APIs, SDKs and agents. Client-operated agents can connect directly to assigned delivery infrastructure, so distinguish this programming abstraction from the actual data path described in section 4.

2. The five primitives

Beam can be understood through five primitives. Each has a distinct interface, trust model and set of limits. Select the one that fits the job, then confirm support for the chosen client and release.

Transfer — move bytes between endpoints

Source ──▶ Destination

A transfer names one or more sources and destinations, with a known, finite source size before planning. Depending on the interface, the caller supplies size information or the SDK obtains it from the source. Beam plans chunks and can distribute delivery across workers. Parallel delivery can improve completion time when the object, endpoints and available network capacity permit it.

Interfaces: server SDKs (Python, TypeScript, Go, Rust), HTTP API, CLI and Studio. The browser SDK exposes transfers through its broker integration; it does not require storage secrets in frontend code.

Fan-out — the same bytes to many destinations

              ┌──▶ Destination A
Source ───────┼──▶ Destination B
              ├──▶ Destination C
              └──▶ Destination D

Fan-out is the transfer API with more than one entry in destinations. It is particularly relevant to a client running N sequential copies of the same dataset. Validate the combined source and destination capacity, completion requirements and cost against the existing process.

Multiple entries in sources represent multiple source objects. They do not implicitly merge files, calculate deltas or synchronize directories. Provider combinations have limits; for example, the reviewed Hugging Face destination path requires a single source object.

Room — a private group of machines and buckets

                   ROOM
      Agent ───────────────── Bucket
        │                       │
        │                       │
     Agent ──────────────── Web Agent

A Room is a permissioned group for exchanging messages, streams, media and objects. Members include enrolled machines running the Beam agent and object-storage buckets attached through an organization-scoped credential. Browsers can participate through a Web Agent and share that instance's identity and grants.

A Room has roles, per-channel grants, bounded invitations, and channels of six kinds: message, stream, datagram, request-reply, media, object. Not every client exposes every channel kind.

Two properties make Rooms useful for integration:

• Invitation-based joining can avoid a personal Beam account. An invitation can bootstrap a machine identity with granted roles and channels. That invitation-only identity cannot create Rooms. The Room still needs a payer.
• A bucket can participate without sharing its storage secret with other members. The configured Studio service resolves and uses the credential. Treat that signing service as a trusted part of the client's deployment.

Interfaces: CLI (beam room …), the local agent API, the browser Web Agent for supported operations, and Studio, including bucket membership management. The protection of an object publication depends on its source and recipients; see section 4.

Tunnel — reach a private resource from outside

Private resource ──▶ Beam Tunnel ──▶ Remote consumer

The machine holding the resource establishes an outbound connection. An inbound port on that origin does not need to be opened. This helps machines behind NAT participate, provided the network permits the required outbound connections.

A tunnel can expose a file, an HTTP service, a stream, a WebRTC endpoint, a TCP address, or a receive directory for inbound files. For a public HTTPS endpoint, use the URL returned by Beam when the tunnel is created. Copy that URL exactly rather than constructing a hostname. Consumers do not need a Beam installation to use the endpoint, but access still depends on its authentication policy and the application behind it. Closing the tunnel stops serving the resource through that endpoint.

A file source or receive directory can also expose an authenticated S3-compatible interface for supported object operations. This lets compatible clients, including Beam's SDK, use a local resource as a transfer endpoint. It is not a promise of every S3 bucket operation or arbitrary directory-source support. Native public TCP is separate from hostname-based HTTPS ingress.

Interface: CLI (beam tunnel …) driving the local agent.

Stream — live and continuously produced data

Source ~~~~~~▶ Consumers

Rooms provide live-data facilities:

• stream channels carry byte streams between compatible agents.
• datagram channels carry bounded individual payloads, suited to workloads that accept the selected delivery and loss behavior.
• media channels expose WHIP ingest for an encoder such as OBS and WHEP playback for viewers. Named publishers can share a channel; subscribers can select publishers through the supported client interface.
• A tunnel can also expose a stream or WebRTC endpoint without a Room.

Live data does not need a declared total byte length. Session lifetimes, idle limits, backpressure and reconnect behavior still apply. A producer that does not know its final size may fit a stream or media channel, provided those limits meet the client's needs. Do not promise the completion, durability or verification contract of an object transfer for a live stream.

3. Room vs Tunnel

Tunnel = make a resource reachable. Consumers use an endpoint. They do not need Room membership; endpoint authentication and application permissions still apply.

Room = organize ongoing exchange. Members have identities, roles and channel grants, and can exchange several kinds of data.

Tunnel:  A ──▶ endpoint ──▶ allowed consumer

Room:        A
           ↙   ↘
          B     C
           ↘   ↙
             D

If the client's problem is "somebody outside needs to get at this one thing", consider a tunnel. If it is "these parties keep exchanging data and need shared membership and permissions", consider a Room. Some architectures benefit from both: a Room for ongoing collaboration and tunnels for specific resources.

Participant count is a useful discovery signal, not a rule. Two participants can benefit from a Room, and many destinations can be served by a fan-out without creating one.

4. Where the bytes actually go

Separate coordination from delivery, and identify the trust boundary for the chosen path. In provider transfers, workers move bulk data between source and destination endpoints. Room agents connect to delivery infrastructure; tunnels and media can use gateways or relays. Do not describe every Beam primitive as having the same direct path or promise that payload never traverses Beam-operated infrastructure.

Workers are third parties. What they can read depends on the selected mode:

Three consequences matter to a client:

1. Keep long-lived storage secrets in the trusted signing application. Supported provider adapters sign through the client's SDK process or configured Studio service. Workers receive prepared access routes rather than those signing secrets. Client-supplied HTTP headers and URLs need their own access review.
2. Signed URLs are access capabilities, not content encryption. Their scope, expiry and reuse behavior depend on the provider. An assigned chunk does not establish a universal one-chunk access restriction, and a small chunk may be the whole object. Keep usable URLs and tokens out of public examples and logs. If unknown intermediaries must not read the content, use client-side encryption or an appropriate protected agent-only object publication.
3. Check protection per publication. A bucket source or recipient selects transport protection for that object publication, including its agent recipients. The presence of a bucket elsewhere in the Room does not by itself determine every channel's protection. Check the reported protection mode before sending sensitive content.

Completion and integrity verification also depend on the provider and operation. Confirm the required checks and final object availability instead of assuming one multipart-completion mechanism or one verification guarantee for all paths.

5. What Beam can connect to

Start with the client's real endpoints and required operations. A provider name, credential form or SDK type is not proof that every operation is supported.

A service lacking a native adapter may still be usable through a properly authorized HTTP endpoint or a compatible storage interface. Validate that specific route before promising GCS, Azure or any other provider.

Studio's storage profiles simplify configuration for services such as MinIO/AIStor, Wasabi, Backblaze B2, DigitalOcean Spaces and other S3-compatible systems. Many profiles use the same driver and require an endpoint. They are configuration options, not independent compatibility certifications.

Studio workflow actions extend beyond data movement. Concrete examples include Slack messaging, Salesforce queries and record operations, HTTP requests, and Zapier tool calls. Studio also has credential definitions for services including Adobe AEP, Snowflake and Databricks; credential support alone does not establish a ready-to-run operational connector. Identify the actual action or API call the workflow will execute.

Local resources can participate through tunnel file-source or receive-directory endpoints, including supported S3-compatible operations. Check the required read/write direction and operations rather than assuming a local directory behaves like a complete cloud bucket.

Use the connector documentation to choose a candidate, then confirm operation support in the selected interface and release. A small end-to-end test is the final check.

6. How a client drives Beam

Pick per job, not once. A client can use the SDK inside a service and Studio for scheduled workflows. The Console provides account, credit, API-key and transfer views; local Studio run history and other surfaces should be checked in their respective interfaces.

The agent-native surface

Studio's MCP server exposes capability-scoped tools, including read:transfers, write:transfers, run:transfers, read:runs, cancel:runs, write:schedules, read:credentials and read:api_keys. The reviewed tools cover Room discovery and bucket membership, workflow creation and updates, execution/retry/cancellation, transfers, schedules and status. The read-credential and read-key surfaces expose safe previews or metadata, not a general ability to retrieve raw secrets. The service binds to loopback by default; deployment configuration can change that.

An agent can automate supported operations using configured credential references without receiving storage secrets itself. Grant only the tools needed for the intended work and follow the client's authorization policy for spending, publishing endpoints and executing actions. Do not assume MCP exposes every Room channel operation.

The browser Web SDK has two different trust models:

• The Beam broker client obtains short-lived scoped access tokens through a publishable client key, a backend token endpoint or a supplied token callback. Keep long-lived Beam API keys and storage secrets on the trusted server.
• The WebAgent client authenticates to a Web Agent instance, and browsers using that instance share its identity and grants. Its instance credential belongs in a trusted application flow, not a public bundle. The SDK rejects long-lived Beam API keys, agent credentials and Studio delegations as substitutes.

From a proposal to a first test

Retain the operation identifiers needed to inspect progress. Request acceptance is not delivery completion. Check partial results before retrying, especially when a workflow action has external side effects.

7. Hard limits, and what Beam is not

Check constraints before recommending a fit. Distinguish the selected interface's current limits from a statement about all of Beam.

Size: a transfer constraint, not a Beam constraint

Sized delivery and live streaming are separate paths.

Unknown-length video, audio or sensor output may fit live channels. For an append-only log or event feed, also establish whether loss, replay, ordering and reconnect behavior meet the application's requirements.

If a client needs transfer-style chunked delivery and object completion checks but cannot know the source length, finalize finite objects first or choose a live path with a different completion contract. Do not promise that the two paths provide identical verification.

Other constraints on transfers

• Parallelism is workload-dependent. Small objects may provide little scope for parallel delivery. Measure them in the intended workflow; aggregation can help when per-object overhead dominates. Chunk selection and supported limits depend on the service, provider and release.
• Object transfer is not automatic delta synchronization. For "only what changed", directory synchronization or deduplication requirements, identify which client or workflow computes the changes and submits the resulting objects.
• Confirm billing authorization. Account-backed operations need an authorized account or API key and sufficient credits. Invitation-only Room members use the Room's configured payer.
• R2 range-read compatibility — observed 24 September 2026. Some R2 multipart objects with nonconsecutive part numbers returned incomplete partial reads crossing an upload boundary, even though full-object reads succeeded. Validate range reads on the actual source objects; a full-file checksum alone does not establish this behavior. Confirm the current limitation and workaround with Beam before relying on affected objects.
• Support is operation-specific. SDK types and Studio profiles do not prove a working adapter. Check section 5 and the actual release before naming a provider in a proposal.

Constraints on Rooms, tunnels and browsers

The current direct browser interface does not provide a supported MLS enrollment path. The Web Agent handles protected data on the browser's behalf, so that server is part of the trust boundary.

Do not recommend a general browser byte-stream integration without a documented, supported client path. Live-channel duration, idle limits, backpressure and reconnect behavior vary by interface. "No declared size" never means unlimited duration or durable replay.

Additional limits:

• Exposing a machine's private resource requires an agent process on that machine; a browser-only application cannot perform that role. A browser can consume a compatible public endpoint.
• Native public TCP is not supported by hostname-based HTTPS ingress. Use the supported relay path for TCP and validate its client requirements.
• Creating a Room requires billing authorization. Member identity and grants determine access; the configured API key determines the payer.
• Object publication requires all selected recipients to finish by default. Partial delivery must be explicitly allowed and inspected.
• A grant, signed route or session can expire or be revoked. Design status, cancellation and reconnect handling for the selected interface.

What Beam is not

• A substitute for general-purpose compute. Studio can execute supported workflow actions, but moving training data does not provide a training cluster.
• A long-term storage service. Destinations, agent inboxes and workflow artifacts can retain data; confirm their storage and retention policies.
• A guarantee of durable messaging, replay or exactly-once external effects. Evaluate channel and workflow behavior against the client's requirements.
• A promise of CDN edge caching.
• Unlimited capacity. Validate volume, concurrency and geography against the current service and workload.

Claims never to make

Do not promise that no intermediary can see plaintext, that no component retains data, or that all Beam paths share one encryption or routing model. Do not quote throughput, capacity, availability or savings without supporting evidence and scope. Do not treat acknowledgement as delivery or promise an undocumented delivery guarantee. Explain the overlap and differences when comparing Rooms, tunnels or Studio with existing products. Recommend only the capabilities that materially improve the client's architecture.

8. Finding where Beam fits

Start by mapping where data moves, gets duplicated, gets staged, or waits. A client may describe a slow business process, an integration burden or a cloud bill before describing a transfer problem. Look for these signals.

Signals for Transfer or Fan-out

• The same dataset is copied to several destinations, one after another.
• A dataset crosses cloud providers, or moves between cloud and on-premise.
• Models, checkpoints, embeddings, container images or media masters are distributed to multiple regions or teams.
• Someone waits on a transfer before a business process or a compute job starts.
• Cloud egress cost is a line item people complain about.
• Data is staged into temporary storage purely to move it somewhere else.
• Teams download and re-upload the same datasets repeatedly.

Signals for a Room

• Several parties exchange data on a recurring basis.
• Separate point-to-point integrations exist between pairs of participants.
• Different participants need different permissions over the same data.
• Partners or customers need onboarding without accounts in the client's systems.
• A bespoke central relay is maintained primarily to coordinate data exchange.
• A bucket needs to participate in ongoing exchange, beyond one delivery.

Signals for a Tunnel

• A private service must be reachable by something outside the network.
• Developers expose services through temporary public infrastructure, or through a VPN that exists only for that.
• A machine cannot accept inbound connections — NAT, restrictive network, edge device — but can establish the required outbound connection.
• One file on one machine needs to reach one person, once.

Signals for a Stream

• Continuously produced data is currently handled by polling, by writing a series of small files, or by a bespoke central relay.
• Several consumers need the same live feed at the same time.
• Live media has to reach viewers with a real encoder in front of it.
• The producer does not know how many bytes it will emit. Audio, video, sensor output, an append-only log, a tail of events. Consider a live channel, then verify its delivery and lifecycle behavior. The known-size requirement applies to transfers, not every Beam primitive.

Signals for Studio

• The work is a pipeline, with conditions, retries, schedules and several steps.
• The client needs a run history a non-engineer can read.
• Non-storage systems are in the loop, such as Salesforce or Slack, through a supported action or a verified API integration.

9. How to reason about a client

Step 1 — Map the movement

Sources, destinations, volume per transfer and per month, frequency, direction, and number of participants. Write the current path down before proposing anything.

Step 2 — Separate movement from connectivity

"We cannot move this fast enough" suggests transfer or fan-out. "We cannot reach that system at all" suggests a tunnel. Many clients have both problems and describe only one.

Step 3 — Understand the relationships

A one-off delivery may need only a transfer or fan-out. Ongoing exchange with shared membership, channels and permissions suggests a Room, even with two participants. Count the integrations and permissions being maintained, as well as the parties.

Step 4 — Find the inefficiency

Sequential transfers, duplicated transfers, staging servers, unnecessary copies, centralised bottlenecks, slow WAN movement, expensive egress, manual file exchange, polling, and separately maintained point-to-point integrations.

Step 5 — Check the constraints before the fit

Run section 7 against the candidate. For a transfer, is source size known or derivable before planning? Is whole-object movement acceptable, or are deltas needed? Are the required provider operations supported? Can the chosen intermediaries see plaintext under the client's policy? Are endpoints reachable with the required authentication? For live data, do session, loss and reconnect limits meet the application's needs?

A design that fails here fails regardless of how good the fit looked.

Step 6 — Match the smallest sufficient set of primitives

Use only what materially improves the workflow. One transfer with four destinations can be the complete proposal when shared membership adds no value.

Step 7 — Quantify what you can, and mark what you cannot

Data volume, destination count, frequency, current duration, redundant copies, integration paths and participating systems. Where a number is missing, say it is missing and name who can supply it. Label estimates and assumptions clearly; do not present them as measurements.

For a cost comparison, include applicable source egress and request charges, Beam charges, destination charges and retries. Measure representative workloads before promising faster completion or lower total cost.

Step 8 — Propose the smallest proof

The test should be small enough to run this week and decisive enough to settle the question:

• One large object to three destinations in a single fan-out, against the client's real endpoints, checking each destination.
• One bucket-to-bucket transfer across two providers they already use.
• One private API reached through an authenticated tunnel, consumed by the system that needs it.
• One Room with a bucket, two machines and one partner joining from an invitation, checking grants and the selected publication's protection mode.
• One live channel with a real encoder and two viewers, for the required duration.
• One recurring job in Studio, replacing a script somebody maintains by hand.

Agree the success criteria before running the proof.

10. Integration patterns

Each pattern names the primitive, the interface, and what must be validated.

A — Sequential copies become one fan-out. Source writes to N destinations one at a time. Replace with one transfer carrying N destinations. Primitive: transfer with multiple destinations through the SDK, API or Studio. Validate: source and destination capacity, each destination's completion and integrity, provider compatibility, elapsed time and combined cost.

B — Multi-cloud distribution. One dataset to S3, R2, a self-hosted S3-compatible store and private infrastructure at once. Primitive: fan-out through the SDK, API or Studio. Validate: every target's required operations through a supported adapter or compatible, authorized HTTP endpoint. Check section 5 before naming a cloud, and identify the trusted SDK process or Studio service that holds the signing credentials.

C — Dataset to distributed compute. Training or batch data reaching several GPU hosts. Primitive: fan-out through the SDK or Studio; or a Room if the hosts also exchange results. Validate: integration with the client's compute system and the point at which the data is usable. Do not assume a job can start before the full object lands. The training or batch compute remains a separate service.

D — Multi-party data room. Enterprise, partners, analysts, buckets and agents around one dataset. Primitive: Room with roles, grants, invitations and object channels, using agent/CLI interfaces and Studio for bucket configuration. Validate: each participant's permissions and the protection of each publication. A bucket source or recipient changes that publication's confidentiality boundary.

E — Agent data exchange. Agents request datasets, deliver outputs, exchange live information and reach services. Primitive: supported Room channels through agent or Web Agent interfaces, and transfers or workflows through Studio MCP. Validate: actual tool and channel support, identities, scopes, spending authorization and credential references. MCP access is not a universal Room channel API.

F — Broadcast from storage. A bucket object distributed to several regions at once. Primitive: fan-out from an object-storage source through SDK/API/Studio; or a Room object publication to bucket members. Validate: the dated R2 range-read caveat in section 7 if R2 is the source, publication protection, and whether recipients need durable membership or one-off destinations.

G — Event-driven movement. An application event produces data that must reach several systems. Primitive: transfer or fan-out from the SDK, or a Studio workflow using a supported external trigger. Validate: that source size can be supplied or derived before planning, action retry behavior, and whether the client wants an inspectable run history.

H — Private service connectivity. A service currently exposed through public infrastructure or a VPN that exists only for it. Primitive: tunnel through CLI/local agent. Validate: protocol, outbound connectivity, endpoint authentication and encryption termination. TCP uses a supported relay path, rather than native public hostname ingress.

I — Partner data exchange. Separate transfer workflows per partner. Primitive: Room with per-partner roles and invitation-based joining through the CLI/agent, or a supported Web Agent flow. Validate: partners' available clients and supported operations, grants, payer, revocation and trust boundary. Browser participants using one Web Agent share that instance's identity.

J — Live distribution. One live source, several consumers. Primitive: Room media channel with WHIP ingest and WHEP playback, or a Room stream channel through compatible agents. Validate: encoder, consumer count, duration, backpressure/loss and reconnect behavior. For browsers, the reviewed Web Agent SDK exposes messages and media; the Beam broker client exposes media paths. Neither is a general browser byte-stream API.

11. Decision tree

Bytes need to move?
  |
  +-- Finite size known or derivable before planning?
       +-- yes, one destination ------> Transfer
       +-- yes, several destinations --> Fan-out
       +-- no, open-ended producer ----> Assess a live channel below

Ongoing exchange needs shared membership and permissions?
  +-----------------------------------> Room (roles, grants, invitations)

Data is live or continuous?
  +-- between compatible agents ------> Room stream / datagram channel
  +-- audio/video with an encoder -----> Room media (WHIP in, WHEP out)
  +-- browser participation -----------> Web Agent SDK: messages + media;
  |                                     Beam broker client: media paths
  +-- expose a source to consumers ----> Tunnel stream / WebRTC endpoint
                                        with the chosen access policy
  Check duration, delivery behavior and reconnect needs for every path.

Something private must be reachable from outside?
  +-----------------------------------> Tunnel; confirm mode and access policy

The process around movement needs steps, retries or scheduling?
  +-----------------------------------> Studio workflow

An AI agent should drive it?
  +-- supported Studio operations -----> Studio MCP server
  +-- other supported operations ------> Their SDK, CLI or agent interface

Several of these at once?
  +-----------------------------------> Combine where each adds value

The tree suggests a starting point. Apply the provider, interface and security constraints in sections 4–7 before recommending a design.

12. Shape of a good answer

When asked how Beam could help a company, answer in this shape. Keep it short enough to be read and specific enough to be acted on.

Existing process — how data moves today and how the systems reach each other. Use their words and their numbers.

Where Beam fits — the specific points of introduction, supported by the client's problem.

Primitives and interfaces used — the capabilities and clients needed for the workflow. Record the client versions used for validation.

Proposed flow — a simple diagram, showing which parts Beam coordinates, where payload travels, and which components are trusted with plaintext or credentials.

Why it helps — the technical or operational reason: parallel delivery, fewer duplicated copies, reusable membership, controlled reachability or automation of repeatable steps. Quantify benefits only where supported by measurements or clearly labeled estimates.

What must be confirmed — open questions with who can answer them. Include unverified constraints from section 7, support/availability, security requirements and the full cost assumptions.

Smallest proof — one test, with agreed success criteria and the relevant getting-started links from section 6.

13. Final mental model

A useful architecture or sales conversation starts with:

Where is data moving, being duplicated, distributed, streamed, or waiting to move? And which systems need to reach each other but currently cannot?

Then ask whether Beam makes that part of the process more programmable, more concurrent or easier to automate.

Find where data movement or connectivity creates avoidable delay, duplication, cost or infrastructure overhead. Explain the specific value Beam can offer, the evidence for it and the conditions required to deliver it. A credible proposal is also clear when the existing architecture already meets the need.

14. Reference map

Pages worth fetching as Markdown when you need detail: intro, architecture, clients, developer-quickstart, sdk, cli, studio, transfers, connectors, billing, management-api, api-reference.