Init Scripts

Run setup commands when the sandbox starts to install packages or configure the environment.

Init scripts run automatically when a sandbox container starts. Use them to install packages, configure tools, or set up the environment before the assistant runs analysis code.

What are init scripts?

Init scripts are shell commands that run once when a new sandbox is created. They let you customize the sandbox environment for your organization's needs:

Install CLI tools and packages
Configure authentication
Set up shell configuration
Pre-clone repositories

Init scripts run as the root user and have full access to the sandbox environment. They execute once at container creation, not on every code execution.

Configuring init scripts

Navigate to sandbox settings

Go to Settings in your project, then select Sandbox from the sidebar.

Enter your init script

In the init script text area, enter the shell commands you want to run when the sandbox is created.

Save changes

Click Save to apply your init script. New sandboxes will run the script on creation.

Changes to init scripts only affect newly created sandboxes. Existing sandboxes continue using the script they were created with.

Example init scripts

Installing CLI tools

# Install Node.js packages globally
npm install -g @company/internal-cli typescript

# Install Python packages
pip install pandas numpy company-tools

# Install system packages
apt-get update && apt-get install -y jq

Configuring authentication

# Set up CLI authentication using environment variables
echo "export API_KEY=$API_KEY" >> ~/.bashrc
echo "export API_ENDPOINT=$API_ENDPOINT" >> ~/.bashrc

# Configure git
git config --global user.email "bot@company.com"
git config --global user.name "Investigation Bot"

Cloning repositories

# Clone internal repositories
git clone https://github.com/company/scripts.git ~/scripts
git clone https://github.com/company/configs.git ~/configs

# Set up PATH
echo 'export PATH="$HOME/scripts/bin:$PATH"' >> ~/.bashrc

Complete example

#!/bin/bash
set -e

# Install required packages
apt-get update && apt-get install -y jq curl
pip install pandas numpy requests
npm install -g @company/cli

# Configure authentication
echo "export COMPANY_API_KEY=$COMPANY_API_KEY" >> ~/.bashrc

# Clone helper scripts
git clone https://github.com/company/investigation-scripts.git ~/scripts
echo 'export PATH="$HOME/scripts/bin:$PATH"' >> ~/.bashrc

# Verify setup
source ~/.bashrc
company-cli --version

Execution details

Property	Value
Runs as	Root user
Timeout	120 seconds
Execution	Once per sandbox creation
Shell	`/bin/bash`
Working directory	`/root`

Environment variables configured in your project settings are available during init script execution.

Use cases

Installing CLI tools: Add organization-specific CLIs, language tools, or utilities that the assistant might need during investigations.

Configuring authentication: Set up credentials for internal APIs or services that investigation scripts might call.

Setting up development environment: Configure shell settings, install language runtimes, or set up debugging tools.

Pre-cloning repositories: Clone helper scripts, configuration files, or code that is frequently needed during investigations.

Debugging init scripts

If your init script fails, new sandboxes will not be created successfully. To debug:

Check sandbox logs

Sandbox creation logs show init script output including any errors. Look for failed commands or missing dependencies.

Test commands manually

Before adding commands to your init script, test them in an interactive sandbox session to verify they work.

Use fail-fast mode

Add set -e at the top of your script to exit immediately on any error. This makes it easier to identify which command failed.

Add verbose output

Use set -x to print each command before execution, helping you trace exactly where failures occur.

Limitations

Keep these limitations in mind when writing init scripts.

120 second timeout: Scripts that take longer will be terminated. Keep installs minimal and use pre-built packages where possible.
No user interaction: Init scripts cannot prompt for input. All configuration must be automatic.
Environment variable timing: Some environment variables may not be fully available during early init script execution. Source .bashrc if you need variables set in the script to be available.
Network access required: Package installation requires network access. If packages fail to download, check that the sandbox has connectivity.
No persistence across threads: Each thread gets a fresh sandbox, so init scripts run for each new thread. Avoid lengthy setup if possible.

On this page