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."

Run the List StackScripts operation.

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.

{
  "id": 1193838, # Store value
  "username": "jqlinode1234",
  "user_gravatar_id": "1a2345b6789012345c678de90fgh",
  "label": "Grafana One-Click",
  "description": "Grafana One Click App",
    "ordinal": 0,
    "logo_url": "",
    "images": [
      "linode/debian11" # Store value
    ],
    "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 value
        "label": "Grafana Password",
        "example": "Password"
      },
      {
        "name": "username", # Store value
        "label": "The limited sudo user to be created for the Linode",
        "default": ""
      },
      {
        "name": "password", # Store value
        "label": "The password for the limited sudo user",
        "default": ""
      },
      {
        "name": "pubkey", # Store value
        "label": "The SSH Public Key that will be used to access the Linode",
        "default": ""
      },
      {
        "name": "disable_root", # Store value
        "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.

Run the List regions operation.

{
  "data": [
   {
     "capabilities": [
       "Linodes",
       "NodeBalancers",
       "Block Storage",
       "Object Storage",
       "Placement Groups",
       "Block Storage Encryption",
       "Linode Interfaces",
       "Premium Plans"
     ],
     "country": "us",
     "id": "us-lax", # Store value
     "label": "Los Angeles, CA, USA",
     ...

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

Run the List types operation.

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

{
 "data": [
   {
     "id": "g6-dedicated-4", # Store value
     "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.

Choose access security

When creating a new Linode, you need to secure access to its disks. You can do this in one of three ways:

Set a root_password. This is the base-level of security for access. Come up with a complex password value that you'll need to provide, each time you access the Linode's disks.
Add an SSH key. You can create an SSH key pair and add the public key to your Linode using the authorized_keys object.
Set authorized users. You can specify individual authorized_users from your account that have an SSH key applied to their profile. You can create a key for a user, then run the Add an SSH key to add it to their profile.

Creation process

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, authorized_keys, or authorized_users. Apply one of these fields, based on what you've chosen for access security.
- 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.
```
{
  "label": "StackScript_Debian_11_Linux_VM",
  "region": "us-lax",
  "type": "g6-dedicated-4",
  "image": "linode/debian11",
  "authorized_keys": [
    "<pasted public key>"
  ],
  "stackscript_id": 1193838,
  "stackscript_data": {
    "grafanapassword": "C0mPL3+-p@$$w0rD",
    "username": "grafana_lead",
    "password": "$uD0-p@$$w0Rd",
    "pubkey": "",
    "disable_root": "No"
  }
}
```
Set other body parameters in the request as desired.

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

{
  "id": 12345678, # Store value
  "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"
  ...
}