Migrating from Mantle

Lithos is a continuation of Mantle (opens in a new tab). The config schema and CLI shape stay largely the same; the binary, filenames, and environment variables are renamed, and Lithos adds live reconciliation, previews, checkpoints, and better CI ergonomics.

You do not need to migrate everything at once. Lithos still reads Mantle names during the transition.

Renames at a glance

What's different beyond the rename

Lithos keeps the same core model but adds a few important behaviors:

• Live reconciliation against the Roblox API. Before applying a deploy, Lithos verifies that the experiences, places, game passes, and developer products it thinks exist actually exist. Resources deleted in the Creator Hub are dropped from state and re-created instead of producing a broken update. See The resource graph.
• Plan preview before apply. Every deploy shows the diff before any API call.
• Preflight diagnostics and rollback checkpoints. Lithos validates the common Roblox failure modes before apply, stores the previous environment graph as a checkpoint, and provides lithos undo for best-effort recovery.
• lithos diff --live. Run the same reconciliation pass that deploy runs, but only print the diff — useful for "what would happen if I deployed right now?" without prompting or writing.
• Cloudflare R2 remote state. Lithos talks to any S3-compatible endpoint, including R2. See Cloudflare R2 remote state.
• Better CI ergonomics. Auto-approve in non-TTY contexts, --plain-preview for plain logs, and --diff --live for PR review.
• Honest error messages. Several Mantle log lines that referenced the wrong credential type (e.g. claiming MANTLE_OPEN_CLOUD_API_KEY was a ROBLOSECURITY) have been corrected.

Recommended migration order

Do it in one PR or in stages. Each step is safe on its own.

1. Swap the binary

Update foreman.toml:

[tools]
- mantle = { source = "blake-mealey/mantle", version = "0.11" }
+ lithos = { source = "siriuslatte/lithos", version = "0.3.0" }

Run foreman install, then update scripts and CI commands to call lithos.

2. Run a deploy

lithos deploy --environment dev

Lithos may warn if it is still reading mantle.yml, mantle.yaml, or .mantle-state.yml. The deploy still works. After the first successful run, Lithos writes .lithos-state.yml next to the legacy file.

3. Rename the config file

Rename mantle.yml → lithos.yml or mantle.yaml → lithos.yaml. If you prefer JSON, convert the config and save it as lithos.json. Lithos prefers lithos.yml, then lithos.yaml, then lithos.json, and prefers any of those over the legacy Mantle names.

4. Update environment variables

In CI secrets, .env files, and team docs, replace MANTLE_* with LITHOS_* when convenient. Both work; LITHOS_* wins.

- MANTLE_OPEN_CLOUD_API_KEY="…"
- MANTLE_AWS_ACCESS_KEY_ID="…"
- MANTLE_AWS_SECRET_ACCESS_KEY="…"
+ LITHOS_OPEN_CLOUD_API_KEY="…"
+ LITHOS_AWS_ACCESS_KEY_ID="…"
+ LITHOS_AWS_SECRET_ACCESS_KEY="…"

5. Delete the legacy state files

Once the new .lithos-state.yml (or remote object) is confirmed, delete the legacy state file or object.

What does not change

• The config schema. Every key valid in mantle.yml or mantle.yaml is valid in lithos.yml, lithos.yaml, and lithos.json. The configuration reference is the same shape Mantle had, with later additions.
• The state-file format. A Mantle state file is a Lithos state file with a different name.
• The set of supported Roblox resources.
• Authentication: same ROBLOSECURITY cookie, same Open Cloud API key.

Help, my deploy errors out after migration

A few things to check:

1. Which env vars are set? During the transition, both names can exist; LITHOS_* wins.
2. Which state file is being loaded? The "Loading project" block names it.
3. Do remote-state credentials still have the same bucket access they had before?

If something else is going wrong, please open an issue (opens in a new tab).