Environment

Understanding the Blocks sandbox and how to customize it for your needs

Overview

When Blocks agents work on your code, they execute in a secure sandbox environment. Each sandbox is based on the Blocks base image, which comes pre-installed with common development tools, programming languages, and CLI utilities. This ensures agents can immediately start working without waiting for basic dependencies.

Sandbox Compute Properties

Each sandbox environment provides the following compute resources:

• CPU: 2 vCPUs
• Memory: 4GB RAM
• Architecture: AMD64 (x86_64)
• Operating System: Debian Trixie (13.3)

These specifications ensure consistent performance across all Blocks sessions while providing sufficient resources for most development tasks.

If you need a more compute for your workloads, contact us at [e-mail].

What’s Included

The Blocks base image includes a comprehensive set of tools organized by category:

Build Tools & Compilers

Essential tools for compiling and building code:

• build-essential - Meta-package including GCC, G++, Make, and other build tools
• gcc - GNU C Compiler
• g++ - GNU C++ Compiler
• make - Build automation tool
• pkg-config - Library compilation helper
• libssl-dev - SSL development libraries

Programming Languages & Runtimes

Pre-installed language toolchains:

• Node.js - JavaScript runtime with npm package manager
• Rust - Stable toolchain via rustup (includes cargo, rustc, rustfmt)

Version Control & Collaboration

Tools for working with repositories:

• git - Distributed version control system
• gh - Official GitHub CLI for managing issues, PRs, and repositories
• glab (v1.80.4) - GitLab CLI for GitLab workflows

CLI Utilities

Common command-line tools:

• curl - Data transfer tool
• jq - JSON processor
• unzip - Archive extraction
• procps - Process monitoring utilities (ps, top, etc.)
• sudo - Privilege escalation
• ripgrep - Fast recursive search tool (rg)
• vim - Text editor
• direnv - Environment variable manager

Database Tools

• postgresql-client - PostgreSQL client tools (psql, pg_dump, etc.)

Cloud & Infrastructure

Tools for cloud services and infrastructure:

• AWS CLI - Amazon Web Services command-line interface (via pip)
• Pulumi ESC CLI - Pulumi Environments, Secrets, and Configuration

Networking & Remote Access

• openssh-client - SSH client for secure remote connections

System Libraries

Required libraries for graphical and system operations:

• ca-certificates - Common CA certificates for SSL/TLS
• libxcb1 - X11 protocol C-language binding
• libx11-6 - X11 client library
• libx11-xcb1 - X11/XCB interop library

When You Need Additional Tools

While the base image includes many common tools, your project may require additional dependencies:

• Language-specific tools - Python (pip packages), Ruby (gems), Go binaries
• Database clients - MySQL, MongoDB, Redis clients
• Build tools - Gradle, Maven, CMake
• Testing frameworks - pytest, Jest, RSpec
• Custom binaries - Project-specific CLI tools
• Cloud provider tools - Google Cloud SDK, Azure CLI, Terraform

Using Post-Clone Scripts

To add custom binaries or install additional tools, use post-clone scripts. These scripts run automatically after Blocks clones your repository and before the agent starts working.

Creating a Post-Clone Script

1. Create a .blocks directory in your repository root:

   mkdir .blocks
   

2. Create a script file named post-clone or post-clone.sh:

   touch .blocks/post-clone
   chmod +x .blocks/post-clone
   

3. Add your installation commands:

Basic Example

#!/bin/bash
set -e

# Install Node.js dependencies
npm install

# Install Python dependencies
pip install -r requirements.txt

echo "Post-clone setup complete!"

Install Custom Binary

#!/bin/bash
set -e

# Download and install a custom CLI tool
curl -L https://example.com/tool.tar.gz -o /tmp/tool.tar.gz
tar -xzf /tmp/tool.tar.gz -C /usr/local/bin
chmod +x /usr/local/bin/tool

# Verify installation
tool --version

Multiple Languages

#!/bin/bash
set -e

# Install Python and its packages
apt-get update && apt-get install -y python3 python3-pip
pip3 install pytest black flake8

# Install Go
GO_VERSION=1.21.0
curl -L https://go.dev/dl/go${GO_VERSION}.linux-amd64.tar.gz | tar -xz -C /usr/local
export PATH=$PATH:/usr/local/go/bin

# Install project dependencies
npm ci
go mod download

echo "All dependencies installed!"

Database Tools

#!/bin/bash
set -e

