Startup commands

Run commands in the environment before the agent starts, so the agent finds dependencies installed, services running, and the project built.

To run commands before the agent session starts, add the file .air/cloud/startup.sh under the repository root. JetBrains Air Teams runs this script in the cloud environment after it clones the repository but before the agent starts working on the task.

Use this script for environment setup, for example, to install tools, prepare configuration files, or initialize project-specific resources.

The list below describes how the startup script works and how to use it:

When it runs – every time JetBrains Air Teams starts the cloud environment for the task, both when you first create the task and every time you resume it later.
Run order – the script runs after JetBrains Air Teams clones the repository but before the agent starts. The repository is already checked out, and the script starts in the project root. Note that the checkout is shallow – it contains only the latest commit.
User – the script runs as the environment user with sudo rights.
Access to environment variables – the script can read everything already present in the environment, including the variables and secrets from your environment configuration.
Set variables for the agent – the script runs in a separate process, so variables you export in it are not passed to the agent session. To make a variable available to the agent, append it to ~/.bashrc. Add it only when it isn't already present so that resuming the task doesn't create duplicate entries (see below).
Idempotency – make the script idempotent.
JetBrains Air Teams runs the script on every environment launch – not only the first time. That includes resuming the task and starting a new task from a snapshot, where the tools and files from an earlier run are already in place. A script that isn't idempotent can repeat heavy setup or leave the environment in a broken state.
- Write the script so that it's safe to run repeatedly and does nothing when the setup is already in place.
- Guard each step so that resuming a task doesn't reinstall dependencies or re-apply the configuration that's already there, and skip expensive one-time work when a marker from a previous run is present.
The following example installs a tool, prepares a configuration directory, and sets a variable for the agent. Each step is skipped when the work is already done, so the script does nothing on resume:
#!/bin/sh set -e # Install tools only if they are missing if ! command -v jq >/dev/null; then apt-get update apt-get install -y jq fi # Create the configuration directory if it doesn't exist mkdir -p ~/.config/my-tool # Add a variable for the agent only once grep -q MY_TOKEN ~/.bashrc || echo 'export MY_TOKEN=secret-value' >> ~/.bashrc
Execution timeout – by default, the script has 600 seconds to finish, and JetBrains Air Teams stops it when that time runs out. To change the limit, set Execution timeout, sec in the Startup Script section of the environment configuration. Allowed values are 1–3600 seconds.
Logs – the startup script output is included in the environment logs, which you can download for debugging.
Failure behavior – if the script exits with a non-zero code, the task still starts and the agent runs. Check the logs to confirm the script completed as expected.

30 September 2026