> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blocks.team/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Note>
  If you need a more compute for your workloads, contact us at [dev@blocksorg.com](mailto:dev@blocksorg.com).
</Note>

## 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. Learn more about [Post-Clone Scripts](/using-blocks/features/post-cloning).

### Creating a Post-Clone Script

1. Create a `.blocks` directory in your repository root:
   ```bash theme={null}
   mkdir .blocks
   ```

2. Create a script file named `post-clone` or `post-clone.sh`:
   ```bash theme={null}
   touch .blocks/post-clone
   chmod +x .blocks/post-clone
   ```

3. Add your installation commands:

<Tabs>
  <Tab title="Basic Example">
    ```bash theme={null}
    #!/bin/bash
    set -e

    # Install Node.js dependencies
    npm install

    # Install Python dependencies
    pip install -r requirements.txt

    echo "Post-clone setup complete!"
    ```
  </Tab>

  <Tab title="Install Custom Binary">
    ```bash theme={null}
    #!/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
    ```
  </Tab>

  <Tab title="Multiple Languages">
    ```bash theme={null}
    #!/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!"
    ```
  </Tab>

  <Tab title="Database Tools">
    ```bash theme={null}
    #!/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!"
    ```
  </Tab>
</Tabs>

### Best Practices

<AccordionGroup>
  <Accordion title="Use set -e for error handling">
    Always start your script with `set -e` to exit immediately if any command fails:

    ```bash theme={null}
    #!/bin/bash
    set -e
    # Your commands here
    ```

    This prevents the agent from starting work with incomplete dependencies.
  </Accordion>

  <Accordion title="Make scripts idempotent">
    Design scripts to run safely multiple times:

    ```bash theme={null}
    #!/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
    ```
  </Accordion>

  <Accordion title="Cache dependencies when possible">
    Use lock files to speed up installation:

    ```bash theme={null}
    #!/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
    ```
  </Accordion>

  <Accordion title="Log progress clearly">
    Add echo statements to help debug issues:

    ```bash theme={null}
    #!/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!"
    ```
  </Accordion>

  <Accordion title="Keep scripts fast">
    Only install what you need:

    ```bash theme={null}
    #!/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
    ```
  </Accordion>
</AccordionGroup>

## Common Use Cases

### Installing Language Runtimes

<CodeGroup>
  ```bash Python theme={null}
  #!/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
  ```

  ```bash Go theme={null}
  #!/bin/bash
  set -e

  # Install Go 1.21
  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
  echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc

  # Download dependencies
  go mod download
  ```

  ```bash Ruby theme={null}
  #!/bin/bash
  set -e

  # Install Ruby via rbenv
  apt-get update && apt-get install -y rbenv ruby-build

  # Install specific Ruby version
  rbenv install 3.2.0
  rbenv global 3.2.0

  # Install bundler and dependencies
  gem install bundler
  bundle install
  ```
</CodeGroup>

### Installing Build Tools

```bash theme={null}
#!/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

```bash theme={null}
#!/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

<AccordionGroup>
  <Accordion title="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.

    ```bash theme={null}
    #!/bin/bash
    set -e  # Add this!
    ```
  </Accordion>

  <Accordion title="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:

    ```bash theme={null}
    export PATH="/custom/path/bin:$PATH"
    echo 'export PATH="/custom/path/bin:$PATH"' >> ~/.bashrc
    ```
  </Accordion>

  <Accordion title="Permission denied errors">
    Ensure scripts and binaries have execute permissions:

    ```bash theme={null}
    chmod +x /usr/local/bin/mytool
    chmod +x .blocks/post-clone
    ```
  </Accordion>

  <Accordion title="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
  </Accordion>
</AccordionGroup>

## Limitations

<Warning>
  **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.
</Warning>

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

## Next Steps

<CardGroup cols={2}>
  <Card title="Plan Mode" icon="clipboard-list" href="/using-blocks/features/plan-mode">
    Learn how Plan Mode can help design your post-clone script
  </Card>

  <Card title="Multi-Repo Support" icon="folder-tree" href="/using-blocks/features/multi-repo-support">
    Working across multiple repositories with different dependencies
  </Card>

  <Card title="GitHub Integration" icon="github" href="/using-blocks/integrations/github">
    Managing post-clone scripts in GitHub repositories
  </Card>

  <Card title="Skills" icon="terminal" href="/using-blocks/features/skills">
    Create custom skills for common workflows
  </Card>
</CardGroup>