Authentication

🚫

Remember to never save your secrets in source control or any insecure environment. Anybody who gets access to them could use them to steal your accounts.

Resource management

For most resource management, Mantle requires a valid .ROBLOSECURITY cookie value to authenticate its requests. Some resources (like Place Files) require a Roblox Open Cloud API key.

ROBLOSECURITY

If there is a logged-in Roblox Studio installation, Mantle can automatically extract its .ROBLOSECURITY cookie and will authenticate requests as the user logged in to Roblox Studio.

Otherwise, you will have to provide the cookie via an environment variable called ROBLOSECURITY.

You can set your environment variable in various ways, like the following:

Create a .env file with the contents:

ROBLOSECURITY="{your cookie}"

Learn more →

To get your .ROBLOSECURITY cookie manually, you have a few options:

Navigate to roblox.com (opens in a new tab) in your browser and open the dev tools (right-click and select "Inspect"). Navigate to the "Application" tab, then look for "Cookies" under "Storage" in the left-hand sidebar. Under "Cookies", select "https://www.roblox.com" then select ".ROBLOSECURITY" from the list of cookies. Copy the value from the "Cookie Value" section. You can then set your environment variable using one of the above methods.

Note that if you ever log out of your browser session the cookie will be revoked and anything using it will no longer work. Getting a cookie from a Roblox Studio session is less likely to get revoked as you typically log out of Roblox Studio less often.

Roblox Open Cloud API key

Follow the official Roblox guide (opens in a new tab) for creating a Cloud API key. You must grant the key access to the following services:

Place Publishing for all experiences you want to manage with Mantle

To authenticate with the Cloud API, you must provide the MANTLE_OPEN_CLOUD_API_KEY environment variable. You can set your environment variable in various ways, like the following:

Create a .env file with the contents:

MANTLE_OPEN_CLOUD_API_KEY="{your api key}"

Learn more →

Remote state management

Mantle supports managing remote state files using AWS S3 storage which requires authentication. You can provide your credentials either through environment variables or an AWS profile file (opens in a new tab).

If you are new to using AWS, I recommend you read their guide on best practices for managing AWS access keys (opens in a new tab) before getting started.

To learn how to get an access key ID and secret, you can read their guide on understanding and getting your AWS credentials (opens in a new tab) (read the intro and "Programmatic access" sections).

The simplest method is to set the MANTLE_AWS_ACCESS_KEY_ID and MANTLE_AWS_SECRET_ACCESS_KEY environment variables. Mantle also supports the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY variables but recommends you scope your variables to Mantle to avoid conflicts with other tools.

If you're using Mantle within an AWS EC2 instance or AWS Elastic Container Service, you can set the MANTLE_AWS_INHERIT_IAM_ROLE environment variable to true to inherit the permission set granted to the host runner via either the EC2 instance's IAM role or the Elastic Container Service task execution IAM role.

You can set your environment variables in various ways, like the following:

Create a .env file with the contents:

MANTLE_AWS_ACCESS_KEY_ID="{your access key id}"
MANTLE_AWS_SECRET_ACCESS_KEY="{your secret access key}"

Learn more →

`dotenv` files

dotenv files are a common tool in the industry for storing frequently used environment variables on a per-developer basis. It is important to make sure you do not check-in your dotenv files into your SCM repo.

When a dotenv file is present in the current working directory or any of its parents, Mantle will parse its contents and use the provided variable definitions as environment variables.

To create a dotenv file, start by ensuring it will be ignored by your SCM tool. For Git, create or update your .gitignore file:

.gitignore

# ignore all dotenv files
.env

Now create a file with the name .env in your project, and add any variables you want Mantle to load:

.env

VARIABLE_NAME="{value}"

It's good practice to update your README.md or CONTRIBUTING.md file as well so that other developers on your team know they need to create a .env file themselves and add the necessary variables, for example:

README.md

## Contributing
 
After cloning the repo, create a `.env` file in the root of the project, and add the following variables:
 
```
MANTLE_AWS_ACCESS_KEY_ID="{your access key id}"
MANTLE_AWS_SECRET_ACCESS_KEY="{your secret access key}"
MANTLE_OPEN_CLOUD_API_KEY="{api key}"
```
 
You can get the secrets by...

Installation Remote State