### Install and Set Up Maelstrom Cluster Components

Source: https://github.com/maelstrom-software/maelstrom/blob/main/README.md

Install Maelstrom worker and broker using `cargo-binstall`. Start the broker on a designated port and subsequently launch workers, connecting them to the broker. This setup enables running tests on a distributed cluster.

```bash
cargo binstall maelstrom-worker maelstrom-broker

```

```bash
maelstrom-broker --port=1234

```

```bash
maelstrom-worker --broker=broker-host:1234

```

--------------------------------

### Install All Maelstrom Binaries with Nix

Source: https://github.com/maelstrom-software/maelstrom/blob/main/doc/book/0.11.0/src/installation.md

Installs all Maelstrom binaries using Nix by referencing the project's flake file. Note that individual binary installation is not supported with this method.

```bash
nix profile install github:maelstrom-software/maelstrom
```

--------------------------------

### Install and Run Maelstrom Tests with Cargo in GitHub Actions

Source: https://github.com/maelstrom-software/maelstrom/blob/main/doc/book/0.13.0/src/github.md

This example demonstrates how to install and configure the `cargo-maelstrom` test runner within a GitHub Actions workflow. After installation, tests can be executed using the standard `cargo maelstrom` command. This action assumes the Maelstrom broker has already been set up in the same job.

```yaml
name: Install and Configure cargo-maelstrom
uses: maelstrom-software/cargo-maelstrom@v1

name: Run Tests
run: cargo maelstrom
```

--------------------------------

### Install Maelstrom Broker from Source with Extra Dependencies

Source: https://github.com/maelstrom-software/maelstrom/blob/main/doc/book/0.11.0/src/installation.md

Installs the `maelstrom-broker` binary from source, which requires additional dependencies like `wasm32-unknown-unknown` target and `wasm-opt` to be installed first.

```bash
rustup target add wasm32-unknown-unknown
cargo install wasm-opt
cargo install maelstrom-broker
```

--------------------------------

### Install Maelstrom Binaries with cargo-binstall

Source: https://github.com/maelstrom-software/maelstrom/blob/main/doc/book/0.11.0/src/installation.md

Installs various Maelstrom binaries using the cargo-binstall tool. This method fetches pre-built binaries from the Maelstrom GitHub releases page.

```bash
cargo binstall maelstrom-run
cargo binstall cargo-maelstrom
cargo binstall maelstrom-go-test
cargo binstall maelstrom-pytest
cargo binstall maelstrom-broker
cargo binstall maelstrom-worker
```

--------------------------------

### Install Maelstrom Binaries from Source with Cargo

Source: https://github.com/maelstrom-software/maelstrom/blob/main/doc/book/0.11.0/src/installation.md

Builds and installs Maelstrom binaries from source using the `cargo install` command. This method requires a Rust toolchain and Cargo.

```bash
cargo install maelstrom-run
cargo install cargo-maelstrom
cargo install maelstrom-go-test
cargo install maelstrom-pytest
cargo install maelstrom-worker
```

--------------------------------

### Install and Run Maelstrom Tests with Go in GitHub Actions

Source: https://github.com/maelstrom-software/maelstrom/blob/main/doc/book/0.13.0/src/github.md

This snippet illustrates the setup for running Maelstrom tests using the `maelstrom-go-test` action in GitHub Actions. It installs and configures the Go test runner, allowing tests to be invoked with the `maelstrom-go-test` command. The Maelstrom broker must be running in the same job prior to this step.

```yaml
name: Install and Configure maelstrom-go-test
uses: maelstrom-software/maelstrom-go-test-action@v1

name: Run Tests
run: maelstrom-go-test
```

--------------------------------

### Install Direnv and Nix-Direnv using Nix Profile

Source: https://github.com/maelstrom-software/maelstrom/blob/main/doc/development-environment.md

Installs `direnv` for automatic environment loading and `nix-direnv` for integrating Direnv with Nix. This setup allows for project-specific environment variables and configurations to be managed automatically.

```bash
nix profile install 'nixpkgs#direnv'
nix profile install 'nixpkgs#nix-direnv'

```

--------------------------------

### Build Maelstrom Broker with Web UI Feature using cargo install

Source: https://github.com/maelstrom-software/maelstrom/blob/main/doc/book/head/src/installation.md

Builds and installs the Maelstrom broker with the optional 'web-ui' feature enabled. This feature provides a basic web dashboard. Requires adding the wasm32-unknown-unknown target and installing wasm-opt.

```bash
rustup target add wasm32-unknown-unknown
cargo install wasm-opt
cargo install maelstrom-broker --features=web-ui
```

