scout

A light, no-node client for reading content from Swarm. Point it at a public gateway (or any Bee HTTP endpoint) and fetch content by reference — no node to run, no stake, no postage batch. The "scout bee" that finds and fetches without keeping the hive.

Published on crates.io as swarm-scout (the binary and library are both scout).

Install

cargo install swarm-scout      # provides the `scout` command

Usage

# read — no node, stake, or stamp
scout cat   <ref> [path]        # print content to stdout (manifest-aware, /bzz)
scout get   <ref> <out> [path]  # download content to a file
scout bytes <ref>               # print the raw bytes behind a reference (/bytes)

# write — needs a Bee node holding a postage batch
scout up       <file> [--name n] --stamp <batch>   # upload a file (/bzz)  -> ref
scout up-bytes <file>            --stamp <batch>    # upload raw bytes (/bytes) -> ref
scout up-dir   <folder> [--index index.html] --stamp <batch>   # upload a browsable collection -> ref

# feeds — a stable handle that always serves the latest content
scout keygen                                              # identity (key + owner + pubkey)
scout publish <ref> --key <hex> -t <topic> --stamp <batch>   # -> feed manifest ref
scout cat <feed-manifest-ref>                            # read latest (re-publish to update)

# sharing — encrypted + revocable (Access Control Trie)
scout share <file> --to <pubkey> --stamp <batch>   # encrypt+grant; records a share id
scout shares                                        # list your shares
scout grantees <id>                                 # who has access
scout revoke <id> --grantee <pubkey> --stamp <batch>   # drop a key
scout fetch <file_ref> --publisher <pk> --history <h>  # recipient: decrypt

Reads default to the public Swarm gateway (--gateway / $BEE_GATEWAY = https://download.gateway.ethswarm.org), so scout cat <ref> works with zero setup. Uploads go to your own Bee node (--node / $BEE_NODE, default http://localhost:1633) and need --stamp / $BEE_STAMP (a usable postage batch):

scout cat <ref>                                     # reads via the public gateway
scout --gateway http://localhost:1633 cat <ref>     # ...or your own node / a private gateway
scout up photo.jpg --stamp <batch>                  # uploads to your node -> reference
BEE_NODE=https://my-node.example BEE_STAMP=<batch> scout up notes.md

Library + examples

scout is also a library (swarm-scout): [LiteClient] wraps the read/write/feed/ACT calls, and the stash / perch / keep tools below are each built on it. See examples/ (cargo run --example read -- <ref>) and the API docs on docs.rs.

Why "light"?

Reads (/bzz, /bytes) are served by any gateway or remote Bee — no local node, stake, or stamp required. That's the light-node idea: most people who use Swarm just want to fetch (and, later, share) content, not operate infrastructure.

Feeds (mutable pointers)

A feed gives you a stable reference that always serves the latest content — the basis for "a folder/site whose contents change but whose link doesn't."

scout keygen                                   # save the key; note the owner
scout publish <ref> --key <key> -t mysite --stamp <batch>   # prints a feed manifest ref
scout cat <feed-manifest-ref>                  # serves the latest published content
# publish again under the same key+topic → the same manifest ref now serves the new content

Sharing (ACT)

Encrypted, revocable sharing via Swarm's Access Control Trie. share uploads a file encrypted and grants a set of recipient compressed pubkeys (scout keygen prints one); recipients download with the file_ref + publisher + history. revoke drops a key without re-uploading.

Shares you create are recorded in ~/.scout/shares.json and managed by a short id (scout shares), so you don't juggle hex refs:

scout keygen                                              # note the pubkey
scout share secret.pdf --to <recipient-pubkey> --stamp <batch>   # -> id + refs
scout shares                                              # list your shares
scout grantees <id>                                      # who currently has access
scout revoke   <id> --grantee <recipient-pubkey> --stamp <batch>
scout fetch <file_ref> --publisher <pubkey> --history <h> out.pdf  # recipient side

A recipient decrypts on their own Bee node (configured with the key behind their pubkey); the node does the decryption, so fetch works for whoever's node it runs against (the publisher always; a grantee on theirs).

Status

• Read — cat / get / bytes; no node, stake, or stamp.
• Write — up / up-bytes to a Bee node holding a postage batch.
• Feeds — keygen / publish; read the latest via cat.
• Sharing (ACT) — share / shares / grantees / revoke / fetch.
• All verified end-to-end against a live Bee node (2.7.2).

The scout toolkit

scout is the foundation; three focused tools are built on its library:

Tool	Crate	What it does
stash	swarm-stash	sync a folder ↔ Swarm (a feed-backed drive)
perch	swarm-perch	publish a folder as a website (stable URL)
keep	swarm-keep	an encrypted secrets/notes vault

Full guide: the scout handbook.

Built on bee-rs.

License

MIT