{"id":8876,"library":"beaker-gantry","title":"Beaker Gantry","description":"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.","status":"active","version":"3.7.0","language":"en","source_language":"en","source_url":"https://github.com/allenai/beaker-gantry","tags":["CLI","experiment management","machine learning","Beaker","automation","Docker-free","research"],"install":[{"cmd":"pip install beaker-gantry","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Gantry is built on top of the Beaker Python client.","package":"beaker-py","optional":false}],"imports":[{"note":"Base exception for Gantry-specific errors.","symbol":"GantryError","correct":"from gantry import GantryError"},{"note":"Used to attach metrics to Beaker experiments programmatically from within a running experiment.","symbol":"write_metrics","correct":"from gantry.api import write_metrics"}],"quickstart":{"code":"import os\n\n# Ensure BEAKER_TOKEN is set in your environment\nBEAKER_TOKEN = os.environ.get('BEAKER_TOKEN', 'YOUR_BEAKER_TOKEN')\nif not BEAKER_TOKEN or BEAKER_TOKEN == 'YOUR_BEAKER_TOKEN':\n    print(\"Warning: Please set the BEAKER_TOKEN environment variable.\")\n    print(\"You can obtain it from your Beaker profile page.\")\nelse:\n    print(\"Beaker token is set. To run an experiment, ensure you are in a Git repository\")\n    print(\"and execute: gantry run --show-logs -- python -c 'print(\\\"Hello, Beaker Gantry!\\\")'\")\n    print(\"For programmatic metric logging from within an experiment:\")\n    print(\"  from gantry.api import write_metrics\")\n    print(\"  write_metrics({'accuracy': 0.95, 'loss': 0.05})\")","lang":"python","description":"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`."},"warnings":[{"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+).","message":"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`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Set the `BEAKER_TOKEN` environment variable (e.g., `export BEAKER_TOKEN='your_token'`) or ensure `beaker-py` can find a valid configuration file.","message":"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`).","severity":"breaking","affected_versions":"All versions"},{"fix":"Always use `--` before your command and its arguments, e.g., `gantry run --show-logs -- python my_script.py --arg value`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Generate a GitHub PAT with `repo` scope and provide it when prompted by Gantry, or set it using `gantry config set-gh-token`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure there are no trailing or leading spaces in CLI options and arguments. For example, use `--post-setup` instead of `--post-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.","error":"Error: No such option: --post-setup (Possible options: --post-setup, --pre-setup, --skip-tcpxo-setup)"},{"fix":"Commit all local changes (`git add . && git commit -m '...'`) and push them to your remote repository (`git push`) before executing `gantry run`.","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.","error":"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."},{"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`.","cause":"The Gantry CLI (and underlying `beaker-py` client) cannot authenticate with the Beaker service because it cannot find an API token.","error":"beaker.client.exceptions.BeakerConfigurationError: Missing Beaker API token. Please set the BEAKER_TOKEN environment variable or configure the Beaker CLI."}]}