Getting started

Install Lithos, wire up credentials, deploy the sample project, change it, and roll it back — all in under ten minutes.

Prerequisites

1. Install Lithos

Foreman (opens in a new tab) is the recommended path. It pins the Lithos version per repo and keeps local and CI machines aligned.

Then clone the example repo and let Foreman install Lithos:

git clone https://github.com/siriuslatte/lithos
cd lithos/examples
foreman install
lithos --version

Foreman reads the pinned version from examples/foreman.toml.

2. Authenticate

Lithos needs two credentials for almost every deploy:

1. Create an Open Cloud API key in the Creator Hub (opens in a new tab) with universe-places:write, asset:read, and asset:write scoped to the experiences you will manage.
2. If Roblox Studio is signed in on this machine, Lithos can usually read ROBLOSECURITY from the OS keychain automatically.
3. Put both in a project-root .env and add .env to .gitignore.

LITHOS_OPEN_CLOUD_API_KEY="…"
ROBLOSECURITY="…"

3. Deploy

From examples/:

lithos deploy projects/getting-started --environment dev

A deploy shows which config and state file Lithos loaded, the plan it intends to apply, and the resulting Roblox URLs.

Loading project:
  ╷
  │  Loaded config file projects/getting-started/lithos.yml
  │  Selected provided environment configuration dev
  │  No previous state for environment dev
  │
  ╰─ Succeeded

On a first deploy, the plan is all creates:

Deploying resources:
  ╷
  │  + Creating: experience_singleton
  │  + Creating: place_start
  │  + Creating: placeFile_start
  │  …
  │
  ╰─ Succeeded with 6 create(s), 0 update(s), 0 delete(s), 0 noop(s), 0 skip(s)

That summary line is usually the fastest signal in CI logs.

Target results:
  ╷
  │  Experience: https://www.roblox.com/games/8667346609
  │  Places:
  │    start: https://www.roblox.com/games/8667346609
  ╰──○

Open the link to launch the experience.

4. Make a change and re-deploy

Edit projects/getting-started/lithos.yml and change the place name:

target:
  experience:
    configuration:
      genre: building
    places:
      start:
        file: game.rbxlx
        configuration:
          name: Going to the moon with Lithos

Run deploy again:

lithos deploy projects/getting-started --environment dev

You should get one update and the rest noops:

Succeeded with 0 create(s), 1 update(s), 0 delete(s), 5 noop(s), 0 skip(s)

That is the core workflow: change config, rerun deploy, apply only the minimum diff. Lithos also recorded a checkpoint before the update.

5. Undo a bad deploy

lithos undo projects/getting-started --environment dev

undo imports live state, compares it to the last checkpoint, shows the rollback plan, and applies it.

6. (Optional) clean up

lithos destroy projects/getting-started --environment dev

Roblox does not allow hard-deletes for most asset types, so destroy archives the assets and removes them from Lithos state.

Next steps

• The resource graphWhat 5 noop(s) actually meant, and how +/~/− markers are decided.
• State and reconciliationWhat .lithos-state.yml is for and when to make it remote.
• EnvironmentsHow dev and prod share a config without overwriting each other.
• CLI referenceEvery subcommand and flag, end to end.