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.
• 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).

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.

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

Do not use your root account.

• 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:

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:

nano ~/sbs-config.json

Paste your configuration (see the example configuration files 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 <(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 <(curl -s https://dist.sandboxstudiosoftware.com/install.sh) --config-file ~/sbs-config.json

For more details on the update behaviour, see 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.

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

Database options

Field	Type	Required	Description
db_instance_type	string	Optional	RDS instance type for the PostgreSQL database, without the db. prefix. Default: t4g.small. Examples: t4g.small, t4g.medium, r6g.large.
db_engine_version	string	Optional	PostgreSQL engine version (format X.Y, major version 17 or higher). Leave empty ("") to use the latest default. Example: 17.4.
db_encryption	string	Optional	Enable storage encryption for the RDS database. One of Yes or No. Default: Yes for new installations.

Identity Center application

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

Field	Type	Required	Description
idc_app_arn	string	Conditional	ARN of an existing IAM Identity Center application to use. If provided, an existing application is reused instead of creating a new one. Example: arn:aws:sso::123456789012:application/ssoins-xxxxxxxxxxxxxxxx/apl-xxxxxxxxxxxxxxxx.
idc_app_name	string	Conditional	Display name for a new IAM Identity Center SAML application (used when creating a new application). Default: Sandbox Studio.
idc_app_description	string	Optional	Description for a new IAM Identity Center SAML application. Default: Sandbox Studio allows users to access temporary AWS accounts.

Networking (VPC)

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

Field	Type	Required	Description
vpc_id	string	Required if use_existing_vpc is true	VPC ID to use. Example: vpc-0123456789abcdef0.
database_subnets	string	Required if use_existing_vpc is true	Comma-separated subnet IDs for the database. Minimum 2 subnets in different Availability Zones. Example: subnet-aaa,subnet-bbb.
compute_subnets	string	Required if use_existing_vpc is true	Comma-separated subnet IDs for compute resources. Minimum 1 subnet. Example: subnet-ccc,subnet-ddd.

Custom domain

Field	Type	Required	Description
custom_domain	string or null	Optional	Custom domain name for the application. Set to null to use the default CloudFront URL. Example: sandbox.example.com.
certificate_arn	string	Required if custom_domain is set	ARN of the ACM certificate in us-east-1. Example: arn:aws:acm:us-east-1:123456789012:certificate/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

Administrators

Field	Type	Required	Description
add_admin_users	boolean	Optional	Whether to add IAM Identity Center users as Sandbox Studio administrators during installation. Default: false.
admin_users	array of strings	Optional	List of IAM Identity Center usernames to add as Sandbox Studio administrators. Used when add_admin_users is true. Example: ["admin@example.com", "john.doe"].

Email notifications

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

Field	Type	Required	Description
email_service	string	Required if notifications_enabled is true	Email service to use for notifications. One of SES or SMTP. Default: SES.
email_from	string (email)	Required if notifications_enabled is true	Sender email address for notifications. For SES, this must be a verified identity. Example: sandboxstudio@example.com.
smtp_server	string	Required if email_service is SMTP	SMTP server hostname. Example: smtp.example.com.
smtp_username	string	Required if email_service is SMTP	SMTP username.
smtp_password	string	Required if email_service is SMTP	SMTP password.
smtp_port	string or integer	Required if email_service is SMTP	SMTP port number. Default: 587.
smtp_use_tls	boolean	Required if email_service is SMTP	Whether to use TLS for SMTP connections. Default: true.

**Security:** When you use the SMTP email service, the configuration file contains your smtp_password 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.

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

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

{
  "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"]
}

Support

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