--------------------------------

### Configure and Run Maelstrom Broker in GitHub Actions

Source: https://github.com/maelstrom-software/maelstrom/blob/main/doc/book/0.13.0/src/github.md

This snippet shows how to install and start the Maelstrom broker as a background process within a GitHub Actions job. It captures the broker's PID and port, setting them as environment variables for subsequent steps. A post-job handler is scheduled to ensure the broker is gracefully terminated.

```yaml
name: Install Maelstrom Broker
uses: maelstrom-software/maelstrom-broker-action@v1

name: Start Maelstrom Broker
run: |
  TEMPFILE=$(mktemp maelstrom-broker-stderr.XXXXXX)
  maelstrom-broker 2> >(tee "$TEMPFILE" >&2) &
  PID=$!
  PORT=$( \
    tail -f "$TEMPFILE" \
    | awk '/<addr: / { print $0; exit}' \
    | sed -Ee 's/^.*\baddr: [^,]*:([0-9]+),.*$/\1/' \
  )
  echo "MAELSTROM_BROKER_PID=$PID" >> "$GITHUB_ENV"
  echo "MAELSTROM_BROKER_PORT=$PORT" >> "$GITHUB_ENV"
env:
  MAELSTROM_BROKER_ARTIFACT_TRANSFER_STRATEGY: github

name: Schedule Post Handler to Kill Maelstrom Broker
uses: gacts/run-and-post-run@v1
with:
  post: kill -15 $MAELSTROM_BROKER_PID
```

--------------------------------

### Complete Maelstrom CI Workflow Example

Source: https://github.com/maelstrom-software/maelstrom/blob/main/doc/book/head/src/github.md

A comprehensive GitHub Actions workflow demonstrating the setup of the Maelstrom broker, multiple workers, client job execution using both `cargo-maelstrom` and `maelstrom-go-test`, and a guaranteed cluster stop mechanism. This example integrates all components for a full Maelstrom testing pipeline.

```yaml
jobs:
  maelstrom-broker:
    name: Maelstrom Broker
    runs-on: ubuntu-24.04
    steps:
    - name: Install and Run Maelstrom Broker
      uses: maelstrom-software/maelstrom-broker-action@v1

  maelstrom-worker:
    strategy:
      matrix:
        worker-number: [1, 2, 3, 4]
    name: Maelstrom Worker ${{ matrix.worker-number }}
    runs-on: ubuntu-24.04
    steps:
    - name: Install and Run Maelstrom Worker
      uses: maelstrom-software/maelstrom-worker-action@v1

  run-tests-1:
    name: Run Tests 1
    runs-on: ubuntu-24.04
    steps:
    - name: Check Out Repository
      uses: actions/checkout@v4
    - name: Install and Configure cargo-maelstrom
      uses: maelstrom-software/cargo-maelstrom-action@v1
    - name: Run cargo-maelstrom
      run: cargo maelstrom

  run-tests-2:
    name: Run Tests 2
    runs-on: ubuntu-24.04
    steps:
    - name: Check Out Repository
      uses: actions/checkout@v4
    - name: Install and Configure maelstrom-go-test
      uses: maelstrom-software/maelstrom-go-test-action@v1
    - name: Run cargo-maelstrom
      run: maelstrom-go-test

  stop-maelstrom:
    name: Stop Maelstrom Cluster
    runs-on: ubuntu-24.04
    if: ${{ always() }}
    needs: [run-tests-1, run-tests-2]
    steps:
    - name: Install and Configure maelstrom-admin
      uses: maelstrom-software/maelstrom-admin-action@v1
    - name: Stop Maelstrom Cluster
      run: maelstrom-admin stop
```

--------------------------------

### TOML Configuration File Example

Source: https://github.com/maelstrom-software/maelstrom/blob/main/doc/book/0.10.0/src/config.md

Example of a TOML configuration file showing how to set string, number, and boolean values for configuration parameters.

```toml
frob-name = "string"
frob-size = 42
enable-frobs = true
enable-qux = false
```

--------------------------------

### Install Maelstrom Test Runners via cargo-binstall

Source: https://github.com/maelstrom-software/maelstrom/blob/main/README.md

Installs pre-built Maelstrom test runner binaries for Rust, Go, and Python using cargo-binstall. This is the recommended method for easy installation.

```bash
cargo binstall cargo-maelstrom

```

```bash
cargo binstall maelstrom-go-test

```

```bash
cargo binstall maelstrom-pytest

```

--------------------------------

