Best Practices
Deploy production worlds using AWS KMS

Deploy production worlds using AWS KMS

The MUD equivalent of root (opens in a new tab) is the owner of the root namespace, by default this is the address that deployed the World. Because this address is so powerful, its private key needs to be very secure. We recommend as best practice to use AWS Key Management Service (opens in a new tab) as the deployer for Worlds in production.

Sign up with AWS

  1. If you do not already have an AWS account, create one (opens in a new tab). The free tier is sufficient for this purpose.

  2. Sign in as a Root user.

Create an IAM user and an access key with permission to use the key to sign

  1. In the AWS console click Services in the top-left corner and then Security, Identity, & Compliance > IAM.

  2. Click Access management > Users and then click Create user.

  3. Create a user called Appname_world_owner. Do not give it any permission for now.

  4. Click the user name and select the Security credentials tab.

  5. Scroll down and click Create access key. Select Command Line Interface (CLI) and click the confirmation. For the description tag value write Appname_world_owner_access.

  6. Click Show to see the access key and keep the access key and secret access key in a safe place.

Create an Ethereum public/private key pair

You can read additional details about this process in the AWS documentation (opens in a new tab).

  1. In the AWS console click Services in the top-left corner and then Security, Identity, & Compliance > Key Management Service.

  2. Click Create a key and select Customer managed key. Select these parameters:

    Key typeAsymmetric
    Key usageSign and verify
    Key specECC_SECG_OP256K1
    Key administratorsNone
    Key deletionClear (only root can delete this key)
    Key usersAppname_world_owner
    Sample key policy
      "Id": "key-consolepolicy-3",
      "Version": "2012-10-17",
      "Statement": [
          "Sid": "Enable IAM User Permissions",
          "Effect": "Allow",
          "Principal": {
            "AWS": "arn:aws:iam::339713099434:root"
          "Action": "kms:*",
          "Resource": "*"
          "Sid": "Allow use of the key",
          "Effect": "Allow",
          "Principal": {
            "AWS": "arn:aws:iam::339713099434:user/Appname_world_owner"
          "Action": ["kms:DescribeKey", "kms:GetPublicKey", "kms:Sign", "kms:Verify"],
          "Resource": "*"
          "Sid": "Allow attachment of persistent resources",
          "Effect": "Allow",
          "Principal": {
            "AWS": "arn:aws:iam::339713099434:user/Appname_world_owner"
          "Action": ["kms:CreateGrant", "kms:ListGrants", "kms:RevokeGrant"],
          "Resource": "*",
          "Condition": {
            "Bool": {
              "kms:GrantIsForAWSResource": "true"
  3. Write down the key ID.

Install and configure the AWS CLI

  1. Install the AWS CLI from the website (opens in a new tab).

  2. Set the AWS environment variables.

    AWS_ACCESS_KEY_IDThe access key you created
    AWS_SECRET_ACCESS_KEYThe secret access key
    AWS_REGIONAWS region (the first component of the console's domain name, such as us-east-2)
    AWS_ENDPOINT_URLhttps:// followed by the hostname from the AWS console (opens in a new tab) for your region
    AWS_KMS_KEY_IDThe key ID for the world owner address, such as 6e8dcfb6-24fe-4fb0-a9ce-afb560f8ce7b

Use the new key

  1. Get the key's deployment address and fund it. For example, if you already have your private key in $PRIVATE_KEY you can use this command to send 1 ETH to the new address on Holesky.

    AWS_ADDRESS=`cast wallet address --aws`
    export ETH_RPC_URL=
    cast send $AWS_ADDRESS --private-key $PRIVATE_KEY --value 1ether
  2. Update scripts as needed. Scripts cannot rely on reading the deployment key from the local environment when you use KMS. Instead, use vm.startBroadcast() without any parameters to get the signature using whatever mechanism is used with forge, such as KMS.

  3. To deploy a new World, run this command.

    pnpm mud deploy --kms
  4. If you need to run forge scripts, use this command.

    forge script --aws

    Forge will automatically detect the AWS configuration from the environment variables.