# Storage

Storage is where a project's source bytes live. The chain commits to those bytes by hash, and a backend
holds them. Storage is stateless in the CLI: there is no config file, so you select a backend per
command with a flag, or set it in the environment.

## Backends

| Backend | What it is | Notes |
| --- | --- | --- |
| `fs` | local disk (the default) | no public URL; for local development |
| `cloud` | S3, R2, or a CDN | needs a public read base (`--public-base` or `ABX_S3_PUBLIC_BASE`) |
| `ipfs` | IPFS | Pinata, or a local Kubo node |
| `arweave` | Arweave | permanent; uses Turbo by default |

Select a backend with `--backend`, or set `ABX_STORAGE_BACKEND`. The order is the flag, then the
environment, then the `fs` default. Secrets are read from the environment only, for example
`ABX_S3_ACCESS_KEY_ID` and `ABX_S3_SECRET_ACCESS_KEY` for cloud, or `PINATA_JWT` for IPFS.

## Commands

- `abx storage show`: the resolved backend, and where each setting came from.
- `abx storage upload <path>`: upload one file and print its locator, which is the URI that `abx attach` takes.
- `abx storage balance`: Arweave upload credits and the funded address.
- `abx storage topup --usd <n>`: buy Arweave upload credits.
- `abx storage backup-key --out <path>`: copy the managed storage key to a path you choose.

## Arweave and Turbo

Arweave uploads go through Turbo by default. Uploads under 100 KB are free and need no setup. Larger
uploads use prepaid credits. On the first upload, a managed Arweave key is created at
`.abx-self-host/arweave-key.json`; it signs uploads and holds the credits, and it is reused across
projects. Read paths such as `serve` and `verify` never create a key.

Credits attach to an identity. `--storage-signer` selects it: `arweave`, the default, uses the managed
key; `eth` uses your EVM signing key as the Turbo identity, so credits sit on that address. With `eth`
and `--sign`, a browser wallet signs each upload with no gas.

Check credits with `abx storage balance` before concluding that an upload needs funding, since both the
managed key and the ETH wallet can hold credits. Back up the managed key with `abx storage backup-key`
before topping up. A gateway or provider is swappable, because the on-chain hash is the anchor.