Installation and Setup

If you’re using a Cerebras Wafer-Scale Cluster running in appliance mode, see Running SDK on a Wafer-Scale Cluster.

Request Access

Request access to the Cerebras SDK Singularity container at cerebras.ai/developers/sdk-request. You can also find a repository of example programs on GitHub. Your download includes a tarball (Cerebras-SDK-2.10.0-{build_id}.tar.gz) containing the SDK software and a sha256sum.txt file for verifying the download integrity.

Prerequisites

Before you begin, make sure your system has the following:

Apptainer or SingularityCE — A container platform capable of running Singularity containers. See the Apptainer Quick Start or SingularityCE Quick Start for setup instructions.
Overlay filesystem — Available by default on Linux kernel 3.18 and later. See the kernel documentation for details.
Bash — The Bash shell must be available on your system.

Install the SDK

If you’re on an Apple Silicon Mac, see Apple Silicon Mac installation instead.

Verify the download (optional)

In the directory where you downloaded the tarball, run the checksum verification:

cd /my/install/location
sha256sum --check sha256sum.txt

If the output shows OK, the file is intact.

Extract the SDK

Set environment variables for your install location and tarball path. Both should be absolute paths:

SDK_INSTALL_LOCATION=/my/install/location
SDK_INSTALL_PATH=$SDK_INSTALL_LOCATION/cs_sdk
SDK_TAR_PATH=/path/to/Cerebras-SDK-2.10.0-{build_id}.tar.gz

Create the install directory and extract the tarball:

mkdir -p $SDK_INSTALL_PATH
tar -C $SDK_INSTALL_PATH -xvf $SDK_TAR_PATH

After extraction, your $SDK_INSTALL_PATH directory should contain:

File	Description
`sdk-cbcore-{build_id}.sif`	The SDK container image (~3 GB)
`cslc`	CSL compiler script
`cs_python`	Script for running Python code within the container’s Python environment
`csdb`	Hardware debug tools script
`cs_readelf`	Cerebras alternative to `readelf`
`sdk_debug_shell`	Simulation debug tools, including the smoke test and SDK GUI
`csl-extras-{build_id}.tar.gz`	Example programs, tutorials, and extras (including CSL syntax highlighters for Vim and VS Code)
`cerebras-software-eula.pdf`	End User License Agreement
`sdk-gui-LICENSE.txt`	License for the GUI tool

Add the SDK to your PATH

Add the SDK to your current session and persist it across future sessions:

export PATH=$SDK_INSTALL_PATH:$PATH
echo 'export PATH='$SDK_INSTALL_PATH':$PATH' >> ~/.bashrc

Run the smoke test

Extract the examples and run the smoke test to verify that everything compiles and runs correctly:

cd $SDK_INSTALL_PATH
tar -xzvf csl-extras-{build_id}.tar.gz
sdk_debug_shell smoke csl-extras-{build_id}

A successful test ends with:

SUCCESS!
PASSED
SMOKE CHECK COMPLETED SUCCESSFULLY

To speed up the smoke test and reduce disk usage, set SINGULARITYENV_CSL_SUPPRESS_SIMFAB_TRACE=1 before running it. This skips generating simfab_traces used by the SDK GUI. Unset this variable before running examples you plan to visualize in the GUI.

Verify the SDK Debug GUI (optional)

To confirm the GUI works, run the gemm-collectives_2d example:

cd $SDK_INSTALL_PATH/csl-extras-{build_id}/csl_examples/benchmarks/gemm_collectives_2d
./commands.sh

Then launch the GUI:

sdk_debug_shell visualize

This outputs one or more URLs. Open one in your browser to view the GUI:

Click this link to open URL:  http://<url>:8000/sdk-gui?session_id=...

After selecting a PE, you should see a visualization like this:

Apple Silicon Mac installation

On Apple Silicon Macs, the SDK runs inside a Linux virtual machine powered by Lima. You can use either Rosetta (recommended for performance) or QEMU for x86 emulation. Choose your approach below, then continue with the shared setup steps.

Rosetta (recommended)
QEMU

Tested with Lima >= 2.0.0 and macOS >= 26.2. See the Lima documentation for details.

Install Lima

brew install lima

Create a VM configuration

Save the following as config.yml. This creates an ARM virtual machine with Apptainer installed, using Rosetta to run the x86_64 SDK container. Your Mac’s home directory and /tmp/lima are mounted as writable:

minimumLimaVersion: 2.0.0

containerd:
  system: false
  user: false
provision:
- mode: system
  script: |
    #!/bin/bash
    set -eux -o pipefail
    command -v apptainer >/dev/null 2>&1 && exit 0
    # Workaround for https://github.com/apptainer/apptainer/issues/2027
    echo "kernel.apparmor_restrict_unprivileged_userns = 0" >/etc/sysctl.d/99-userns.conf
    sysctl --system
    # add the "Official PPA for Apptainer"
    add-apt-repository -y ppa:apptainer/ppa
    apt-get update
    apt-get install -y apptainer
