# Non-interactive installation (Configuration file)

#### Introduction

Sandbox Studio can be installed in two ways:

- **Interactive mode**: you run the installation script and answer each prompt as the wizard guides you through the setup. This is described in [Running the Installation Wizard](https://docs.sandboxstudiosoftware.com/books/installation-guide/page/running-the-installation-wizard "Running the Installation Wizard").
- **Non-interactive mode**: you provide all of the required settings up front in a JSON **configuration file** and pass it to the script with the `--config-file` flag. The installer reads every value from the file and runs the entire deployment without asking any questions.

Non-interactive mode is useful when you want repeatable, scripted, or unattended installations (for example in CI/CD pipelines, or when deploying the same configuration across multiple environments).

<p class="callout info">The configuration file drives exactly the same deployment as the interactive wizard. Every value you would normally be asked for in the wizard has a matching field in the configuration file.</p>

#### Installing with the script and a configuration file

You can run the installer from any terminal, including AWS CloudShell, your local machine, or a build agent, as long as it meets the requirements below.

**Before you begin, make sure your terminal is:**

- Authenticated to your AWS **Organisation Management account** (for example via `aws configure`, environment variables, an SSO profile, or an assumed role).

<p class="callout warning">Do not use your root account.</p>

- Targeting the AWS region where you want to install Sandbox Studio (for example by setting `AWS_REGION` / `AWS_DEFAULT_REGION` or your CLI profile's default region).

You can confirm which account and region your terminal is using with:

```bash
aws sts get-caller-identity
aws configure get region
```

**Then run the installation:**

1. Create your configuration file somewhere on the machine running the installer. For example, create a file called `sbs-config.json` in your home directory:

```bash
nano ~/sbs-config.json
```

Paste your configuration (see the [example configuration files](#bkmrk-example-configuration) below), then save and exit. You can use any text editor; `nano` is just an example.

2. Run the installation script and point it at your configuration file:

```bash
bash <(curl -s https://dist.sandboxstudiosoftware.com/install.sh) --config-file ~/sbs-config.json
```

The installer will load every value from the file and deploy the solution without prompting. Because no questions are asked, make sure your file is complete and correct before you run the command.

#### Using a configuration file to update Sandbox Studio

The same command is used to update an existing installation. When the script runs with a configuration file and detects an existing Sandbox Studio installation, it automatically upgrades all deployed stacks, with no confirmation prompts. Point the `--config-file` flag at your file exactly as you would for a first-time install:

```bash
bash <(curl -s https://dist.sandboxstudiosoftware.com/install.sh) --config-file ~/sbs-config.json
```

For more details on the update behaviour, see [Update Sandbox Studio](https://docs.sandboxstudiosoftware.com/books/installation-guide/page/update-sandbox-studio "Update Sandbox Studio").

#### The configuration file

The configuration file is a single JSON object. The sections below describe every field, whether it is required, its default value, and what it does.

##### Required fields

These fields must always be present in the configuration file.

<table id="bkmrk-field-type-descripti" style="width: 100%;"><thead><tr><th style="width: 22.2884%;">Field</th><th style="width: 9.5363%;">Type</th><th style="width: 68.1753%;">Description</th></tr></thead><tbody><tr><td style="width: 22.2884%;"><code>namespace</code></td><td style="width: 9.5363%;">string</td><td style="width: 68.1753%;">Unique namespace for this Sandbox Studio instance. Must be 3 to 8 alphanumeric characters (pattern <code>^[0-9a-zA-Z]{3,8}$</code>). Used as a prefix to name Sandbox Studio resources. Example: <code>Sandbox</code>.</td></tr><tr><td style="width: 22.2884%;"><code>hub_account_id</code></td><td style="width: 9.5363%;">string</td><td style="width: 68.1753%;">AWS account ID of the hub account where the data, compute, and API stacks are deployed. Must be a 12-digit account ID (pattern <code>^[0-9]{12}$</code>).</td></tr><tr><td style="width: 22.2884%;"><code>parent_ou_id</code></td><td style="width: 9.5363%;">string</td><td style="width: 68.1753%;">ID of the parent Organisational Unit where the Sandbox OUs will be created. Example: <code>ou-xxxx-xxxxxxxx</code> or a root ID such as <code>r-xxxx</code>.</td></tr><tr><td style="width: 22.2884%;"><code>managed_regions</code></td><td style="width: 9.5363%;">string</td><td style="width: 68.1753%;">Comma-separated list of AWS regions to manage. <code>us-east-1</code> is always included automatically. Example: <code>us-east-1,eu-west-1,ap-southeast-2</code>.</td></tr><tr><td style="width: 22.2884%;"><code>admin_group_name</code></td><td style="width: 9.5363%;">string</td><td style="width: 68.1753%;">IAM Identity Center group name for administrators. Example: <code>Sandbox_AdminsGroup</code>.</td></tr><tr><td style="width: 22.2884%;"><code>manager_group_name</code></td><td style="width: 9.5363%;">string</td><td style="width: 68.1753%;">IAM Identity Center group name for managers. Example: <code>Sandbox_ManagersGroup</code>.</td></tr><tr><td style="width: 22.2884%;"><code>user_group_name</code></td><td style="width: 9.5363%;">string</td><td style="width: 68.1753%;">IAM Identity Center group name for regular users. Example: <code>Sandbox_UsersGroup</code>.</td></tr><tr><td style="width: 22.2884%;"><code>allowed_ip_ranges</code></td><td style="width: 9.5363%;">string</td><td style="width: 68.1753%;">Comma-separated CIDR ranges allowed to access the API. Default: <code>0.0.0.0/1,128.0.0.0/1</code> (all IPs). Restrict to your corporate ranges if required.</td></tr><tr><td style="width: 22.2884%;"><code>use_existing_vpc</code></td><td style="width: 9.5363%;">boolean</td><td style="width: 68.1753%;">Whether to use an existing VPC (<code>true</code>) or create a new one (<code>false</code>).</td></tr><tr><td style="width: 22.2884%;"><code>notifications_enabled</code></td><td style="width: 9.5363%;">boolean</td><td style="width: 68.1753%;">Whether to enable email notifications.</td></tr></tbody></table>

##### Database options

<table id="bkmrk-field-type-required-" style="width: 100%;"><thead><tr><th style="width: 18.7128%;">Field</th><th style="width: 7.38705%;">Type</th><th style="width: 9.77624%;">Required</th><th style="width: 64.124%;">Description</th></tr></thead><tbody><tr><td style="width: 18.7128%;"><code>db_instance_type</code></td><td style="width: 7.38705%;">string</td><td style="width: 9.77624%;">Optional</td><td style="width: 64.124%;">RDS instance type for the PostgreSQL database, without the <code>db.</code> prefix. Default: <code>t4g.small</code>. Examples: <code>t4g.small</code>, <code>t4g.medium</code>, <code>r6g.large</code>.</td></tr><tr><td style="width: 18.7128%;"><code>db_engine_version</code></td><td style="width: 7.38705%;">string</td><td style="width: 9.77624%;">Optional</td><td style="width: 64.124%;">PostgreSQL engine version (format <code>X.Y</code>, major version 17 or higher). Leave empty (<code>""</code>) to use the latest default. Example: <code>17.4</code>.</td></tr><tr><td style="width: 18.7128%;"><code>db_encryption</code></td><td style="width: 7.38705%;">string</td><td style="width: 9.77624%;">Optional</td><td style="width: 64.124%;">Enable storage encryption for the RDS database. One of <code>Yes</code> or <code>No</code>. Default: <code>Yes</code> for new installations.</td></tr></tbody></table>

##### Identity Center application

You must provide **either** an existing application ARN (<code>idc_app_arn</code>) **or** a name for a new application (<code>idc_app_name</code>). If <code>idc_app_arn</code> is not supplied, a new SAML application is created using <code>idc_app_name</code> and <code>idc_app_description</code>.

<table id="bkmrk-field-type-required--1" style="width: 100%;"><thead><tr><th style="width: 19.3087%;">Field</th><th style="width: 7.38975%;">Type</th><th style="width: 12.7504%;">Required</th><th style="width: 60.5511%;">Description</th></tr></thead><tbody><tr><td style="width: 19.3087%;"><code>idc_app_arn</code></td><td style="width: 7.38975%;">string</td><td style="width: 12.7504%;">Conditional</td><td style="width: 60.5511%;">ARN of an existing IAM Identity Center application to use. If provided, an existing application is reused instead of creating a new one. Example: <code>arn:aws:sso::123456789012:application/ssoins-xxxxxxxxxxxxxxxx/apl-xxxxxxxxxxxxxxxx</code>.</td></tr><tr><td style="width: 19.3087%;"><code>idc_app_name</code></td><td style="width: 7.38975%;">string</td><td style="width: 12.7504%;">Conditional</td><td style="width: 60.5511%;">Display name for a new IAM Identity Center SAML application (used when creating a new application). Default: <code>Sandbox Studio</code>.</td></tr><tr><td style="width: 19.3087%;"><code>idc_app_description</code></td><td style="width: 7.38975%;">string</td><td style="width: 12.7504%;">Optional</td><td style="width: 60.5511%;">Description for a new IAM Identity Center SAML application. Default: <code>Sandbox Studio allows users to access temporary AWS accounts</code>.</td></tr></tbody></table>

##### Networking (VPC)

When <code>use_existing_vpc</code> is <code>true</code>, the following three fields become **required**. When <code>use_existing_vpc</code> is <code>false</code>, a new VPC is created and these fields are ignored.

<table id="bkmrk-field-type-required--2" style="width: 100%;"><thead><tr><th style="width: 16.4482%;">Field</th><th style="width: 11.6806%;">Type</th><th style="width: 22.5163%;">Required</th><th style="width: 49.355%;">Description</th></tr></thead><tbody><tr><td style="width: 16.4482%;"><code>vpc_id</code></td><td style="width: 11.6806%;">string</td><td style="width: 22.5163%;">Required if <code>use_existing_vpc</code> is <code>true</code></td><td style="width: 49.355%;">VPC ID to use. Example: <code>vpc-0123456789abcdef0</code>.</td></tr><tr><td style="width: 16.4482%;"><code>database_subnets</code></td><td style="width: 11.6806%;">string</td><td style="width: 22.5163%;">Required if <code>use_existing_vpc</code> is <code>true</code></td><td style="width: 49.355%;">Comma-separated subnet IDs for the database. Minimum 2 subnets in different Availability Zones. Example: <code>subnet-aaa,subnet-bbb</code>.</td></tr><tr><td style="width: 16.4482%;"><code>compute_subnets</code></td><td style="width: 11.6806%;">string</td><td style="width: 22.5163%;">Required if <code>use_existing_vpc</code> is <code>true</code></td><td style="width: 49.355%;">Comma-separated subnet IDs for compute resources. Minimum 1 subnet. Example: <code>subnet-ccc,subnet-ddd</code>.</td></tr></tbody></table>

##### Custom domain

<table id="bkmrk-field-type-required--3" style="width: 100%;"><thead><tr><th style="width: 16.5673%;">Field</th><th style="width: 11.323%;">Type</th><th style="width: 14.4131%;">Required</th><th style="width: 57.6965%;">Description</th></tr></thead><tbody><tr><td style="width: 16.5673%;"><code>custom_domain</code></td><td style="width: 11.323%;">string or null</td><td style="width: 14.4131%;">Optional</td><td style="width: 57.6965%;">Custom domain name for the application. Set to <code>null</code> to use the default CloudFront URL. Example: <code>sandbox.example.com</code>.</td></tr><tr><td style="width: 16.5673%;"><code>certificate_arn</code></td><td style="width: 11.323%;">string</td><td style="width: 14.4131%;">Required if <code>custom_domain</code> is set</td><td style="width: 57.6965%;">ARN of the ACM certificate in <code>us-east-1</code>. Example: <code>arn:aws:acm:us-east-1:123456789012:certificate/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</code>.</td></tr></tbody></table>

##### Administrators

<table id="bkmrk-field-type-required--4" style="width: 100%;"><thead><tr><th style="width: 17.399%;">Field</th><th style="width: 10.8489%;">Type</th><th style="width: 9.89273%;">Required</th><th style="width: 61.8594%;">Description</th></tr></thead><tbody><tr><td style="width: 17.399%;"><code>add_admin_users</code></td><td style="width: 10.8489%;">boolean</td><td style="width: 9.89273%;">Optional</td><td style="width: 61.8594%;">Whether to add IAM Identity Center users as Sandbox Studio administrators during installation. Default: <code>false</code>.</td></tr><tr><td style="width: 17.399%;"><code>admin_users</code></td><td style="width: 10.8489%;">array of strings</td><td style="width: 9.89273%;">Optional</td><td style="width: 61.8594%;">List of IAM Identity Center usernames to add as Sandbox Studio administrators. Used when <code>add_admin_users</code> is <code>true</code>. Example: <code>["admin@example.com", "john.doe"]</code>.</td></tr></tbody></table>

##### Email notifications

When <code>notifications_enabled</code> is <code>true</code>, <code>email_service</code> and <code>email_from</code> are **required**. If <code>email_service</code> is set to <code>SMTP</code>, the SMTP fields below also become required.

<table id="bkmrk-field-type-required--5" style="width: 100%;"><thead><tr><th style="width: 14.7795%;">Field</th><th style="width: 11.7998%;">Type</th><th style="width: 26.2095%;">Required</th><th style="width: 47.2112%;">Description</th></tr></thead><tbody><tr><td style="width: 14.7795%;"><code>email_service</code></td><td style="width: 11.7998%;">string</td><td style="width: 26.2095%;">Required if <code>notifications_enabled</code> is <code>true</code></td><td style="width: 47.2112%;">Email service to use for notifications. One of <code>SES</code> or <code>SMTP</code>. Default: <code>SES</code>.</td></tr><tr><td style="width: 14.7795%;"><code>email_from</code></td><td style="width: 11.7998%;">string (email)</td><td style="width: 26.2095%;">Required if <code>notifications_enabled</code> is <code>true</code></td><td style="width: 47.2112%;">Sender email address for notifications. For SES, this must be a verified identity. Example: <code>sandboxstudio@example.com</code>.</td></tr><tr><td style="width: 14.7795%;"><code>smtp_server</code></td><td style="width: 11.7998%;">string</td><td style="width: 26.2095%;">Required if <code>email_service</code> is <code>SMTP</code></td><td style="width: 47.2112%;">SMTP server hostname. Example: <code>smtp.example.com</code>.</td></tr><tr><td style="width: 14.7795%;"><code>smtp_username</code></td><td style="width: 11.7998%;">string</td><td style="width: 26.2095%;">Required if <code>email_service</code> is <code>SMTP</code></td><td style="width: 47.2112%;">SMTP username.</td></tr><tr><td style="width: 14.7795%;"><code>smtp_password</code></td><td style="width: 11.7998%;">string</td><td style="width: 26.2095%;">Required if <code>email_service</code> is <code>SMTP</code></td><td style="width: 47.2112%;">SMTP password.</td></tr><tr><td style="width: 14.7795%;"><code>smtp_port</code></td><td style="width: 11.7998%;">string or integer</td><td style="width: 26.2095%;">Required if <code>email_service</code> is <code>SMTP</code></td><td style="width: 47.2112%;">SMTP port number. Default: <code>587</code>.</td></tr><tr><td style="width: 14.7795%;"><code>smtp_use_tls</code></td><td style="width: 11.7998%;">boolean</td><td style="width: 26.2095%;">Required if <code>email_service</code> is <code>SMTP</code></td><td style="width: 47.2112%;">Whether to use TLS for SMTP connections. Default: <code>true</code>.</td></tr></tbody></table>

<p class="callout warning"><strong>Security:</strong> When you use the <code>SMTP</code> email service, the configuration file contains your <code>smtp_password</code> in plain text. Do not commit this file to source control and do not share it. Delete it once the installation is complete, and store any long-lived copy securely.</p>

#### Example configuration files

The examples below use placeholder account IDs, VPC IDs, and subnet IDs. Replace them with your own values.

##### Example 1: New VPC with SES notifications

```json
{
  "namespace": "Sandbox",
  "hub_account_id": "123456789012",
  "parent_ou_id": "ou-xxxx-xxxxxxxx",
  "managed_regions": "us-east-1,eu-west-1",
  "db_instance_type": "t4g.small",
  "db_engine_version": "",
  "idc_app_name": "Sandbox Studio",
  "idc_app_description": "Sandbox Studio allows users to access temporary AWS accounts",
  "admin_group_name": "Sandbox_AdminsGroup",
  "manager_group_name": "Sandbox_ManagersGroup",
  "user_group_name": "Sandbox_UsersGroup",
  "allowed_ip_ranges": "0.0.0.0/1,128.0.0.0/1",
  "use_existing_vpc": false,
  "custom_domain": null,
  "notifications_enabled": true,
  "add_admin_users": true,
  "admin_users": ["admin@example.com"],
  "email_service": "SES",
  "email_from": "sandboxstudio@example.com"
}
```

##### Example 2: Existing VPC, no notifications

```json
{
  "namespace": "SBS",
  "hub_account_id": "123456789012",
  "parent_ou_id": "ou-xxxx-xxxxxxxx",
  "managed_regions": "us-east-1,ap-southeast-1",
  "db_instance_type": "t4g.small",
  "db_engine_version": "",
  "idc_app_name": "Sandbox Studio",
  "idc_app_description": "Sandbox Studio allows users to access temporary AWS accounts",
  "admin_group_name": "Sandbox_Admins",
  "manager_group_name": "Sandbox_Managers",
  "user_group_name": "Sandbox_Users",
  "allowed_ip_ranges": "0.0.0.0/1,128.0.0.0/1",
  "use_existing_vpc": true,
  "vpc_id": "vpc-0123456789abcdef0",
  "database_subnets": "subnet-0aaaa1111bbbb2222,subnet-0cccc3333dddd4444",
  "compute_subnets": "subnet-0eeee5555ffff6666,subnet-07777gggg8888hhhh",
  "custom_domain": null,
  "notifications_enabled": false,
  "add_admin_users": true,
  "admin_users": ["admin-trial", "andy"]
}
```

##### Example 3: Email notifications with SES

This example enables email notifications using Amazon SES. The <code>email_from</code> address must be a verified identity in SES.

```json
{
  "namespace": "Sandbox",
  "hub_account_id": "123456789012",
  "parent_ou_id": "ou-xxxx-xxxxxxxx",
  "managed_regions": "us-east-1,eu-west-1",
  "db_instance_type": "t4g.small",
  "db_engine_version": "",
  "idc_app_name": "Sandbox Studio",
  "idc_app_description": "Sandbox Studio allows users to access temporary AWS accounts",
  "admin_group_name": "Sandbox_AdminsGroup",
  "manager_group_name": "Sandbox_ManagersGroup",
  "user_group_name": "Sandbox_UsersGroup",
  "allowed_ip_ranges": "0.0.0.0/1,128.0.0.0/1",
  "use_existing_vpc": false,
  "custom_domain": null,
  "notifications_enabled": true,
  "email_service": "SES",
  "email_from": "sandboxstudio@example.com"
}
```

##### Example 4: Email notifications with SMTP

This example enables email notifications using an SMTP server. When <code>email_service</code> is set to <code>SMTP</code>, all of the <code>smtp_*</code> fields are required.

```json
{
  "namespace": "Sandbox",
  "hub_account_id": "123456789012",
  "parent_ou_id": "ou-xxxx-xxxxxxxx",
  "managed_regions": "us-east-1,eu-west-1",
  "db_instance_type": "t4g.small",
  "db_engine_version": "",
  "idc_app_name": "Sandbox Studio",
  "idc_app_description": "Sandbox Studio allows users to access temporary AWS accounts",
  "admin_group_name": "Sandbox_AdminsGroup",
  "manager_group_name": "Sandbox_ManagersGroup",
  "user_group_name": "Sandbox_UsersGroup",
  "allowed_ip_ranges": "0.0.0.0/1,128.0.0.0/1",
  "use_existing_vpc": false,
  "custom_domain": null,
  "notifications_enabled": true,
  "email_service": "SMTP",
  "email_from": "sandboxstudio@example.com",
  "smtp_server": "smtp.example.com",
  "smtp_username": "smtp-user",
  "smtp_password": "your-smtp-password",
  "smtp_port": "587",
  "smtp_use_tls": true
}
```

##### Example 5: Custom domain with an ACM certificate

This example serves Sandbox Studio from a custom domain instead of the default CloudFront URL. When <code>custom_domain</code> is set, <code>certificate_arn</code> is required and the certificate must exist in <code>us-east-1</code>.

```json
{
  "namespace": "Sandbox",
  "hub_account_id": "123456789012",
  "parent_ou_id": "ou-xxxx-xxxxxxxx",
  "managed_regions": "us-east-1,eu-west-1",
  "db_instance_type": "t4g.small",
  "db_engine_version": "",
  "idc_app_name": "Sandbox Studio",
  "idc_app_description": "Sandbox Studio allows users to access temporary AWS accounts",
  "admin_group_name": "Sandbox_AdminsGroup",
  "manager_group_name": "Sandbox_ManagersGroup",
  "user_group_name": "Sandbox_UsersGroup",
  "allowed_ip_ranges": "0.0.0.0/1,128.0.0.0/1",
  "use_existing_vpc": false,
  "custom_domain": "sandbox.example.com",
  "certificate_arn": "arn:aws:acm:us-east-1:123456789012:certificate/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "notifications_enabled": false
}
```

#### Support

If you encounter any issues, please contact your Sandbox Studio support team at <support@sandboxstudiosoftware.com> or go to [https://support.sandboxstudiosoftware.com](https://support.sandboxstudiosoftware.com).