Storage
Choose where source media and rendered output live.
The chain commits to content by hash. A storage backend keeps the bytes available.
| Backend | Use it for | Public by default |
|---|---|---|
fs | Local development | No |
cloud | S3, R2, or a CDN | With a public base URL |
ipfs | Pinata or Kubo | With a gateway and pinning |
arweave | Permanent storage through Turbo | Yes, after propagation |
Pass --backend for one command or set ABX_STORAGE_BACKEND. The flag wins over the environment.
The fallback is fs.
Keep credentials in ignored .env, never in commands or committed files. The root
.env.example lists optional variables.
Inspect and upload
abx storage show
abx storage upload ./art.png
abx storage status <locator>storage status reports:
| Result | Meaning |
|---|---|
ready | The configured gateway serves the bytes. |
propagating | Another gateway has the bytes; yours is behind. |
unreachable | No checked gateway can fetch the locator yet. |
Upload first. Wait for ready. Then write the locator into a token. Re-uploading does not make a slow
gateway catch up.
IPFS
--backend ipfs has two modes:
kubois the default and uses an IPFS node you run.pinatauses Pinata. SetABX_IPFS_MODE=pinataandPINATA_JWT.
Both modes upload directories under one root CID. This supports url-template fields such as
<base>/{id}.<ext>.
Point kubo mode at a local node with:
ABX_IPFS_API_URL=http://127.0.0.1:5001
ABX_IPFS_GATEWAY=http://127.0.0.1:8080Directory uploads preserve relative paths. A failed upload returns no root CID. A localhost gateway works only on that machine, so set a public gateway before publishing.
Arweave identity
--backend arweave needs the optional @artblocks/abx-storage-arweave package.
npm install @artblocks/abx-storage-arweave once alongside the CLI. It is not part of the default
install. See Install.
Turbo credits belong to the signing identity. The default mode stores its key at
.abx-self-host/arweave-key.json. Back it up before adding credits. See
Local data directory.
abx storage balance
abx storage backup-key --out <safe-path>
abx storage topup --usd <amount>--storage-signer eth uses an EVM wallet as the Turbo identity. With --sign, the browser wallet
signs an offchain upload message.
Fresh Arweave and IPFS content may take time to reach a given gateway. Set ABX_ARWEAVE_GATEWAY or
ABX_IPFS_GATEWAY before publishing if the project needs a specific host.
Metadata stores IPFS CIDs and Arweave transaction IDs, so abx set-gateway can change their gateway.
Rendered artifacts store a finished URL.