Environments

Environment variables allow you to securely pass configuration values to your tasks. The Box supports both global environment variables and repository-specific ones.

Overview

Environment variables are key-value pairs that are injected into the sandbox when Claude runs your task. They're useful for:

• API keys and secrets
• Database connection strings
• Service URLs
• Feature flags
• Any configuration that varies between environments

Types of Environment Variables

Global Environment Variables

Global environment variables are available to all your tasks, regardless of which repository they're working on.

Best for:

• API keys used across multiple projects (OpenAI, Stripe, etc.)
• Personal access tokens
• Common service URLs

How to configure:

1. Go to Settings page
2. Find the Global Environments section
3. Click Add Variable
4. Enter the key and value
5. Save changes

Repository Environment Variables

Repository-specific environment variables are only available when working on that specific repository.

Best for:

• Project-specific API keys
• Database URLs
• Project configuration
• Secrets that should only be used with one project

How to configure:

1. Go to Settings page
2. Find the repository you want to configure
3. Click on the repository settings
4. Find the Environment Variables section
5. Add your variables
6. Save changes

Priority Order

When the same variable name exists in both global and repository environments, repository-specific variables take priority.

Repository ENV  →  Takes priority (used)
Global ENV      →  Fallback (used if not in repo)

This allows you to:

• Set default values globally
• Override them for specific repositories when needed

How to Use

Environment variables are automatically available in the sandbox. Claude and any scripts can access them:

In Shell Scripts

# Access directly
echo $DATABASE_URL

# Use in commands
curl -H "Authorization: Bearer $API_KEY" https://api.example.com

In Node.js

// Access via process.env
const apiKey = process.env.API_KEY;
const dbUrl = process.env.DATABASE_URL;

In PHP

// Access via getenv or $_ENV
$apiKey = getenv('API_KEY');
$dbUrl = $_ENV['DATABASE_URL'];

In Python

import os

api_key = os.environ.get('API_KEY')
db_url = os.environ.get('DATABASE_URL')

In Go

import "os"

apiKey := os.Getenv("API_KEY")
dbUrl := os.Getenv("DATABASE_URL")

In Rust

use std::env;

let api_key = env::var("API_KEY").unwrap();
let db_url = env::var("DATABASE_URL").unwrap();

Security

Best Practices

1. Never commit secrets — Use environment variables instead of hardcoding secrets
2. Use specific scopes — Use repository-specific variables when possible
3. Rotate regularly — Change API keys and secrets periodically
4. Limit permissions — Use API keys with minimum required permissions

How Variables Are Protected

• Variables are encrypted at rest
• Variables are only decrypted when injected into the sandbox
• Variables are never logged or exposed in task outputs
• Each sandbox is isolated from others

Common Variables

Here are some commonly used environment variables:

API Keys

Database

Services

Example: Setting Up a Project

Here's a complete example of setting up environments for a typical project:

1. Global Variables

Set these in Settings → Global Environments:

GITHUB_TOKEN=ghp_xxxxxxxxxxxx
OPENAI_API_KEY=sk-xxxxxxxxxxxx

2. Repository Variables

Set these in Settings → Repository → Environment Variables:

DATABASE_URL=postgresql://user:pass@host:5432/dbname
REDIS_URL=redis://localhost:6379
APP_SECRET=your-app-secret-key

3. Setup Script

Create a setup script that uses these variables:

# Install dependencies
bun install

# Run migrations using DATABASE_URL
bun run db:migrate

# Seed database
bun run db:seed

Now when Claude works on your task, all these variables will be available automatically!

Troubleshooting

Variable Not Available

If a variable isn't available in your task:

1. Check if it's saved correctly in Settings
2. Verify the variable name (case-sensitive)
3. Check if it's in the correct scope (global vs repository)

Variable Value Incorrect

If a variable has the wrong value:

1. Check for typos in the value
2. Check if a repository variable is overriding a global one
3. Make sure you saved the changes