# Install MySQL client
apt-get update && apt-get install -y mysql-client

# Install MongoDB tools
curl -L https://fastdl.mongodb.org/tools/db/mongodb-database-tools-ubuntu2204-x86_64-100.9.4.deb -o /tmp/mongo-tools.deb
dpkg -i /tmp/mongo-tools.deb

# Install Redis CLI
apt-get install -y redis-tools

echo "Database tools installed!"

Best Practices

Use set -e for error handling

Always start your script with set -e to exit immediately if any command fails:

#!/bin/bash
set -e
# Your commands here

This prevents the agent from starting work with incomplete dependencies.

Make scripts idempotent

Design scripts to run safely multiple times:

#!/bin/bash
set -e

# Check if tool already exists
if ! command -v mytool &> /dev/null; then
    echo "Installing mytool..."
    curl -L https://example.com/mytool -o /usr/local/bin/mytool
    chmod +x /usr/local/bin/mytool
else
    echo "mytool already installed"
fi

Cache dependencies when possible

Use lock files to speed up installation:

#!/bin/bash
set -e

# Use npm ci instead of npm install for faster, reproducible installs
npm ci

# Use pip with hashes for security
pip install --require-hashes -r requirements.txt

Log progress clearly

Add echo statements to help debug issues:

#!/bin/bash
set -e

echo "Installing system dependencies..."
apt-get update && apt-get install -y python3-dev

echo "Installing Python packages..."
pip install -r requirements.txt

echo "Running database migrations..."
python manage.py migrate

echo "Post-clone setup complete!"

Keep scripts fast

Only install what you need:

#!/bin/bash
set -e

# BAD: Installs everything
apt-get install -y build-essential python3-dev libpq-dev mysql-client mongodb-tools

# GOOD: Only installs what this project needs
apt-get install -y python3-dev libpq-dev

Common Use Cases

Installing Language Runtimes

Python

#!/bin/bash
set -e

# Install Python 3.11
apt-get update && apt-get install -y python3.11 python3.11-dev python3-pip

# Install poetry for dependency management
curl -sSL https://install.python-poetry.org | python3 -
export PATH="/root/.local/bin:$PATH"

# Install project dependencies
poetry install --no-root

Installing Build Tools

#!/bin/bash
set -e

# Install CMake
CMAKE_VERSION=3.27.0
curl -L https://github.com/Kitware/CMake/releases/download/v${CMAKE_VERSION}/cmake-${CMAKE_VERSION}-linux-x86_64.sh -o /tmp/cmake.sh
sh /tmp/cmake.sh --prefix=/usr/local --skip-license

# Install Ninja build system
apt-get update && apt-get install -y ninja-build

# Build project
cmake -B build -G Ninja
ninja -C build

Setting Up Environment Variables

#!/bin/bash
set -e

# Create .env file from template
cp .env.example .env

# Set development environment
export NODE_ENV=development
export DATABASE_URL=postgresql://localhost:5432/myapp_dev

# Load direnv if .envrc exists
if [ -f .envrc ]; then
    direnv allow
fi

# Install dependencies
npm ci

Troubleshooting

Script fails silently

Ensure you’re using set -e at the start of your script. Without it, errors are ignored and the agent continues with incomplete setup.

#!/bin/bash
set -e  # Add this!

Tool not found during agent execution

Make sure binaries are installed in a directory on the PATH (/usr/local/bin, /usr/bin) or export PATH in your script:

export PATH="/custom/path/bin:$PATH"
echo 'export PATH="/custom/path/bin:$PATH"' >> ~/.bashrc

Permission denied errors

Ensure scripts and binaries have execute permissions:

chmod +x /usr/local/bin/mytool
chmod +x .blocks/post-clone

Script takes too long

Optimize installation steps:

• Use apt-get install -y to skip prompts
• Use npm ci instead of npm install
• Cache downloads when possible
• Only install required dependencies

Limitations

Ephemeral Environment: Each Blocks session runs in a fresh sandbox. Changes made during agent execution (installed packages, generated files) are not persisted between sessions. Always use post-clone scripts for reproducible setup.

Root Access: Post-clone scripts run with sudo privileges, allowing installation of system packages. Use this power responsibly and only install trusted software.

Next Steps

Plan Mode

Learn how Plan Mode can help design your post-clone script

Multi-Repo Support

Working across multiple repositories with different dependencies

GitHub Integration

Managing post-clone scripts in GitHub repositories

Commands

Create custom commands for common workflows