A StackScript lets you automate the deployment of new systems, through a customized script you run when creating a new Linode. Here, we cover how to add a new Linode using a pre-built StackScript from our library. The StackScript runs the first time your new Linode boots, allowing you to automatically customize the default Linux distribution.

Get the StackScript

To start, you need to get the specific StackScript you want to use from our library. This is what we refer to as a "community StackScript."

1. Run the List StackScripts operation.

2. Review the following in the response, for each StackScript:

   • description. This is what this script will apply on a new Linode.

   • images. These represent the Linux distributions that support the StackScript. Review the list and store the Linux distribution you'd like to use as your imageId.

   • user_defined_fields. These represent specific values you'll need to provide when creating your new Linode. Store the name for each of these and review each label for a description of the value you'll need to provide.

   JSON

   {
     "id": 1193838, <== Store.
     "username": "jqlinode1234",
     "user_gravatar_id": "1a2345b6789012345c678de90fgh",
     "label": "Grafana One-Click",
     "description": "Grafana One Click App",
       "ordinal": 0,
       "logo_url": "",
       "images": [
         "linode/debian11" <== Store.
       ],
       "deployments_total": 0,
       "deployments_active": 0,
       "is_public": true,
       "mine": false,
       "created": "2023-06-15T10:25:33",
       "updated": "2023-06-15T10:25:33",
       "rev_note": "",
       "script": "#!/usr/bin/env ...",
       "user_defined_fields": [
         {
           "name": "grafanapassword", <== Store.
           "label": "Grafana Password",
           "example": "Password"
         },
         {
           "name": "username", <== Store.
           "label": "The limited sudo user to be created for the Linode",
           "default": ""
         },
         {
           "name": "password", <== Store.
           "label": "The password for the limited sudo user",
           "default": ""
         },
         {
           "name": "pubkey", <== Store.
           "label": "The SSH Public Key that will be used to access the Linode",
           "default": ""
         },
         {
           "name": "disable_root", <== Store.
           "label": "Disable root access over SSH?",
           "oneof": "Yes,No",
           "default": "No"
         }
       ]
     },
     ...
   }
   

👍

You can create your own

If you'd prefer, you can create your own custom StackScript and save it on our cloud for future use. Check out Write a custom script for use with StackScripts for more information on generating a compatible script.

Get some other details

This includes information on the region where you want to create the Linode and the Linode plan you want to use.

Choose a region

You need to determine the Akamai Cloud data center (region) where your Linode will live.

1. Run the List regions operation.

   JSON

   {
     "data": [
      {
        "capabilities": [
          "Linodes",
          "NodeBalancers",
          "Block Storage",
          "Object Storage",
          "Placement Groups",
          "Block Storage Encryption",
          "Linode Interfaces",
          "Premium Plans"
        ],
        "country": "us",
        "id": "us-lax", <== Store
        "label": "Washington, DC, USA",
        ...
   

2. Consider where the majority of your requesting clients will be geographically, based on the label object. Choose an eligible region that's closest and store its id as your regionId.

   👍

   Review the capabilities object to ensure a region also offers all of the services you want included in your Linode. See Choose a Data Center for a complete list.

Choose a Linode plan

You need to decide on the type of Linode you want to use, based on your resource needs. Review Choose a Linode for complete details on all of the available types.

📘

Various Linode types are only available in certain regions:

• High memory Linodes

• GPU Linodes

• Premium Linodes

1. Run the List types operation.

2. In the response, locate the label object for the applicable plan type and store its id as your linodeType.

   JSON

   {
    "data": [
      {
        "id": "g6-dedicated-4", <== Store
        "label": "Dedicated 8GB",
        "price": {
          "hourly": 0.108,
          "monthly": 72.0
         },
         "region_prices": [
           {
             "id": "id-cgk",
             "hourly": 0.13,
             "monthly": 86.4
           },
           {
             "id": "br-gru",
             "hourly": 0.151,
             "monthly": 100.8
           }
         ],
         "addons": {
           "backups": {
             "price": {
               "hourly": 0.015,
               "monthly": 10.0
             },
             "region_prices": [
               {
                 "id": "id-cgk",
                 "hourly": 0.018,
                 "monthly": 12.0
               },
               {
                 "id": "br-gru",
                 "hourly": 0.021,
                 "monthly": 14.0
               }
             ]
           }
         },
         "memory": 8192,
         "disk": 163840,
         "transfer": 5000,
         "vcpus": 4,
         "gpus": 0,
         "network_out": 5000,
         "class": "dedicated",
         "successor": null,
         "capabilities": [],
         "accelerated_devices": 0
       },
       ...
     ],
     "page": 1,
     "pages": 1,
     "results": 47
   }
   

Create the Linode

Now, we'll create the new Linode and apply the StackScript.

1. Run the Create a Linode operation. Include the following values in the request:

   • label. Give your Linode an easily recognizable name.

   • region. Set this to your stored regionId.

   • image. Set this to your stored imageId.

   • type. Set this to your stored linodeType.

   • root_pass. Set a root user password that you'll use to access your Linode. The root user has access to the entire system, including files and commands. Make sure this is extremely strong to prevent attackers from gaining access to your system.

   • stackscript_id. Set this to your stored stackscriptId.

   • stackscript_data. Populate this object with values for all of the user_defined_values you stored for your selected StackScript.

   JSON

   {
     "label": "StackScript_Debian_11_Linux_VM",
     "region": "us-lax",
     "type": "g6-dedicated-4",
     "image": "linode/debian11",
     "root_pass": "@C0mpl3x-P@$$w0rd",
     "stackscript_id": 1193838,
     "stackscript_data": {
       "grafanapassword": "C0mPL3+-p@$$w0rD",
       "username": "grafana_lead",
       "password": "$uD0-p@$$w0Rd",
       "pubkey": "",
       "disable_root": "No"
     }
   }
   

2. Set other body parameters in the request as desired.

   👍

   Add more security

   You can create an SSH key pair and add the public key to your Linode using the authorized_keys object with this operation. This automatically appends the key to the root user's ~/.ssh/authorized_keys file. This replaces the root_password and connections to the Linode will be resolved using the key pair. If you don't apply it now, you can run the Rebuild a Linode operation and target this Linode to add this security.

3. From the response, store the id as your linodeId. Use this value to target your Linode with other API operations.

   JSON

   {
     "id": 12345678, <== Store
     "label": "StackScript_Debian_11_Linux_VM",
     "group": "",
     "status": "provisioning",
     "created": "2025-10-28T20:40:20",
     "updated": "2025-10-28T20:40:20",
     "type": "g6-dedicated-4",
     "ipv4": [
       "123.456.789.10"
     ...
   }