---
title: Configure sandbox profiles
description: "Configure repository setup and startup scripts, build reusable filesystem snapshots, and inspect the sandbox profile Smart Gate uses for pull requests."
product: general
lang: en
token_estimate: 1329
---
# Configure sandbox profiles

A sandbox profile defines how Smart Gate prepares a repository or folder for coding and verification. A profile build saves the repository, installed dependencies, and tools in a reusable filesystem snapshot. Customize a profile when your repository needs setup steps that automatic setup doesn't discover.

> For AI agents: a documentation index is available at [/llms.txt](/llms.txt). Append `.md` to any page URL for markdown, or send `Accept: text/markdown`.

## Open a sandbox profile

You need permission to edit Smart Gate settings and a repository connected through the Statsig GitHub App. If you haven't connected the repository, follow [Set up Smart Gate](https://docs.statsig.com/smart-gate/set-up).

1. Open the Smart Gate settings from _Settings > Integrations > Statsig GitHub App_.
2. On the _Repositories_ tab, expand the repository and find the folder row you want to configure.
3. In the _Sandbox profile_ column, select **Customize** to create a profile or **Configure** to edit an existing profile.
4. Select **Configuration** in the profile drawer.

A folder without its own profile can inherit a parent folder's profile. Select **Save and build** to give that folder its own profile. If the settings page says **Save to customize**, save your repository settings first. If profile controls aren't available, contact your Statsig account team.

## Configure setup and startup scripts

Use the _Setup script_ setting for toolchain installation, dependency installation, and required build or code-generation steps. The setup script runs during a snapshot build.

| Setup option | When to use it |
| --- | --- |
| Automatic | Let Smart Gate work out the installation steps from repository setup instructions and configuration. Start here unless your repository needs custom steps. |
| Script in the repository | Use a checked-in setup script, such as `scripts/sandbox-setup.sh`. |
| Inline script | Enter shell commands directly in the profile. |

Use the _Startup script_ setting for work that each new sandbox needs after checkout, such as starting required services. Choose **None**, **Script in the repository**, or **Inline script**. Keep dependency installation in the setup script so Smart Gate can reuse the installed files from the snapshot.

Write scripts that work in the default Linux sandbox image. Make scripts safe to run again, and keep verification focused on the repository or folder the profile serves. Never put tokens, passwords, or other secrets in scripts or setup learnings. Organization members can read these values.

## Build a snapshot

Select **Save and build** to save the profile configuration and start a snapshot build. The build uses the default sandbox image, checks out the repository, prepares the toolchain, verifies the setup, and captures the filesystem for later runs.

Setup verification checks whether tools can execute commands such as lint, typecheck, and focused tests. Existing source-code errors can still appear in those checks. A usable toolchain doesn't mean every check passes on every pull request.

To try configuration changes without changing the artifact Smart Gate uses, select **Test build**. Test builds retain their build details and logs, but Smart Gate doesn't use their artifacts for pull requests or save their new setup learnings. Select **Save and build** when you're ready to publish a reusable snapshot.

## Inspect build results

Open the _Builds_ tab in the profile drawer and select a build to inspect its details.

- **Status and duration**: Check the build status and how long the build takes.
- **Usable until**: Check the snapshot's expiration date. Rebuild the profile when its snapshot approaches expiration.
- **Logs**: Inspect setup, installation, verification, and capture output to diagnose a failed build.
- **Source commit and scripts**: Confirm which repository revision and setup configuration the build used.
- **Snapshot details**: Inspect the snapshot ID, size, and base image when you need to identify an artifact.
- **Setup learnings**: Read observations from the build. Successful saved builds can update the profile's read-only learnings for future builds.

Check the profile's active build indicator to confirm which snapshot Smart Gate selects. A newer build in the history doesn't necessarily replace the active snapshot.

## How Smart Gate uses snapshots

Smart Gate restores a usable snapshot for the profile, checks out the pull request's code, and verifies the environment before coding. It can attempt repairs for requirements that differ from the saved snapshot.

A successful saved build can become the profile's active snapshot. Smart Gate checks that the snapshot matches the repository and folder and has enough usable lifetime remaining. It excludes expired snapshots and test-build artifacts. If the active snapshot is unavailable, Smart Gate looks for another compatible, usable snapshot.

If toolchain setup fails and the profile has no usable prepared snapshot, Smart Gate can retain a snapshot containing only the repository checkout. This reduces repeated cloning, but it doesn't provide verified lint, typecheck, or test tools. Smart Gate prefers a prepared snapshot when one is available. A failed build doesn't displace a usable prepared snapshot.