Environment

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.

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
tailscale - Zero-config VPN for secure networking
frpc (v0.65.0) - Fast Reverse Proxy client for tunneling
ttyd (v1.7.7) - Terminal sharing over web

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

Create a .blocks directory in your repository root:
```
mkdir .blocks
```

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

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

Add your installation commands:

Basic Example
Install Custom Binary
Multiple Languages
Database Tools

#!/bin/bash
set -e

# Install Node.js dependencies
npm install

# Install Python dependencies
pip install -r requirements.txt

echo "Post-clone setup complete!"

#!/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

#!/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!"

#!/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

#!/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

Introduction

Platform Integrations

Use Cases

Agents

Features

Sandbox

Workspaces

Getting Help

Overview

What’s Included

Build Tools & Compilers

Programming Languages & Runtimes

Version Control & Collaboration

CLI Utilities

Database Tools

Cloud & Infrastructure

Networking & Remote Access

System Libraries

When You Need Additional Tools

Using Post-Clone Scripts

Creating a Post-Clone Script

Best Practices

Common Use Cases

Installing Language Runtimes

Installing Build Tools

Setting Up Environment Variables

Troubleshooting

Limitations

Next Steps

Plan Mode

Multi-Repo Support

GitHub Integration

Commands

Introduction

Platform Integrations

Use Cases

Agents

Features

Sandbox

Workspaces

Getting Help

​Overview

​What’s Included

​Build Tools & Compilers

​Programming Languages & Runtimes

​Version Control & Collaboration

​CLI Utilities

​Database Tools

​Cloud & Infrastructure

​Networking & Remote Access

​System Libraries

​When You Need Additional Tools

​Using Post-Clone Scripts

​Creating a Post-Clone Script

​Best Practices

​Common Use Cases

​Installing Language Runtimes

​Installing Build Tools

​Setting Up Environment Variables

​Troubleshooting

​Limitations

​Next Steps

Plan Mode

Multi-Repo Support

GitHub Integration

Commands

Overview

What’s Included

Build Tools & Compilers

Programming Languages & Runtimes

Version Control & Collaboration

CLI Utilities

Database Tools

Cloud & Infrastructure

Networking & Remote Access

System Libraries

When You Need Additional Tools

Using Post-Clone Scripts

Creating a Post-Clone Script

Best Practices

Common Use Cases

Installing Language Runtimes

Installing Build Tools

Setting Up Environment Variables

Troubleshooting

Limitations

Next Steps