Administrator Guide

As an Administrator, you are responsible for configuring and maintaining Sandbox Studio for your organisation. This includes setting global policies such as global maximum budget thresholds and cleanup policies. You will also manage integration with AWS, set up permissions and guardrails, and provision new sandbox accounts when required.

Beyond initial setup, you’ll regularly monitor account activity, review system alerts, and ensure the platform remains secure, compliant, and cost-effective. This guide will walk you through the key administrative tasks, from first-time configuration to ongoing monitoring and troubleshooting.

Home Page

After logging into the Sandbox Studio UI, as an Administrator, you will land on your Administrator's Home page.

As a Sandbox Studio Administrator, you have the capability of requesting and accessing AWS Accounts yourself, overseeing the end user accounts as a manager would, as well as the global overview of your entire AWS Sandbox environment. 

Therefore the Administrator's homepage is divided into three sections, both on the main page and the left menu:

image.png

image.png

image.png

The rest of this Administrators Guide, will focus on features specific to Administrators.

    It is really important to monitor the duration and budget on all of your own and your users accounts.  If they reach their thresholds , the accounts will (depending how your Sandbox Studio environment is setup) terminate and delete everything in that account.  So if what you or your users are working on is important, closely monitor the thresholds and/or move the account out of the sandbox environment into a production environment.  Users can request an account extension from their manager or administrator.

    AWS Accounts

    AWS Accounts

    AWS Accounts

    As an Administrator, by clicking on the AWS Accounts (1) link in the Administrator section of the left menu, the Administrator can access the Accounts Summary page. 

    image.pngAccount Sumary

    Let's look at some of these in more detail.

    By clicking on the Account ID (1), this provides more details on the AWS Account itself, including the account email and account name  (2) as well as the Account Usage History (3) of which user / account template was associated with this AWS Account in the past. 

    image.png

    By clicking on the View current lease (1), link, this provides more details on the Lease associated with the AWS Account.  From this page, the Administrator can do various things including Login to the account (2)  and Update (3) (change) the Budget or Duration of the lease. 

    image.png

    Settings

    This section will cover details of the settings and configuration capabilities for Administrators

    Settings

    System Settings

    The Administrator has access to a wide range of advanced settings from the System Settings (1) menu on the left hand menu. This page will detail each of the following sections: 

    image.png

    General Settings

    In the General Settings section, the Administrator can make the following configuration changes by clicking on the Update (1) button :

    Unless requested by the Sandox Studio team for support purpose, please avoid changing this value.

    image.png

     
    Lease Settings

    In the Lease Settings section, the Administrator can make the following configuration changes by clicking on the Update (1) button:

    Leases shared don't count towards this value

    image.png

    Terms of Service

    An Administrator may wish to get the users of their sandbox accounts to agree to certain Terms of Service before they access their sandbox environments.  An Administrator is able to edit these Terms of Service and also keep a record of previous versions that users agreed too. 

    Within the Terms of Service page, the Administrator is able to view (1) the existing terms of service, Edit (2) the terms of service and view the version history (3) of previous versions of Terms of Service.

    image.png

     

    Authentication Settings

    In the Authentication Settings section, the Administrator can make the following configuration changes by clicking on the Update button :

    image.png

    Changing those settings may break your Sandbox Studio installation, please update carefully!

    Account Monitoring

    In the Account Monitoring section, the Administrator can trigger the following checks manually:

    image.png

    Settings

    Display Settings

    image.png

     

    Please refer to UI Customisation for more details about Display Settings.

    Settings

    Email Settings

    As an Administrator you have control over what and how notifications are sent. From the left hand menu, select Settings > Email Settings (1):

    image.png

    Two tabs are available:

    1. Delivery Settings: Allows to configure how emails are sent, either through Amazon Simple Email Service (SES) or through a standard SMTP server.
    2. Notifications: Allows to select what notifications are sent to users, managers or approvers. In the current version of Sandbox Studio, this settings applies for all users.

    Delivery Settings

    Configure SMTP server
    image.png
    1. Select SMTP Server
    2. Set the SMTP Server address
    3. SMTP Port
    4. SMTP Username
    5. SMTP Password
    6. Use TLS for authentication

    Configure Simple Email Service (SES)

    image.png

    For SES to work, you need to have a verified identity in your SES environment in the Hub account. More details here: https://docs.aws.amazon.com/ses/latest/dg/verify-addresses-and-domains.html

    This verified identity needs to:

    We recommend having a domain verified identity and have your environment out of the SES Sandbox. https://docs.aws.amazon.com/ses/latest/dg/request-production-access.html

    Notifications

    In the notification tab, you can select the notifications you want Sandbox Studio to send. Those notifications can be for leases lifecycle (Lease created, lease shared, ...), for events (Event created, event started, etc.) but also for administrative tasks (ie: account failed setup, or account failed cleanup) 

    image.png

    In this version of Sandbox Studio, the modifications on the notifications will apply for ALL users. eg: if you disable the notifications for leases, no user will receive notification for when leases are created.

    Settings

    Cleaner Settings

    An Administrator is able to control and change the way that the AWS Accounts are cleaned/recycled at the end of a lease.  This is task is completed by an open-source tool called AWS Nuke.  However, in some instances an Administrator may wish to modify the way that the accounts are cleaned to preserve or delete certain resources.  This can be done through the Cleaner Settings (1) menu on the left hand menu.


    image.png

     

    1. AWS Nuke Binary URL: URL of the Linux aws-nuke binary used for account cleanup. This allows you to use the latest available AWS Nuke version as soon as it's released.

    You can find the latest releases links here: https://github.com/ekristen/aws-nuke/releases

    Distribution: Linux, AMD64

    1. Max Failed Cleanup Attempts: In certain circumstances, AWS Nuke fails to cleanup resources from the first try. Sandbox Studio to retry on error. This setting help defines how many times it needs to retry.
    2. Retry Wait Time: Time to wait between retries when cleanup fails.
    3. Successful Attempts Required: Number of successful cleanup to execute before Sandbox Studio marks the cleanup as successful. In this example, Nuke will run 2 times and if both execution succeed, the account will be marked as successfully cleaned up.
    4. Success Wait Time: The number of seconds to wait before rerunning a successful attempt
    5. AWS Nuke Configuration

    Refer to AWS Nuke documentation for more details. 

    Settings

    Subscription

    On the Subscription page, an Administrator can view their Sandbox Studio current licensing entitlements and usage.

    Subscription page

    The Subscription page shows the current status of the licence, how many AWS accounts are allowed, the API key used to connect to Sandbox Studio for updates and the duration of the licence. 

    image.png

    Account Usage

    On the account usage page, the Administrator can view how many accounts are in use and what the maximum number of AWS accounts are allowed.

    image.png


    Monitoring the solution

    Monitoring the solution

    Monitoring the solution

    Overview

    The Sandbox Studio solution includes observability tools for monitoring the solution resources.

    Amazon CloudWatch Application Insights

    Sandbox Studio on AWS includes access to Amazon CloudWatch Application Insights to provide automatic detection and alerting for any errors raised by the solution. When a recurring error is detected within the solution, Application Insights will raise an alarm indicating the potential problem.

    Currently, active alarms are displayed in the AWS Cloudwatch Console Dashboard. You can also view an overview of all current and previously detected issues for the solution using the CloudFormation Application Insights console.

    CloudWatch Application Insights helps you monitor your applications by identifying and setting up key metrics, logs, and alarms across your application resources and your technology stack. It continuously monitors metrics and logs to detect and correlate anomalies and errors. To assist with troubleshooting, it creates automated dashboards for detected problems, which include correlated metric anomalies and log errors, along with additional insights to identify a potential root cause.

    To view the CloudWatch AppInsights dashboard for Sandbox Studio:

    The dashboard displays various metrics and logs for your solution.

    Cloudwatch log queries

    Note:  By default, Sandbox Studio will retain all compute logs for one year. You can change this retention period as part of the solution’s Compute stack CloudFormation parameters.

    Sandbox Studio provides several pre-populated AWS CloudWatch log insights queries that allow you to troubleshoot issues.

    To access log insights queries:

    The logs section will display the compute logs for the solution.

    AWS X-Ray

    Sandbox Studio includes access to AWS X-Ray for all critical execution paths. This allows you to troubleshoot any failing workflows and identify where the errors are occurring.

    image.png

    Troubleshooting & Support

    If you need support, there is a full knowledge base and ticketing site here:

    https://support.sandboxstudiosoftware.com/

    Below are some common problems identified during installation.

    Troubleshooting & Support

    Investigating accounts in Quarantine state

    When the Sandbox Studio solution detects an issue with one of its sandbox accounts, the account is moved to a Quarantine state and an email is sent to the solution administrators indicating that action be taken to resolve the account’s quarantine status.

    Note:  If the account clean-up mechanism fails to automatically delete resources at the end of an active lease, you might have accounts in a Quarantine state. We highly recommend investigating quarantined accounts as quickly as possible, as these accounts can incur costs for resources running inside these accounts.

     

    To resolve the quarantined status:

     

    If the account is in quarantine if the retry clean up failed, refer to the Resolving cleanup failures section.

    Troubleshooting & Support

    Resolving clean-up failures

    If the cleanup process fails to completely clean an account at the end of a lease, Sandbox Studio will move the account into a Quarantine state, and email the Administrators notifying them of the issue.

    To resolve an account that has failed clean-up:

    1. Log in to the Web UI as an Administrator, and from the left, under Administration, select AWS Accounts.

    2. Confirm the account that has failed the clean-up process. You can preview the error by hovering your mouse over the "Clean-up error" textimage.png

    For a detailed view of the error, you need to access the AWS Console and look at the "AccountCleaner" step functions

    image.png

    See log details:

    1. Log in to the AWS Console using the Hub account, and navigate to the CloudWatch > Logs Insights page.

    2. From the right pane, under Sample queries, select the SS-Sandbox group, and from the dropdown, choose the AccountCleanupLogs saved query, and Apply.

    image.png

    3. Change the time frame to match the execution you want to get the logs for:

    image.png

    4. Update the query to copy the last cleanup process ID:

    image.png

    You can get the cleanup process ID from the  'Last Cleanup ReferenceID'.

    Select Run query to see related events. The log information is displayed under the Logs tab.

    Maintenance

    Maintenance

    Backup of the solution

    The following elements need to be backed up on a regular basis:

     

    1. Sandbox Studio Database (RDS)

    Sandbox Studio stores its data into a relational database hosted on Amazon RDS. As a precaution, backup this database regularly.

    This database is named sandbox-studio-rds and is hosted in the Hub Account.

     

    2. Launch Templates configuration (S3)

    For Launch Templates (Creating resources on new sandbox accounts), Sandbox Studio will save buildspec files into Amazon S3. This S3 bucket needs to be backed up regularly.

    You can find this S3 bucket in the Hub Account with the name: sandboxstudio-compute-s3bucketbuildspecfiles<XXXXXXX>

    The exact name of the S3 bucket can be found in the SandboxStudio-Compute Cloudformation stack, in the output DeploymentFilesBucketName

     

    3. Configuration (AppConfig)

    We also recommand backing up the configurations you define in AppConfig for the following configs:

     

    Updating the solution

    Updating the solution

    Monitor for updates

    Automatic Update Alerts

    When a new version of Sandbox Studio is available, administrators will receive an update notification that appears in their left menu. This notification system is designed to keep administrators informed of significant updates without overwhelming them with minor changes.

    image.png

    Important: Only Major and Minor version updates will trigger this notification. Patch updates will not generate automatic notifications in the left menu.

    Administrators have the option to dismiss these update notifications if they choose to postpone the update. Only new major/minor updates will trigger another notification.

    Manual Update Check

    For administrators who want more control or need to check for patch updates, a manual check option is available:

    1. Navigate to Advanced Settings
    2. Click on "Check for updates"
    3. The system will display the latest available updates, including patches

    This manual check provides visibility into all version types and allows administrators to stay completely up-to-date, even with the smaller patch releases that don't trigger automatic notifications.

    image.png

    Understanding Version Numbers

    Software versions follow a three-part numbering system: Major.Minor.Patch (for example, 2.5.3)

    UI Customisation

    UI Customisation

    How to display users profile pictures

    Starting with version 1.1.0 of Sandbox Studio, users' profile pictures can be displayed in the interface:

    image.png



    IAM Identity Center

    IAM IdC has a specific attribute for profile picture URL:

    image.png

    This is the field that you need to map from your IdP in order to show the profile picture.

    UI Customisation

    Display Settings - Change default language

    To change the default language of your Sandbox Studio installation, go to "Settings" > "Display Settings" (1) and click on "Update" in the "Language Settings" section (2):

    image.png

    Then select the language and "Update":

    image.png

    Default language will be used if users have not selected their default language.

    UI Customisation

    Display Settings - Change header logo

    To change the default language of your Sandbox Studio installation, go to "Settings" > "Display Settings" (1) and click on "Update" in the "Header Logo" section (2):

    image.png

    You can now select your custom header image:

    image.png


    1. Upload your image file. We recommend using transparent background so the logo displays flawlessly.
    2. You can choose to have a different logo for dark mode. If this option is left unticked, the same logo as the first one is used.

    image.png

    UI Customisation

    Display Settings - Change theme colour

    To change the theme colour of your Sandbox Studio installation, go to "Settings" > "Display Settings" (1) and click on "Update" in the "Colour Settings" section (2):

    image.png

    You can now select your custom colours:

    image.png

    1. Primary Colour. This colour is used for buttons, menu items, etc.
    2. Navigation Bar. This colour is used for the top bar of Sandbox Studio

    image.png

    You can also change the colours that display for the dark mode. For instance:

    image.png

    image.png