Beaker Gantry

3.7.0 · active · verified Thu Apr 16

Beaker Gantry (beaker-gantry) is a command-line interface (CLI) tool and Python library that streamlines running Python experiments in Beaker. It manages containers and boilerplate, eliminating the need for manual Dockerfile creation or complex Beaker YAML experiment specifications. Gantry automatically handles environment setup, repository cloning, and workload management at runtime, making it ideal for Python-based batch jobs from rapidly changing Git repositories. It is actively maintained with frequent updates.

Common errors

```
Error: No such option: --post-setup (Possible options: --post-setup, --pre-setup, --skip-tcpxo-setup)
```
cause This error often occurs when there's an unintended space character after a command-line option, like `gantry run --post-setup ` (with a trailing space). The CLI parser treats the space-padded option as a different, non-existent option.

fix Ensure there are no trailing or leading spaces in CLI options and arguments. For example, use `--post-setup` instead of `--post-setup `.
```
GantryError: DirtyRepoError: Repository contains uncommitted changes. Please commit your changes before running Gantry. OR GantryError: UnpushedChangesError: Repository contains unpushed changes. Please push your changes before running Gantry.
```
cause Gantry attempts to create an exact replica of your Git repository's state on Beaker. If there are uncommitted or unpushed changes locally, Gantry will prevent the experiment from running to ensure reproducibility.

fix Commit all local changes (`git add . && git commit -m '...'`) and push them to your remote repository (`git push`) before executing `gantry run`.
```
beaker.client.exceptions.BeakerConfigurationError: Missing Beaker API token. Please set the BEAKER_TOKEN environment variable or configure the Beaker CLI.
```
cause The Gantry CLI (and underlying `beaker-py` client) cannot authenticate with the Beaker service because it cannot find an API token.

fix Obtain a Beaker API token from your Beaker profile page and set it as an environment variable (e.g., `export BEAKER_TOKEN='your_token'`) in your shell, or configure the Beaker CLI client using `beaker configure`.

Warnings

gotcha All `gantry` CLI commands must be invoked from the root directory of your Git repository. Running from a subdirectory will likely result in a `GitError` or `DirtyRepoError`.
Fix: Change directory to the root of your Git repository before executing `gantry` commands. Alternatively, use the `--remote` option for non-repository contexts (Gantry 3.5.3+).
breaking Gantry relies on Beaker authentication. You must have the `BEAKER_TOKEN` environment variable set or the Beaker command-line client configured locally (e.g., `$HOME/.beaker/config.yml`).
Fix: Set the `BEAKER_TOKEN` environment variable (e.g., `export BEAKER_TOKEN='your_token'`) or ensure `beaker-py` can find a valid configuration file.
gotcha When providing a command and its arguments to `gantry run`, use `--` to clearly separate `gantry`'s own options from the command's arguments. Without it, Gantry might misinterpret your command's options as its own.
Fix: Always use `--` before your command and its arguments, e.g., `gantry run --show-logs -- python my_script.py --arg value`.
gotcha For private Git repositories, Gantry requires a GitHub Personal Access Token (PAT) with `repo` scope to clone your repository on Beaker. Gantry will prompt you for this token the first time it's needed.
Fix: Generate a GitHub PAT with `repo` scope and provide it when prompted by Gantry, or set it using `gantry config set-gh-token`.
gotcha To save results or metrics from an experiment, your experiment should write files to the `/results` directory within the Beaker container. This directory is automatically configured to be persisted as a Beaker dataset.
Fix: Modify your experiment code to output relevant data to the path specified by the `RESULTS_DIR` environment variable (which defaults to `/results` in the container), or use `from gantry.api import write_metrics` for programmatic metric logging.

Install

pip install beaker-gantry Install with pip

Imports

GantryError
```
from gantry import GantryError
```
Base exception for Gantry-specific errors.
write_metrics
```
from gantry.api import write_metrics
```
Used to attach metrics to Beaker experiments programmatically from within a running experiment.

Quickstart

While primarily a CLI tool, `beaker-gantry` interacts with Beaker. This quickstart demonstrates how to verify your Beaker token (a prerequisite) and shows the most basic CLI command to run an experiment. It also hints at the Python API for logging metrics from within a running experiment. Ensure you have committed and pushed your changes to a Git repository before running `gantry run`.

import os

# Ensure BEAKER_TOKEN is set in your environment
BEAKER_TOKEN = os.environ.get('BEAKER_TOKEN', 'YOUR_BEAKER_TOKEN')
if not BEAKER_TOKEN or BEAKER_TOKEN == 'YOUR_BEAKER_TOKEN':
    print("Warning: Please set the BEAKER_TOKEN environment variable.")
    print("You can obtain it from your Beaker profile page.")
else:
    print("Beaker token is set. To run an experiment, ensure you are in a Git repository")
    print("and execute: gantry run --show-logs -- python -c 'print(\"Hello, Beaker Gantry!\")'")
    print("For programmatic metric logging from within an experiment:")
    print("  from gantry.api import write_metrics")
    print("  write_metrics({'accuracy': 0.95, 'loss': 0.05})")

view raw JSON →