### Install Nix Package Manager

Source: https://github.com/maelstrom-software/maelstrom/blob/main/doc/development-environment.md

Installs the Nix package manager and enables experimental features for command-line operations and flakes. This is the foundational step for managing project dependencies.

```bash
sh <(curl -L https://nixos.org/nix/install) --daemon

```

--------------------------------

### Configure `go test -short` Flag (`short`)

Source: https://github.com/maelstrom-software/maelstrom/blob/main/doc/book/0.13.0/src/go-test/config.md

The `short` configuration option is forwarded to test binaries, instructing long-running tests to reduce their execution time. Refer to `go help testflag` for more details on the `-short` flag and its implications.

```json
{
  "short": true
}
```

--------------------------------

### Configure Python Docker Image in Maelstrom

Source: https://github.com/maelstrom-software/maelstrom/blob/main/doc/book/0.10.0/src/pytest.md

Specifies the Docker image to use for Python tests within the `maelstrom-pytest.toml` file. It includes directives for image name and usage.

```toml
[[directives]]
image.name = "docker://python:3.11-slim"
image.use = ["layers", "environment"]
```

--------------------------------

### Install Git using Nix Profile

Source: https://github.com/maelstrom-software/maelstrom/blob/main/doc/development-environment.md

Installs the Git version control system using the `nix profile` command. This ensures Git is managed by Nix, providing a consistent development environment.

```bash
nix profile install 'nixpkgs#git'

```

--------------------------------

### Specify Pip Packages for Maelstrom Python Environment

Source: https://github.com/maelstrom-software/maelstrom/blob/main/doc/book/0.10.0/src/pytest.md

Defines the Python packages required for testing by listing them in `test-requirements.txt`. Maelstrom automatically includes these packages if a 'python' image is configured. Requires at least the `pytest` package.

```text
pytest==8.1.1
```

--------------------------------

### Include Python Project Files in Maelstrom Layers

Source: https://github.com/maelstrom-software/maelstrom/blob/main/doc/book/0.10.0/src/pytest.md

Configures Maelstrom to include all `.py` files from the project directory as layers. This ensures Python source code is available within the test container. Supports glob patterns for flexibility.

```toml
added_layers = [ { glob = "**.py" } ]
```

--------------------------------

### Example: Pass Extra Arguments via Command Line

Source: https://github.com/maelstrom-software/maelstrom/blob/main/doc/book/0.13.0/src/go-test/config.md

This example demonstrates how to pass extra command-line arguments to the Go test binary using `maelstrom-go-test`. The `--` separator is crucial for distinguishing Maelstrom arguments from the arguments intended for the test binary, such as `-test.parallel 12`.

```bash
maelstrom-go-test -- -test.parallel 12
```

--------------------------------

### --init

Source: https://github.com/maelstrom-software/maelstrom/blob/main/doc/book/0.12.0/src/go-test/cli.md

Initializes a starter maelstrom-go-test.toml configuration file.

```APIDOC
## `--init`

### Description
The `--init` command-line option creates a starter `maelstrom-go-test.toml` file in the current directory. Refer to the documentation for more details on initializing test metadata files.

### Method
N/A (CLI option)

### Endpoint
N/A
```

--------------------------------

### Install Maelstrom Packages on Arch Linux with pacman

Source: https://github.com/maelstrom-software/maelstrom/blob/main/doc/book/head/src/installation.md

Installs Maelstrom packages on Arch Linux using the pacman package manager. This method relies on packages maintained by David Runge. It allows installation of individual Maelstrom components.

```bash
pacman -S cargo-maelstrom
pacman -S maelstrom-go-test
pacman -S maelstrom-pytest
pacman -S maelstrom-run
pacman -S maelstrom-broker
pacman -S maelstrom-worker
pacman -S maelstrom-admin
```

--------------------------------

### Configure Environment Variables with PATH and USER (TOML)

Source: https://github.com/maelstrom-software/maelstrom/blob/main/doc/book/head/src/pytest/spec/containers.md

This example demonstrates prepending to the PATH environment variable and setting the USER. It utilizes the '$prev{PATH}' syntax for inheritance and shows direct assignment for the USER.

```toml
[container.example-1]
parent = "parent"
added_environment = [
    { vars = { PATH = "/foo/bar/bin:$prev{PATH}" }, extend = false },
    { vars = { USER = "bob" }, extend = true },
]
```

--------------------------------

### Example cargo-maelstrom.toml Configuration (Grouped)

Source: https://github.com/maelstrom-software/maelstrom/blob/main/doc/book/0.13.0/src/cargo-maelstrom/spec/format.md