probes:
- script: |
    #!/bin/bash
    set -eux -o pipefail
    if ! timeout 30s bash -c "until command -v apptainer >/dev/null 2>&1; do sleep 3; done"; then
      echo >&2 "apptainer is not installed yet"
      exit 1
    fi
  hint: See "/var/log/cloud-init-output.log" in the guest

images:
- location: "https://cloud-images.ubuntu.com/releases/noble/release-20251213/ubuntu-24.04-server-cloudimg-arm64.img"
  arch: "aarch64"
  digest: "sha256:a40713938d74aaec811f74cb1fa8bfcb535d22e26b2a0ca1cc90ad9db898feb9"
- location: https://cloud-images.ubuntu.com/releases/noble/release/ubuntu-24.04-server-cloudimg-arm64.img
  arch: aarch64

mounts:
- location: "~"
  writable: true
- location: "/tmp/lima"
  writable: true

mountType: "virtiofs"

vmOpts:
  vz:
    rosetta:
      enabled: true
      binfmt: true

QEMU x86 emulation is noticeably slower than Rosetta, and emulation bugs are possible. Use Rosetta if your system supports it.

Install Lima and QEMU

brew install lima qemu

Create a VM configuration

Save the following as config.yml. This creates an x86_64 virtual machine with SingularityCE installed. Your Mac’s home directory and /tmp/lima are mounted as writable:

vmType: "qemu"

images:
- location: "https://cloud-images.ubuntu.com/releases/22.04/release-20231130/ubuntu-22.04-server-cloudimg-amd64.img"
  arch: "x86_64"
  digest: "sha256:7edc2eccf1e34df23d9561b721b6fed381c3b6e8c916c91c71bbce7b8488b496"

arch: "x86_64"

cpuType:
  x86_64: "max"

ssh:
  loadDotSSHPubKeys: false

mounts:
- location: "~"
  writable: true
- location: "/tmp/lima"
  writable: true

containerd:
  system: false
  user: false

provision:
- mode: system
  script: |
    #!/bin/bash
    set -eux -o pipefail
    export DEBIAN_FRONTEND=noninteractive
    apt-get update -y && apt install -y squashfs-tools-ng
    wget https://github.com/sylabs/singularity/releases/download/v4.0.2/singularity-ce_4.0.2-jammy_amd64.deb
    apt install -y ./singularity-ce_4.0.2-jammy_amd64.deb

probes:
- script: |
    #!/bin/bash
    set -eux -o pipefail
    if ! timeout 30s bash -c "until command -v singularity >/dev/null 2>&1; do sleep 3; done"; then
      echo >&2 "singularity is not installed yet"
      exit 1
    fi
  hint: See "/var/log/cloud-init-output.log" in the guest

Create the VM and Run the SDK

After completing either option above:

Create the virtual machine

limactl start ./config.yml --name cs_sdk

Start the VM and add the SDK to your PATH

Extract the SDK tarball somewhere under your Mac’s home directory, then start a shell in the VM:

# Start a shell inside the VM
limactl shell cs_sdk

# Add the SDK to your PATH (use the absolute Mac path — the home directory
# inside the VM is different from your Mac's home directory)
export PATH=/Users/your-username/path/to/sdk:$PATH

From here, you can run SDK examples within the VM. Lima automatically forwards ports, so if you launch the SDK GUI inside the VM, you can access it in your Mac’s browser at 127.0.0.1:8000/sdk-gui.

Using Additional Python Packages

The cs_python script runs host code from the Python environment inside the container. To add packages to this environment, save the following helper script as sdk_install_python_package.sh:

#!/bin/bash
 
py_path=$(realpath $1)
package_name=$2
SINGULARITYENV_PYTHONPATH="$(realpath $py_path)"
cs_python -c "
import subprocess
import sys
package='$2'
subprocess.check_call([sys.executable, '-m', 'pip', 'install', '--target=$py_path', package])
"
echo -e "Please do\nexport SINGULARITYENV_PYTHONPATH=\"$SINGULARITYENV_PYTHONPATH\"\nbefore using cs_python"

Then install a package into a local directory:

mkdir MY_LOCAL_PY_PATH
bash /path/to/sdk_install_python_package.sh ./MY_LOCAL_PY_PATH <package-name>

Before running cs_python, set the environment variable so it can find your installed packages:

export SINGULARITYENV_PYTHONPATH=$(realpath $MY_LOCAL_PY_PATH)

Start Here

Development Guides

Debugging

Host API Reference

Request Access

Prerequisites

Install the SDK

Apple Silicon Mac installation

Create the VM and Run the SDK

Using Additional Python Packages

​Request Access

​Prerequisites

​Install the SDK

​Apple Silicon Mac installation

​Create the VM and Run the SDK

​Using Additional Python Packages

Request Access

Prerequisites

Install the SDK

Apple Silicon Mac installation

Create the VM and Run the SDK

Using Additional Python Packages