Cloudflare R2 Remote State

Use R2 if you want S3-compatible remote state without AWS.

1. Create a bucket

Create a private R2 bucket. The default access settings are fine.

2. Upload existing state (optional)

If you are moving from local state, rename .lithos-state.yml to <project-name>.lithos-state.yml and upload it to the bucket.

<project-name> becomes the remote object key Lithos uses.

3. Configure Lithos

Add remote-state config to lithos.yml:

# ...your existing configuration
state:
  remote:
    region:
      custom:
        name: <r2-region-name>
        endpoint: <r2-s3-api>
    bucket: <bucket-name>
    key: <project-name>

• Replace <r2-region-name> with the bucket region. The R2 docs (opens in a new tab) list the available hints.
• Replace <r2-s3-api> with the bucket's S3 API endpoint.
• Replace <bucket-name> with the name you selected when you created your bucket.
• Replace <project-name> with the project key. For example, pirate-wars becomes pirate-wars.lithos-state.yml in the bucket.

4. Supply credentials

Create an R2 API token with Object Read & Write access to the bucket. Lithos uses the token's access key ID and secret access key through the same LITHOS_AWS_* variables it uses for S3.

See Authentication for the exact env vars.

After that, Lithos reads and writes the R2 object automatically. Once the remote file is confirmed, delete the checked-in local state file so it does not drift.