Amazon S3 Remote State

Use S3 when more than one machine or CI job deploys the same project.

1. Create a bucket

Create a private S3 bucket in the AWS region you want to use for state. Leave "Block all public access" enabled.

If you expect to use Object Lock later, enable it now; it cannot be added after bucket creation.

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: [<aws-region>]
    bucket: <bucket-name>
    key: <project-name>

• Replace <aws-region> with the bucket region, for example us-west-2.
• Replace <bucket-name> with the bucket name.
• Replace <project-name> with the project key. For example, pirate-wars becomes pirate-wars.lithos-state.yml in the bucket.

4. Supply credentials

Set LITHOS_AWS_ACCESS_KEY_ID and LITHOS_AWS_SECRET_ACCESS_KEY, or use LITHOS_AWS_INHERIT_IAM_ROLE=1 on AWS-managed workloads.

See Authentication for the exact env vars.

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