Swarm
Omnipin supports uploading on the Swarm decentralized network via the Hoverfly light client, Swarmy, or a Bee node.
Hoverfly
- API token env variables:
OMNIPIN_HOVERFLY_TOKEN,OMNIPIN_HOVERFLY_KEY - Supported methods: Upload
Hoverfly is a Swarm light client that requires no Bee node and no remote server — it runs entirely on your machine and works in CI.
Requires a Hoverfly daemon (v0.2.0 or newer) — Omnipin talks to it over its UNIX socket.
Setup
Install Hoverfly:
curl -fsSL https://raw.githubusercontent.com/omnipin/hoverfly/main/install.sh | shGenerate a signer key, fund it with xDAI + BZZ on Gnosis (see the Hoverfly README), then buy a postage batch and generate an overlay nonce:
hoverfly batch create --key 0xYOUR_KEY --size 200MB --duration 30d
hoverfly vanity-overlay --key 0xYOUR_KEY --peerlist peers.json --output overlay-nonceRunning the daemon
Start the daemon and leave it running:
hoverfly daemon \
--socket /tmp/hoverfly.sock \
--pool-size 256 \
--identity 0xYOUR_KEY \
--nonce-file overlay-nonce \
--peerlist peers.jsonAlways fetch a fresh peerlist from the GitHub CDN — the release-bundled peers.seed.json goes stale:
curl -fsSL -o peers.json https://raw.githubusercontent.com/omnipin/hoverfly/main/peers.seed.jsonOn a cold peerlist, add --discover-rounds 3.
Running the deployment
Set the postage batch ID and signer key in the environment:
OMNIPIN_HOVERFLY_TOKEN=0xf078...1afc # postage batch ID
OMNIPIN_HOVERFLY_KEY=da25...0a44
# OMNIPIN_HOVERFLY_SOCKET=/tmp/hoverfly.sock # optional, this is the defaultThen run the deployment command:
omnipin deployOmnipin reads the batch depth and its mutability from the chain, and checks that the signer key derives to the batch owner (a mismatched key makes bee reject every stamp). Set OMNIPIN_HOVERFLY_DEPTH to pin the depth — that skips the chain read, and with it the owner check. Set OMNIPIN_HOVERFLY_NO_OWNER_CHECK=1 to skip the owner check on its own, when you are authorised to stamp for a batch you don't own.
Other optional knobs:
OMNIPIN_HOVERFLY_RPC_URL— Gnosis RPC used for the on-chain lookup (defaults tohttps://rpc.gnosischain.com).OMNIPIN_HOVERFLY_NONCE— overlay nonce (hex, 32 bytes) that pins the upload overlay across uploads. Generate one withhoverfly vanity-overlay --key 0xYOUR_KEY --output overlay-nonce. Without it the daemon derives a fresh random overlay per upload.OMNIPIN_HOVERFLY_IMMUTABLE—1/trueto force fill-only (immutable) stamping,0/falsefor mutable. Only used when the depth is pinned.OMNIPIN_HOVERFLY_REDUNDANCY— Reed–Solomon redundancy level:none,medium,strong,insaneorparanoid(defaults to the daemon'smedium).OMNIPIN_HOVERFLY_CONCURRENCY— parallel peer sessions (defaults to 8, same ashoverfly upload).OMNIPIN_HOVERFLY_RETRIES— peers to try per chunk (defaults to 10, same ashoverfly upload).
Swarmy
- API token env variables:
OMNIPIN_SWARMY_TOKEN - Supported methods: Upload
Omnipin supports uploading on the Swarm decentralized network via Swarmy, a storage provider. A website cannot be uploaded to both Swarm and IPFS at the same time, so when opting in for Swarmy, other providers will be ignored.
Setup
To use Swarmy, you need to create an account on Swarmy. Afterwards, you should request a storage quota on the "Billing" page.

After receiving your storage quota, generate an API key from the "API Keys" section.

Running the deployment
Once you have your API key, put it in the environment variables:
OMNIPIN_SWARMY_TOKEN=123...Then run the deployment command:
omnipin deploy --ens omnipin.eth --safe eth:0x...Bee node
- API token env variables:
OMNIPIN_BEE_TOKEN,OMNIPIN_BEE_URL(optional, defaults tohttp://localhost:1633) - Supported methods: Upload
Running a Bee node
Install Bee for your platform, then create a minimum viable configuration at ~/.bee.yaml:
full-node: false
mainnet: true
password: password
blockchain-rpc-endpoint: "https://rpc.gnosischain.com"
swap-enable: true
verbosity: 4
welcome-message: "welcome-from-the-hive"
warmup-time: 10s
bootnode: /dnsaddr/mainnet.ethswarm.orgThis runs Bee as a light node on Swarm mainnet, using the public Gnosis Chain RPC. For production use, point blockchain-rpc-endpoint at your own RPC provider (e.g. Gateway.fm, Ankr, or a self-hosted Nethermind/Erigon node) — the public endpoint is rate-limited and Bee will misbehave under throttling.
Start the node:
bee start --config ~/.bee.yamlOn first start, Bee will print your node's Ethereum address. Wait until the node is running, then check the address via the debug API:
curl -s http://localhost:1633/addresses | jq .ethereumFunding the node
Bee needs both xDAI (for gas) and xBZZ (for postage stamps and SWAP) on Gnosis Chain. The easiest way to get both is via the official faucet/funding tool at fund.ethswarm.org:
- Open fund.ethswarm.org.
- Paste your node's Ethereum address.
- Pay with any supported asset/network — the service handles cross-chain swaps and delivers xDAI + xBZZ directly to your node's address on Gnosis Chain.
Once the funds arrive, Bee will automatically deposit BZZ into the chequebook contract.
Buying a postage stamp batch
- Calculate the amount and depth parameters using the batch calculator. Select how much storage you need and for how long you would like your website to stay on the network. It is possible to top up a batch later.
- Buy a postage stamp batch for the Bee node. The easiest way is via swarm-cli:
npx @ethersphere/swarm-cli stamp create --amount <amount> --depth <depth>pnpm dlx @ethersphere/swarm-cli stamp create --amount <amount> --depth <depth>bunx @ethersphere/swarm-cli stamp create --amount <amount> --depth <depth>deno run -A npm:@ethersphere/swarm-cli stamp create --amount <amount> --depth <depth>Or directly via the Bee API:
curl -sX POST http://localhost:1633/stamps/<amount>/<depth>
# {
# "batchID": "8fc...8552c6b", <-- you need this
# "txHash": "0x51c77...907b675"
# }Add the batch ID to the environment variables:
OMNIPIN_BEE_TOKEN=8fc...8552c6b
# OMNIPIN_BEE_URL=http://localhost:1633 # optional, this is the defaultSet OMNIPIN_BEE_URL only if your Bee node is not running on http://localhost:1633.
Then run the deployment command:
omnipin deploy --ens omnipin.eth --safe eth:0x...