A `cargo-maelstrom.toml` configuration example with elements grouped by type (directives first, then containers). This illustrates an alternative ordering for the same configuration, highlighting that container definitions can appear after their references.

```toml
[[directives]]
filter = "package.equals(maelstrom-worker) && name.starts_with(executor::)"
parent = "executor"

[[directives]]
filter = "package.equals(maelstrom-worker) && name.starts_with(executor::tests::tty_)"
parent = "executor-with-pts"

[containers.executor-with-pts]
parent = "executor"
added_layers = [
    { stubs = [ "dev/pts/" ] },
    { symlinks = [ { link = "/dev/ptmx", target = "/dev/pts/ptmx" } ] },
]
added_mounts = [
    { type = "devpts", mount_point = "/dev/pts" },
]

[containers.executor]
layers = [
    { stubs = [ "{proc,tmp}/", "dev/{null,random,urandom,zero}" ] },
]
mounts = [
    { type = "tmp", mount_point = "/tmp" },
    { type = "proc", mount_point = "/proc" },
    { type = "devices", devices = ["null", "random", "urandom", "zero"] },
]

```

--------------------------------

### Start Maelstrom Broker

Source: https://context7.com/maelstrom-software/maelstrom/llms.txt

Installs and starts the `maelstrom-broker` binary, which acts as the central coordinator for job distribution in a Maelstrom cluster. It can be configured with a specific port, cache size, and network interface binding.

```bash
# Install broker binary
cargo binstall maelstrom-broker

# Start broker on specific port
maelstrom-broker --port=1234

# Start with custom cache size (default 1GB)
maelstrom-broker --port=1234 --cache-size=10GB

# Bind to specific network interface
maelstrom-broker --port=1234 --bind=192.168.1.100
```

--------------------------------

### Go Configuration File Example for Maelstrom-Go-Test

Source: https://github.com/maelstrom-software/maelstrom/blob/main/doc/book/0.12.0/src/SUMMARY.md

Example of a `maelstrom-go-test.toml` file used to configure test runs for go projects. It specifies directives, configurations, and other settings for Maelstrom testing.

```toml
# Example maelstrom-go-test.toml

[defaults]
concurrency = 10

[[directives]]
name = "my_go_test"
path = "tests/my_go_test.go"
concurrency = 5

[configurations.release]
"build.flags" = ["-tags", "production"]

```

--------------------------------

### Environment Variable Examples

Source: https://github.com/maelstrom-software/maelstrom/blob/main/doc/book/0.11.0/src/config.md

Demonstrates setting configuration values using environment variables. Variable names are derived from configuration values in screaming snake case, prefixed by the program name. Supports true/false for booleans.

```bash
MAELSTROM_PROG_FROB_NAME=string
MAELSTROM_PROG_FROB_SIZE=42
MAELSTROM_PROG_ENABLE_FROBS=true
MAELSTROM_PROG_ENABLE_FROBS=false
```

--------------------------------

### Start Maelstrom Workers

Source: https://context7.com/maelstrom-software/maelstrom/llms.txt

Installs and starts `maelstrom-worker` binaries, which execute jobs in containers and report results to the broker. Workers can be configured to connect to a specific broker, set the number of concurrent job slots, and define cache sizes for artifacts.

```bash
# Install worker binary
cargo binstall maelstrom-worker

# Connect worker to broker
maelstrom-worker --broker=broker-host:1234

# Specify number of concurrent job slots
maelstrom-worker --broker=broker-host:1234 --slots=8

# Set cache size for artifacts
maelstrom-worker --broker=broker-host:1234 --cache-size=50GB
```

--------------------------------

### Extract Latest Maelstrom Binary Release

Source: https://github.com/maelstrom-software/maelstrom/blob/main/doc/book/0.11.0/src/installation.md

Downloads and extracts the latest pre-built `cargo-maelstrom` binary for Linux x86-64 architecture directly from GitHub releases. This is an alternative if cargo-binstall is not available.

```bash
wget -q -O - https://github.com/maelstrom-software/maelstrom/releases/latest/download/cargo-maelstrom-x86_64-unknown-linux-gnu.tgz | tar xzf -
```

--------------------------------

### Initialize Maelstrom Configuration File

Source: https://github.com/maelstrom-software/maelstrom/blob/main/doc/book/0.12.0/src/go-test/cli.md

The --init command-line option is used to create a starter maelstrom-go-test.toml configuration file. This provides a basic template for users to begin configuring their tests.

```bash
maelstrom-go-test --init
```